# 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).

TIP

Visit the Manage access to CDF getting started course for an introduction to the the technology behind CDF authentication and authorization.

This article explains the design principles and best practices for configuring Azure AD with to manage access to CDF.

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.

CDF group mappings for service applications

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 group mappings for users

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.

NOTE

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
  • Generic read/write access to assets, time series, events, sequences, files and RAW
  • Scoped access to through data sets, one group per dataset or related datasets.
  • Scoped access to RAW databases and tables (access to certain databases or tables)
Create an AD group per distinct set of capabilities, and assign group memberships to the service principal in AD.
  • Extractor type and data source
  • Scheduled scripts
  • Transformations, split into multiple for different transformation categories / use cases
  • Cognite Functions - long running scheduled functions (split per needed access)
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.

Claim Description Expected value
iss Issuer of the JWT. URI and path from the IdP from which the JWT was issued.
aud Audience of the JWT (intended recipient). URI of the service requiring authentication.
exp Expiration time of the JWT. Datetime stamp.
iat Issued at Time of the JWT. Datetime stamp.
nbf Not Before Time of the JWT (before which the token should not be accepted). Datetime stamp.
sub Subject of the JWT (the user). User name from IdP.
scp Scope of the JWT (attribute inherited from the scopes defined for the subject in the IdP). Text field, defined in ADFS.
groups 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.

Last Updated: 4/30/2021, 12:42:57 PM