Credential Providers

class cognite.client.credentials.CredentialProvider(*args, **kwargs)

classmethod load(config: dict[str, Any] | str) → CredentialProvider

Load a credential provider object from a YAML/JSON string or dict.

Note

The dictionary must contain exactly one top level key, which is the type of the credential provider and must be one of the following strings: "token", "client_credentials", "interactive", "device_code", "client_certificate". The value of the key is a dictionary containing the configuration for the credential provider.

Parameters: config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing the configuration for the credential provider.
Returns: Initialized credential provider of the specified type.
Return type: CredentialProvider

Examples

Get a token credential provider:

>>> from cognite.client.credentials import CredentialProvider
>>> config = {"token": "my secret token"}
>>> credentials = CredentialProvider.load(config)

Get a client credential provider:

>>> import os
>>> config = {
...     "client_credentials": {
...         "client_id": "abcd",
...         "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...         "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...         "scopes": ["https://api.cognitedata.com/.default"],
...     }
... }
>>> credentials = CredentialProvider.load(config)

class cognite.client.credentials.Token(token: str | collections.abc.Callable[[], str])

Token credential provider

Parameters: token (str | Callable[[], str]) – A token or a token factory.

Examples

>>> from cognite.client.credentials import Token
>>> token_provider = Token("my secret token")
>>> token_factory_provider = Token(lambda: "my secret token")

Note

If you pass in a callable, we will expect that you supplied a function that may do a token refresh under the hood, so it will be called while holding a thread lock (threading.Lock()).

classmethod load(config: dict[str, str | collections.abc.Callable[[], str]] | str) → Token

Load a token credential provider object from a YAML/JSON string or dict.

Parameters: config (dict[str, str | Callable[[], str]] | str) – A dictionary or YAML/JSON string containing configuration values defined in the Token class.
Returns: Initialized token credential provider.
Return type: Token

Note

A callable token is not supported if passing in a yaml string.

Examples

>>> from cognite.client.credentials import Token
>>> credentials = Token.load({"token": "my secret token"})

class cognite.client.credentials.OAuthClientCredentials(token_url: str, client_id: str, client_secret: str, scopes: list[str], token_expiry_leeway_seconds: int = 30, **token_custom_args: Any)

OAuth credential provider for the “Client Credentials” flow.

Parameters

token_url (str) – OAuth token url
client_id (str) – Your application’s client id.
client_secret (str) – Your application’s client secret
scopes (list[str]) – A list of scopes.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec
**token_custom_args (Any) – Optional additional arguments to pass as query parameters to the token fetch request.

Examples

>>> from cognite.client.credentials import OAuthClientCredentials
>>> import os
>>> oauth_provider = OAuthClientCredentials(
...     token_url="https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...     client_id="abcd",
...     client_secret=os.environ["OAUTH_CLIENT_SECRET"],
...     scopes=["https://greenfield.cognitedata.com/.default"],
...     # Any additional IDP-specific token args. e.g.
...     audience="some-audience"
... )

classmethod load(config: dict[str, Any] | str) → OAuthClientCredentials

Load a OAuth client credentials credential provider object from a YAML/JSON string or dict.

Parameters: config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the OAuthClientCredentials class.
Returns: Initialized OAuthClientCredentials credential provider.
Return type: OAuthClientCredentials

Examples

>>> from cognite.client.credentials import OAuthClientCredentials
>>> import os
>>> config = {
...     "token_url": "https://login.microsoftonline.com/xyz/oauth2/v2.0/token",
...     "client_id": "abcd",
...     "client_secret": os.environ["OAUTH_CLIENT_SECRET"],
...     "scopes": ["https://greenfield.cognitedata.com/.default"],
...     "audience": "some-audience"
... }
>>> credentials = OAuthClientCredentials.load(config)

classmethod default_for_azure_ad(tenant_id: str, client_id: str, client_secret: str, cdf_cluster: str, token_expiry_leeway_seconds: int = 30, **token_custom_args: Any) → OAuthClientCredentials

Create an OAuthClientCredentials instance for Azure with default token URL and scopes.

The default configuration creates the URLs based on the tenant id and cluster/oauth2/v2.0/token:

Token URL: “https://login.microsoftonline.com/{tenant_id}”
Scopes: [f”https://{cdf_cluster}.cognitedata.com/.default”]

Parameters

tenant_id (str) – The Azure tenant id
client_id (str) – Your application’s client id.
client_secret (str) – Your application’s client secret.
cdf_cluster (str) – The CDF cluster where the CDF project is located.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec
**token_custom_args (Any) – Optional additional arguments to pass as query parameters to the token fetch request.

Returns

An OAuthClientCredentials instance

Return type

OAuthClientCredentials

class cognite.client.credentials.OAuthInteractive(authority_url: str, client_id: str, scopes: list[str], redirect_port: int = 53000, token_cache_path: Optional[Path] = None, token_expiry_leeway_seconds: int = 30)

OAuth credential provider for an interactive login flow.

Make sure you have http://localhost:port in Redirect URI in App Registration as type “Mobile and desktop applications”.

Parameters

authority_url (str) – OAuth authority url
client_id (str) – Your application’s client id.
scopes (list[str]) – A list of scopes.
redirect_port (int) – Redirect port defaults to 53000.
token_cache_path (Path | None) – Location to store token cache, defaults to os temp directory/cognitetokencache.{client_id}.bin.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec

Examples

>>> from cognite.client.credentials import OAuthInteractive
>>> oauth_provider = OAuthInteractive(
...     authority_url="https://login.microsoftonline.com/xyz",
...     client_id="abcd",
...     scopes=["https://greenfield.cognitedata.com/.default"],
... )

classmethod load(config: dict[str, Any] | str) → OAuthInteractive

Load a OAuth interactive credential provider object from a YAML/JSON string or dict.

Parameters: config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the OAuthInteractive class.
Returns: Initialized OAuthInteractive credential provider.
Return type: OAuthInteractive

Examples

>>> from cognite.client.credentials import OAuthInteractive
>>> config = {
...     "authority_url": "https://login.microsoftonline.com/xyz",
...     "client_id": "abcd",
...     "scopes": ["https://greenfield.cognitedata.com/.default"],
... }
>>> credentials = OAuthInteractive.load(config)

classmethod default_for_azure_ad(tenant_id: str, client_id: str, cdf_cluster: str, token_expiry_leeway_seconds: int = 30, **token_custom_args: Any) → OAuthInteractive

Create an OAuthClientCredentials instance for Azure with default token URL and scopes.

The default configuration creates the URLs based on the tenant id and cluster:

Authority URL: “https://login.microsoftonline.com/{tenant_id}”
Scopes: [f”https://{cdf_cluster}.cognitedata.com/.default”]

Parameters

tenant_id (str) – The Azure tenant id
client_id (str) – Your application’s client id.
cdf_cluster (str) – The CDF cluster where the CDF project is located.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec
**token_custom_args (Any) – Optional additional arguments to pass as query parameters to the token fetch request.

Returns

An OAuthInteractive instance

Return type

OAuthInteractive

class cognite.client.credentials.OAuthDeviceCode(authority_url: str | None, client_id: str, scopes: Optional[list[str]] = None, cdf_cluster: Optional[str] = None, oauth_discovery_url: Optional[str] = None, token_cache_path: Optional[Path] = None, token_expiry_leeway_seconds: int = 30, clear_cache: bool = False, mem_cache_only: bool = False, **token_custom_args: Any)

OAuth credential provider for the device code login flow.

Parameters

authority_url (str | None) – MS Entra OAuth authority url, typically “https://login.microsoftonline.com/{tenant_id}”
client_id (str) – Your application’s client id that allows device code flows.
scopes (list[str] | None) – A list of scopes.
cdf_cluster (str | None) – The CDF cluster where the CDF project is located. If provided, scopes will be set to [f”https://{cdf_cluster}.cognitedata.com/IDENTITY https://{cdf_cluster}.cognitedata.com/user_impersonation openid profile”].
oauth_discovery_url (str | None) – Standard OAuth discovery URL, should be where “/.well-known/openid-configuration” is found.
token_cache_path (Path | None) – Location to store token cache, defaults to os temp directory/cognitetokencache.{client_id}.bin.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec
clear_cache (bool) – If True, the token cache will be cleared on initialization. Default: False
mem_cache_only (bool) – If True, the token cache will only be stored in memory. Default: False
**token_custom_args (Any) – Additional request parameters to pass to the authorization endpoint.

Examples

>>> from cognite.client.credentials import OAuthDeviceCode
>>> oauth_provider = OAuthDeviceCode(
...     authority_url="https://login.microsoftonline.com/xyz",
...     client_id="abcd",
...     scopes=["https://greenfield.cognitedata.com/.default"],
... )

Create credentials with auth0

>>> from cognite.client.credentials import OAuthDeviceCode
>>> oauth_provider = OAuthDeviceCode(
...     authority_url=None,
...     oauth_discovery_url="https://my-tenant.auth0.com/oauth",
...     client_id="abcd",
...     scopes=["IDENTITY", "user_impersonation"],
... )

classmethod load(config: dict[str, Any] | str) → OAuthDeviceCode

Load a OAuth device code credential provider object from a YAML/JSON string or dict.

Parameters: config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the OAuthDeviceCode class.
Returns: Initialized OAuthDeviceCode credential provider.
Return type: OAuthDeviceCode

Examples

>>> from cognite.client.credentials import OAuthDeviceCode
>>> config = {
...     "authority_url": "https://login.microsoftonline.com/xyz",
...     "client_id": "abcd",
...     "scopes": ["https://greenfield.cognitedata.com/.default"],
... }
>>> credentials = OAuthDeviceCode.load(config)

classmethod default_for_azure_ad(tenant_id: str, client_id: str, cdf_cluster: str, token_cache_path: Optional[Path] = None, token_expiry_leeway_seconds: int = 30, clear_cache: bool = False, mem_cache_only: bool = False) → OAuthDeviceCode

Create an OAuthDeviceCode instance for Azure with default URLs and scopes. It uses the pre-configured Cognite app registration for device code flow. If you need device code flow with another app registration, instantiate OAuthDeviceCode directly.

The default configuration creates the URLs based on the tenant id and cluster:

Authority URL: “https://login.microsoftonline.com/{tenant_id}”
Scopes: [f”https://{cdf_cluster}.cognitedata.com/.default”]

Parameters

tenant_id (str) – The Azure tenant id
client_id (str) – An app registration that allows device code flow.
cdf_cluster (str) – The CDF cluster where the CDF project is located.
token_cache_path (Path | None) – Location to store token cache, defaults to os temp directory/cognitetokencache.{client_id}.bin.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec
clear_cache (bool) – If True, the token cache will be cleared on initialization. Default: False
mem_cache_only (bool) – If True, the token cache will only be stored in memory. Default: False

Returns

An OAuthDeviceCode instance

Return type

OAuthDeviceCode

class cognite.client.credentials.OAuthClientCertificate(authority_url: str, client_id: str, cert_thumbprint: str, certificate: str, scopes: list[str], token_expiry_leeway_seconds: int = 30)

OAuth credential provider for authenticating with a client certificate.

Parameters

authority_url (str) – OAuth authority url
client_id (str) – Your application’s client id.
cert_thumbprint (str) – Your certificate’s thumbprint. You get it when you upload your certificate to Azure AD.
certificate (str) – Your private certificate, typically read from a .pem file
scopes (list[str]) – A list of scopes.
token_expiry_leeway_seconds (int) – The token is refreshed at the earliest when this number of seconds is left before expiry. Default: 30 sec

Examples

>>> from cognite.client.credentials import OAuthClientCertificate
>>> from pathlib import Path
>>> oauth_provider = OAuthClientCertificate(
...     authority_url="https://login.microsoftonline.com/xyz",
...     client_id="abcd",
...     cert_thumbprint="XYZ123",
...     certificate=Path("certificate.pem").read_text(),
...     scopes=["https://greenfield.cognitedata.com/.default"],
... )

classmethod load(config: dict[str, Any] | str) → OAuthClientCertificate

Load a OAuth client certificate credential provider object from a YAML/JSON string or dict.

Parameters: config (dict[str, Any] | str) – A dictionary or YAML/JSON string containing configuration values defined in the OAuthClientCertificate class.
Returns: Initialized OAuthClientCertificate credential provider.
Return type: OAuthClientCertificate

Examples

>>> from cognite.client.credentials import OAuthClientCertificate
>>> from pathlib import Path
>>> config = {
...     "authority_url": "https://login.microsoftonline.com/xyz",
...     "client_id": "abcd",
...     "cert_thumbprint": "XYZ123",
...     "certificate": Path("certificate.pem").read_text(),
...     "scopes": ["https://greenfield.cognitedata.com/.default"],
... }
>>> credentials = OAuthClientCertificate.load(config)