# Design principles for OpenID Connect and CDF

This article outlines the design principles for OpenID Connect in Cognite Data Fusion and Cognite applications.

In this article:

# Authentication

The general rules are:

  • Service applications (applications that have no human interaction, meaning no username and password can be entered, for example extractors) will use the client-credentials authentication flow. Service applications may also be referred to as daemon applications.

  • User applications (applications that require human interaction, for example the CDF portal application, connectors, and web applications) will either use 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.

The configuration of the application registration on the identity provider (IdP) varies with the type of authentication flow the registration has to support. It is important to know the type of flow implemented for the application.

The table below provides a non-exhaustive list of applications and the flows they use:

Application Client credentials Authorization code grant Implicit grant On behalf of
The CDF portal x
Extractors x
Transformations x Planned
Functions x x
Grafana x
Power BI x
Excel x
Postman x x x


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.

# Authorization

Access to CDF data and capabilities in CDF projects are governed by policies defined in the customer’s IdP by resolving the policies into one or more CDF groups where the access scope is defined.

These policies can be processed and resolved in various ways in the IdP, and are embodied in OAUTH2 token claims in a token that is issued by the IdP.

CDF groups can be configured to use any type of OAUTH2 claim to determine access. The most commonly used claim type is groups, which is also the claim type recommended by Cognite.

CDF groups can only be matched against a single claim value per CDF group.

# IdP configuration

In Azure Active Directory, it is typical to use security groups for user and service accounts (applications?) as a means to determine access privileges. For each security group that a user or service account is a member of, a groups claim will be created and entered into an access token for the user (typically with the SID of the security group as the value for each claim). The figures below illustrate the relationships between these objects.

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

See the best practice guide for detailed configuration examples.

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

See the best practice guide for detailed configuration examples.

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