Authentication flows
Cognite Data Fusion (CDF) uses OAuth 2.0 and OpenID Connect protocols to authenticate and authorize users and applications.
Identity providers (IdPs) issue OAuth 2.0/OIDC tokens in the JSON Web Tokens format (JWT, 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. For CDF, the relevant grants are:
- The Authorization code grant and the Implicit grant (to authenticate and authorize user applications).
- The Client credentials grant and On behalf of (to authenticate and authorize service applications).
Authorization code grant
This type of grant is the most commonly used in OAuth 2.0 deployments. It's geared toward a user (resource owner) using an application to perform some action that first requires authentication and authorization. The application or client can run for an extended period and needs both the client credentials AND your interactive approval. This flow allows the app to both get a token and a refresh token and to continue to get renewed access without your approval. We refer to this OAuth2 communication flow as an authorization code grant with PKCE.
The diagram below illustrates the communications flow in this grant type. 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).
Learn more: Microsoft identity platform and authorization code flow
Implicit grant
In this flow, you have to interact as part of the sign-in process to approve that the application can get a token on your behalf. This token is time-limited, but the application will NOT get a refresh token. When the token expires, the application has to recheck with Microsoft Entra ID (ME-ID) to see if you are signed in to ME-ID in your browser. If not, it will prompt you to sign in again. If you're signed in and the session hasn't timed out (dependent on the organization's security policies), the application will silently get another token in the background.
The implicit grant is similar to the authorization code grant, with two distinct differences.
-
Firstly, it's intended for user-agent-based clients (such as single-page web apps) that can't keep a client secret because all the application code and storage are easily accessible.
-
Secondly, instead of the authorization server returning an authorization code that's exchanged for an access token, the authorization server returns an access token.
Learn more: Microsoft identity platform and implicit grant flow
Client credentials grant
Use this type of grant when authentication of system-to-system communications is required and where a user's specific permission isn't required to perform its functions. Applications must authenticate before writing data to CDF. For example, you have a Python script running locally on your computer, it's secure, and has a start and a stop time. However, you expect it to run for several hours, so you don't want to sit there and wait. You also don't want it to run as you since it will only operate on some of the data in CDF, and you want to ensure that the script runs with the least number of privileges to avoid that something bad happens if you have made a mistake in the script.
In the client credentials grant flow the ME-ID app registration gives you a client id and a client secret. You configure your application with these values, and the application interacts with the CDF project and the ME-ID instance to get a time-limited token. As long as you secure your script, intercepting the communications will only yield a token that's not valid for long. The Python app also gets a refresh token that it can use to get a new token. This can continue for days and months.
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).
Learn more: Microsoft identity platform and client credentials flow