# Design princliples and best practices for authentication and authorization
By connecting Cognite Data Fusion (CDF) to your identity provider (IdP), you can use the IdP framework to manage access to CDF data securely. We currently support Microsoft's Azure Active Directory (Azure AD).
Visit the Manage access to CDF getting started course for an introduction to the the technology behind CDF authentication and authorization.
In this article:
# Design principles: OpenID Connect and CDF
This section outlines the design principles for using Azure AD's OpenID Connect implementation to manage access to CDF.
# Authentication and applications
Authentication is about determining the identity of a person or application trying to access a resource. It establishes if they are who they say they are.
Applications and users need to get a token from the IdP to authenticate and get access to CDF. The token is a very targeted key that grants access for an identity (a user identity for people, a service principal for applications.)
To learn how to allow users to sign in to CDF and Cognite apps with their existing organizational ID, visit Register the Cognite API and applications in Azure AD.
# Authorization and groups
Authorization is about determining what level of access an authenticated person or application has. It specifies what data they're allowed to access and what they can do with it.
Access to CDF data and capabilities in CDF projects are governed by policies defined in the customer’s IdP and by resolving the policies into one or more CDF groups where the access scope is defined. The policies are specified in the claims in the tokens that the IdP issues.
You can configure CDF groups to use any OAUTH v2.0 claim to determine access. The most commonly used claim type is
groups, which is also the claim type recommended by Cognite.
You need to create AD groups to govern access rights to CDF for applications (service principals). For each security group a service service principal is a member of, a groups claim is created and entered into an access token for the service principal.
# CDF group mappings for service applications
The configuration tasks to provide the appropriate claims and claim values for service applications can vary between IdPs, but the relationships between the entities illustrated above describe the principle that you should apply.
To use the most appropriate object (security groups) attributes to populate a groups claim’s value, the service application must be associated to the security group. The configuration method to achieve this varies between Azure Active Directory and on-premises AD/ADFS, however the principle outlined above remains the same.
# CDF group mappings for users
In large organisations, users are likely to be members of multiple security groups.
CDF has a limit of 50 groups claims in a single access token. You may need to define rules on the IdP to limit the number of claims that are entered into the token. You should create rules that filter the CDF specific security groups such that only claims values relevant to CDF are included in the access token.
# Best practices: Register applications and set up groups
This section outlines the best practices for registering and configuring applications to authenticate with CDF. You'll also find information about setting up groups to authorize what data users and applications can access and what they can do with the data.
# Register and configure applications for authentication
The general rules for applications are:
Service applications (applications that have no human interaction, for example extractors) use the client credentials authentication flow. Service applications are sometimes referred to as daemon applications. You need to register each service application separately to provide specific access for different service applications and distinguish between security contexts.
User applications (applications that require human interaction, for example the CDF portal application, connectors, and web applications) uses either the authorization code grant flow, or the implicit grant flow, depending on the implementation choices of the client application. Where supported, you should use PKCE.
Visit Register and configure components and applications to find the detailed configuration and registration steps for Cognite apps and components.
When you register applications using the client credentials flow, you should NOT share client IDs and secrets across multiple applications, even if the applications have common authentication requirements in CDF. CDF applies rate-limiting at the individual login level, and applications can end up being throttled. Sharing client IDs and secrets across multiple applications can also cause issues with audit logs, with events from multiple entities being identified under a common client ID.
# Set up groups for authorization
|I want to set up||Do this|
| ||Create an AD group per distinct set of capabilities, and assign group memberships to the service principal in AD.|
| ||Create one AD group per service principal and assign the CDF linked group the capabilities required by the service principal.|
# Tokens and claims
Within a token, there are multiple claims used to assert pieces of information about a subject. Tokens issued to authenticate and authorize a subject to access CDF should contain the following claims, some of which are reserved, and the others are custom configured. See this article (opens new window) for more information about tokens and claims.
The table below shows the minimum required claims in a token for CDF to authenticate and authorize the subject.
| ||Issuer of the JWT.||URI and path from the IdP from which the JWT was issued.|
| ||Audience of the JWT (intended recipient).||URI of the service requiring authentication.|
| ||Expiration time of the JWT.||Datetime stamp.|
| ||Issued at Time of the JWT.||Datetime stamp.|
| ||Not Before Time of the JWT (before which the token should not be accepted).||Datetime stamp.|
| ||Subject of the JWT (the user).||User name from IdP.|
| ||Scope of the JWT (attribute inherited from the scopes defined for the subject in the IdP).||Text field, defined in ADFS.|
| ||Groups of the JWT (attribute inherited from the groups defined for the subject in the IdP).||Object ID of a security group.|
For CDF to use these claims as part of its authorization mechanism, you need follow the steps in the Set up Azure AD and CDF groups to control access article to use the AD group's object ID to map CDF groups to the group claim in the token.
As you create or change groups in CDF, make sure that you also maintain the mappings.