Authenticating with the Cognite Toolkit

This article shows two ways to authenticate to the Cognite Toolkit. Data engineers sign in as themselves. Cognite Toolkit administrators configure a service account for CI/CD. Install the CLI first. See Set up locally. To register the identity provider application and client secret, see Authentication and authorization.

Authenticate as a data engineer

To sign in as yourself, use a persisted Cognite identity provider (CogIdP) session. Run:

cdf auth login

Sign-in flow

$ cdf auth login
? Enter your organization name my_organization
Opening browser for authentication...
Signed in.
? Select the CDF project to use with the toolkit my_organization-dev — cdf_cluster
? Do you want to save these to .env file for next time? Yes

The command opens a browser so you can sign in. It then asks which CDF project to use. Save the project and cluster to .env so the Cognite Toolkit selects them the next time you run a command.

Check your authentication

Check your authentication:

cdf auth status --verbose --show-missing

The command prints whether you are signed in, the identity provider, the project, and when the access token expires. It then lists each CDF project you can access, how many capabilities you have there, and which groups you belong to.--verbose prints every capability on the token. --show-missing adds a row for every Cognite Toolkit resource. Read and Write show the capabilities behind that access. No access means the token cannot read or write that resource type.

Sign out

To sign out, run:

cdf auth logout

This removes the persisted CogIdP session. Sign in again before the next Cognite Toolkit command that needs CDF.

Authenticate as a Cognite Toolkit administrator

Create the identity provider application and store its client ID and client secret before these steps. See Authentication and authorization.

Create the .env file

A Cognite Toolkit administrator uses credentials that a CI/CD pipeline can reuse. Run:

cdf auth init

The wizard writes a .env file and checks that the credentials can reach CDF.

Init flow

$ cdf auth init
? Choose the provider (Who authenticates you?) entra_id: Use Microsoft Entra ID to authenticate
? Choose the login flow (How do you going to authenticate?) client_credentials: Use a service principal with client ID and secret (for
CI/CD or automated workloads)
? Enter the CDF cluster (e.g. westeurope-1) my_cluster
? Enter the CDF project my_project
? Enter the client id: my_client_id
? Enter the client secret: *****
? Enter the Tenant id for Microsoft Entra ID (e.g. 00000000-0000-0000-0000-000000000000 or mytenant.onmicrosoft.com): my_tenant_id
Additional variables:
  CDF_URL=https://my_cluster.cognitedata.com
  IDP_TOKEN_URL=https://login.microsoftonline.com/my_tenant_id/oauth2/v2.0/token
  IDP_AUDIENCE=https://my_cluster.cognitedata.com
  IDP_SCOPES=['https://my_cluster.cognitedata.com/.default']
  CDF_CLIENT_TIMEOUT=60
  CDF_CLIENT_MAX_WORKERS=5
? Do you want to change any of these variables? No
? Do you want to save these to .env file for next time? Yes
The credentials are valid.

The credentials are valid. means the Cognite Toolkit exchanged the client credentials for a token. The .env file contains the client secret. Do not commit it.

Create the Cognite Toolkit group

cdf auth verify does not create the identity provider application. It checks the CDF group that the service account should use, and can create or update that group.The group name is fixed: cognite_toolkit_service_principal. The service account should be a member of only that group, and the group should be able to manage the resources the Cognite Toolkit deploys.Run:

cdf auth verify

If the group does not exist, the wizard asks whether to create it and for the identity provider group ID (sourceId). If the group exists and is missing capabilities, the wizard lists the resources those capabilities unlock and asks whether to add them.

Update authorization

When a newer Cognite Toolkit version supports more resources, run cdf auth verify again. The command compares the group with the capabilities the current CLI expects:

Update authorization

...
INFO: The missing capabilities are required for the following resources:
    - integration configs
    - signal sinks
    - schema mappings
    - signal subscriptions
    - integrations
    - SAP instances
    - SAP endpoints
? Do you want to update the group with the missing capabilities? (Y/n)

Accept the prompt to add the missing capabilities to cognite_toolkit_service_principal. Deploy and clean can then manage the new resource types.

Next steps

Initialize a project with these credentials. See Initializing a Cognite Toolkit project. Build and deploy after the credentials can write the resources in your modules. See Building configurations.

​Authenticate as a data engineer

​Authenticate as a Cognite Toolkit administrator

​Next steps

Authenticate as a data engineer

Authenticate as a Cognite Toolkit administrator

Next steps