# Authentication flow details

Cognite Data Fusion (CDF) uses both OAuth 2.0 (opens new window) and OpenID Connect (opens new window) protocols to authenticate and authorize users and applications.

Identity providers (IdPs) issue OAuth 2.0/OIDC tokens in the JSON Web Tokens format (JWT (opens new window), pronounced "jot"). Users, services, and applications are responsible for obtaining the appropriate JWT from the IdP to access the Cognite API.

The way these tokens are granted may vary, depending on the software vendor's implementation. OAuth 2.0 specifies five types of grants designed to satisfy different use cases. In this unit, we are concerned with the Authorization Code Grant, (to authenticate and authorize users), the Implicit Grant, and the Client Credentials Grant (to authenticate and authorize extractors).

Let's take a closer look at how these grants work.

# Authorization code grant

This type of grant is the most commonly used in OAuth 2.0 deployments. It is geared toward a user (resource owner) using an application to perform some form of action that first requires authentication and authorization.

The diagram below illustrates the communications flow in this grant type. Note that when Open ID Connect is implanted with OAuth 2.0, an ID token is returned along with the access token (denoted in the flow in brackets).

Authorization code grant

# Implicit grant

The implicit grant is similar to the authorization code grant with two distinct differences.

Firstly, it is intended for user-agent-based clients (e.g., single-page web apps) that can't keep a client secret because all of the application code and storage are easily accessible.

Secondly, instead of the authorization server returning an authorization code that is exchanged for an access token, the authorization server returns an access token.

Implicit grant

# Client credentials grant

Use this type of grant when authentication of system-to-system communications is required and where a user's specific permission is not required to perform its functions. Extractors must authenticate before writing data to CDF and follow this pattern and therefore authenticate using this method.

Because it doesn't need user interaction, this grant type flow is simplified, per the diagram below.

This grant type is critical to successfully implement userless software services such as extractors, as they meet the need for these applications to be able to authenticate without any user interaction (beyond the initial configuration).

Client credentials grant

# Token attributes

Let's also have a look at the token attributes that we are configuring for.

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 Manage groups 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.

# Troubleshooting

If there are any issues with a user's authentication, you can retrieve and read issued JWTs from a web browser using Networking section of the Developer Tools. By default, the content of the claims in the token is encoded in a non-human readable format. To read the token content, you need to paste it into a JWT decoding tool such as jwt.ms (opens new window).

Check that the token contains the claims listed above, and that the values within the token match the expected values defined in CDF (as it relates to group SIDs specifically).

Below is an example of an OAuth 2.0/OIDC token issued from a Microsoft Azure AD IdP, containing all mandatory information to authenticate the user using the CDF portal application.

{
  "aud": "https://openfield.cognitedata.com",
  "iss": "https://sts.windows.net/~~~~~~~~-~~~~-~~~~-~~~~-~~~~~~~~~~~~5/",
  "iat": 1615211873,
  "nbf": 1615211873,
  "exp": 1615215773,
  "acr": "1",
  "aio": "AZQAa/8TAAAAyJhgrQQDIeLdV6L8ihHRav6lQANXu27jnkK5Y9x+tskrnZgw1mBcZJ8xVcPDWJso/WOop60PruNM4XA14b0H1wrwDX4+q5YX9tC6O6Dx7axTg7Yx3kRfScjO3WBPFRqRp0yPsQ+l8KdcO59FODEaTcLQeBqR9gSZrK/VylSkJ62Cp+47MUnZWmeSC5pX4nR4",
  "amr": ["rsa", "mfa"],
  "appid": "9f039f43-cd64-4d32-abc1-333ca411e5f9",
  "appidacr": "0",
  "email": "glen.sykes@example.com",
  "family_name": "Sykes",
  "given_name": "Glen",
  "groups": [
    "73d09ef9-1295-4193-af7b-da134dfaca70",
    "f5620625-57b9-47fc-82d9-df3df8b2950e"
  ],
  "idp": "https://sts.windows.net/a9ae5b54-3600-4917-a9dc-3020723360b3/",
  "ipaddr": "~~.~~.~~~.~~",
  "name": "Glen Sykes",
  "oid": "b45a1671-9ee5-4810-a4a4-1fdc7c20d8a1",
  "rh": "0.AAAAH7vyMKEox0aobgCZRWEZZUOfA59kzTJNq8EzPKQR5fl6AHw.",
  "scp": "IDENTITY user_impersonation",
  "sub": "mp9krYK2S_QjiFWwTcr-kONiQX4R2Yfb_ww6wCw_Yx8",
  "tid": "30f2bb1f-28a1-46c7-a86e-009945611965",
  "unique_name": "glen.sykes@example.com",
  "uti": "MjCUJzWVzE2AMQkcHtw6AA",
  "ver": "1.0"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Last Updated: 4/23/2021, 1:20:23 PM