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 | 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 | 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: Path | None = 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: list[str] | None = None,

cdf_cluster: str | None = None,

oauth_discovery_url: str | None = None,

token_cache_path: Path | None = 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: Path | None = 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.

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/IDENTITY”, f”https://{cdf_cluster}.cognitedata.com/user_impersonation”, “profile”, “openid”, “offline_access”]

Parameters:

tenant_id (str) – The Azure tenant id
client_id (str) – Your app registration client id. Must have device code flow enabled.
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)