Authentication

Classes:

Auth([domain, scope, leeway, ...])

Client used to authenticate with all Descartes Labs service APIs.

class Auth(domain=None, scope=None, leeway=500, token_info_path=<object object>, client_id=None, client_secret=None, jwt_token=None, refresh_token=None, retries=None, _suppress_warning=False)[source]

Client used to authenticate with all Descartes Labs service APIs.

Retrieves a JWT access token from a client id and refresh token for cli usage.

By default and without arguments the credentials are retrieved from a config file named token_info.json. This file can be created by running descarteslabs auth login from the command line.

You can change the default location by setting the environment variable DESCARTESLABS_TOKEN_INFO_PATH. Make sure you do this before running descarteslabs auth login so the credentials will be saved to the file specified in the environment variable, and when still set when instantiating this class, the credentials will be read from that file.

To use a short-lived access token that will not be refreshed, either set the environment variable DESCARTESLABS_TOKEN or use the jwt_token parameter.

To use a long-lived refresh token that will be refreshed, either set the environment variables DESCARTESLABS_CLIENT_ID and DESCARTESLABS_CLIENT_SECRET or use the parameters client_id and client_secret. This will retrieve an access token which will be cached between instances for the same combination of client id and client secret.

If in addition to the client id and client secret you also specify a valid short-lived access token, it will be used until it expires.

Note that the environment variable DESCARTESLABS_REFRESH_TOKEN is identical to DESCARTESLABS_CLIENT_SECRET and the parameter refresh_token is identical to client_secret. Use one or the other but not both.

Although discouraged, it is possible to set one value as environment variable, and pass the other value in as parameter. For example, one could set the environment variable DESCARTESLABS_CLIENT_ID and only pass in the parameter client_secret.

If you also specify a token_info_path that indicates which file to read the credentials from. If used by itself, it works the same as DESCARTESLABS_TOKEN_INFO_PATH and assuming the file exists and contains valid credentials, you could switch between accounts this way.

If you specify the token_info_path together with an additional client id and client secret (whether retrieved through environment variables or given using parameters), the given credentials will be written to the given file. If this file already exists and contains matching credentials, it will be used to retrieve the short-lived access token and refreshes it when it expires. If the file already exists and contains conflicting credentials, it will be overwritten with the new credentials.

Parameters:

domain (str, default descarteslabs.config.get_settings().IAM_URL) – The domain used for the credentials. You should normally never change this.
scope (list(str), optional) – The JWT access token fields to be included. You should normally never have to use this.
leeway (int, default 500) – The leeway is given in seconds and is used as a safety cushion for the expiration. If the expiration falls within the leeway, the JWT access token will be renewed.
token_info_path (str, default ~/.descarteslabs/token_info.json) – Path to a JSON file holding the credentials. If not set and credentials are provided through environment variables or through parameters, this parameter will not be used. However, if no credentials are provided through environment variables or through parameters, it will default to ~/.descarteslabs/token_info.json and credentials will be retrieved from that file if present. If explicitly set to None, credentials will never be retrieved from file and must be provided through environment variables or parameters.
client_id (str, optional) – The JWT client id. If provided it will take precedence over the corresponding environment variable, or the credentials retrieved through the file specified in token_info_path. If this parameter is provided, you must either provide a client_secret or refresh_token (but not both). Access tokens retrieved this way will be cached without revealing the client secret.
client_secret (str, optional) – The refresh token used to retrieve short-lived access tokens. If provided it will take precedence over the corresponding environment variable, or the credentials retrieved through the file specified in token_info_path. If this parameter is provided, you must also provide a client id either as a parameter or through an environment variable. Access tokens retrieved this way will be cached without revealing the client secret.
jwt_token (str, optional) – A short-lived JWT access token. If valid and used without other parameters, it will be used for access. If used with a client id, the access token must match or it will be discarded. If the access token is discarded either because it expired or didn’t match the given client id, and no client secret has been given, no new access token can be retrieved and access will be denied. If used with both client id and client secret, the token will be cached and updated as needed without revealing the client secret.
refresh_token (str, optional) – Identical to the client_secret. You can only specify one or the other, or if specified both, they must match. The refresh token takes precedence over the client secret.
retries (Retry or int, optional) – The number of retries and backoff policy; by default 5 retries with a random backoff policy between 1 and 10 seconds.

Raises:

UserWarning – In case the refresh token and client secret differ. In case the defailt or given token_info_path cannot be found. In case no credentials can be found.

Examples

>>> import descarteslabs
>>> # Use default credentials obtained through 'descarteslabs auth login'
>>> auth = descarteslabs.auth.Auth()
>>> # Your Descartes Labs user id
>>> auth.namespace 
'a54d88e06612d820bc3be72877c74f257b561b19'
>>> auth = descarteslabs.auth.Auth(
...     client_id="ZOBAi4UROl5gKZIpxxlwOEfx8KpqXf2c",
...     client_secret="b70B_ozH6CaV23WQ-toFQ8CaujGHDs-eC39QEJTRnZa9Z",
... )
>>> auth.namespace 
'67f21eb1040f978fe1da32e5e33501d0f4a604ac'
>>>

Methods:

`from_environment_or_token_json`(**kwargs)	Creates an Auth object from the given arguments.
`get_default_auth`()	Retrieve the default Auth.
`set_default_auth`(auth)	Change the default Auth to the given Auth.

Attributes:

`all_acl_subjects`	A list of all ACL subjects identifying this user (the user itself, the org, the groups) which can be used in ACL queries.
`all_owner_acl_subjects`	A list of ACL subjects identifying this user (the user itself, the org, org admin and catalog admins) which can be used in owner ACL queries.
`namespace`	Gets the user namespace (the Descartes Labs used id).
`payload`	Gets the token payload.
`token`	Gets the short-lived JWT access token.

classmethod from_environment_or_token_json(**kwargs)[source]

Creates an Auth object from the given arguments.

Creates an Auth object from the given arguments, environment variables, or stored credentials.

See Auth for details.

static get_default_auth()[source]

Retrieve the default Auth.

This Auth is used whenever you don’t explicitly set the Auth when creating clients, etc.

static set_default_auth(auth)[source]

Change the default Auth to the given Auth.

This is the Auth that will be used whenever you don’t explicitly set the Auth when creating clients, etc.

property all_acl_subjects: A list of all ACL subjects identifying this user (the user itself, the org, the groups) which can be used in ACL queries.

property all_owner_acl_subjects: A list of ACL subjects identifying this user (the user itself, the org, org admin and catalog admins) which can be used in owner ACL queries.

property namespace

Gets the user namespace (the Descartes Labs used id).

Returns:

The user namespace.

Return type:

str

Raises:

AuthError – Raised when incomplete credentials were provided.
OauthError – Raised when a token cannot be obtained or refreshed.

property payload

Gets the token payload.

Returns:

Dictionary containing the fields specified by scope, which may include:

name:           The name of the user.
groups:         Groups to which the user belongs.
org:            The organization to which the user belongs.
email:          The email address of the user.
email_verified: True if the user's email has been verified.
sub:            The user identifier.
exp:            The expiration time of the token, in seconds since
                the start of the unix epoch.

Return type:

dict

Raises:

AuthError – Raised when incomplete credentials were provided.
OauthError – Raised when a token cannot be obtained or refreshed.

property token

Gets the short-lived JWT access token.

Returns:

The JWT token string.

Return type:

str

Raises:

AuthError – Raised when incomplete credentials were provided.
OauthError – Raised when a token cannot be obtained or refreshed.