Token Storages

Interacting with Globus services requires the use of Globus Auth-issued OAuth2 tokens. To assist in reuse of these tokens, the SDK provides an interface to store and retrieve this data across different storage backends.

In addition to the interface, TokenStorage, the SDK provides concrete implementations for some of the most common storage backends:

Reference

class globus_sdk.tokenstorage.TokenStorage(namespace='DEFAULT')[source]

The interface for interacting with a store of TokenStorageData objects.

Implementations must partition their token data objects by namespace. Within a namespace, token data must be indexed by resource_server.

Parameters:

namespace (str) – A unique string for partitioning token data (Default: “DEFAULT”).

abstract store_token_data_by_resource_server(token_data_by_resource_server)[source]

Store token data for one or more resource server in the current namespace.

Parameters:

token_data_by_resource_server (Mapping[str, TokenStorageData]) – mapping of resource server to token data.

abstract get_token_data_by_resource_server()[source]

Retrieve all token data stored in the current namespace.

Returns:

a dict of TokenStorageData objects indexed by their resource server.

Return type:

dict[str, TokenStorageData]

get_token_data(resource_server)[source]

Retrieve token data for a particular resource server in the current namespace.

Parameters:

resource_server (str) – The resource_server string to get token data for.

Returns:

token data if found or else None.

Return type:

TokenStorageData | None

abstract remove_token_data(resource_server)[source]

Remove token data for a resource server in the current namespace.

Parameters:

resource_server (str) – The resource server string to remove token data for.

Returns:

True if token data was deleted, False if none was found to delete.

Return type:

bool

store_token_response(token_response)[source]

Store token data from an OAuthTokenResponse in the current namespace.

Parameters:

token_response (OAuthTokenResponse) – A token response object from an authentication flow.

class globus_sdk.tokenstorage.TokenStorageData(resource_server, identity_id, scope, access_token, refresh_token, expires_at_seconds, token_type, extra=None)[source]

Data class for tokens and token metadata issued by a globus auth token grant. For storage and retrieval of these objects, see TokenStorage.

Tokens are scoped to a specific user/client (identity_id) performing specific operations (scope) with a specific service (resource_server).

Variables:
  • resource_server (str) – The resource server for which this token data was granted.

  • identity_id (str) – The primary identity id of the user or client which requested this token. This will be None if an identity id was not extractable from the token grant response.

  • scope (str) – A space separated list of scopes that this token data provides access to.

  • access_token (str) – A Globus Auth-issued OAuth2 access token. Used for authentication when interacting with service APIs.

  • refresh_token (str | None) – A Globus Auth-issued OAuth2 refresh token. Used to obtain new access tokens when the current one expires. This value will be None if the original token grant did not request refresh tokens.

  • expires_at_seconds (int) – An epoch seconds timestamp for when the associated access_token expires.

  • token_type (str | None) – The token type of access_token, currently this will always be “Bearer” if present.

Parameters:

extra (dict[str, Any]) – An optional dictionary of additional fields to include. Included for forward/backward compatibility.

File-based Token Storages

class globus_sdk.tokenstorage.JSONTokenStorage(filepath, *, namespace='DEFAULT')[source]

A token storage which stores token data on disk in a JSON file.

This class defines a format_version which determines what the specific data shape. Any data in a supported_version format which is not the primary format_version will be automatically rewritten.

See TokenStorage for common interface details.

Variables:
  • format_version ("2.0") – The data format version used when writing data.

  • supported_versions (("1.0", "2.0")) – The list of data format versions which can be read.

Parameters:
  • filepath (pathlib.Path | str) – The path to a JSON file where token data should be stored.

  • namespace (str) – A unique string for partitioning token data (Default: “DEFAULT”).

class globus_sdk.tokenstorage.SQLiteTokenStorage(filepath, *, connect_params=None, namespace='DEFAULT')[source]

A token storage which stores token data on disk in a SQLite database.

See TokenStorage for common interface details.

Parameters:
  • filepath (pathlib.Path | str) – The path on disk to a SQLite database file.

  • connect_params (dict[str, t.Any] | None) – A dictionary of parameters to pass to sqlite3.connect().

  • namespace (str) – A unique string for partitioning token data (Default: “DEFAULT”).

Raises:

GlobusSDKUsageError – If the filepath is “:memory:”. This usage-mode is not supported in this class; use MemoryTokenStorage instead if in-memory token storage is desired.

close()[source]

Close the underlying database connection.

iter_namespaces()[source]

Iterate over all distinct namespaces in the SQLite database.

Return type:

Iterator[str]

Ephemeral Token Storages

class globus_sdk.tokenstorage.MemoryTokenStorage(*, namespace='DEFAULT')[source]

A token storage which holds tokens in-memory. All token data is lost when the process exits.

See TokenStorage for common interface details.

Parameters:

namespace (str) – A unique string for partitioning token data (Default: “DEFAULT”).

Validating Token Storage

Alongside the above storage-specific implementations which supply built-in token storage to common locations, the SDK provides a unique token storage called ValidatingTokenStorage. This class isn’t concerned with the actual storage of tokens, but rather their validity.

A ValidatingTokenStorage is created with one or more TokenDataValidators, each of which define a custom token validation that will be performed during the storage or retrieval of a token. The SDK provides a number of validators out-of-the-box to meet common validation requirements: Concrete Validators.

class globus_sdk.tokenstorage.ValidatingTokenStorage(token_storage, *, validators=())[source]

A special token storage which provides token data validation hooks.

See TokenDataValidator for details on hook specifics.

See TokenStorage for common interface details.

Parameters:
  • token_storage (TokenStorage) – A proxy token storage for this class to pass through store, get, and remove requests to.

  • validators (t.Iterable[TokenDataValidator]) – A collection of validation hooks to call.

Variables:

identity_id (str | None) – The primary identity ID of the entity which granted tokens, if known.

class globus_sdk.tokenstorage.TokenDataValidator[source]

The abstract base class for custom token validation logic.

Implementations should raise a TokenValidationError if a validation error is encountered.

abstract before_store(token_data_by_resource_server, context)[source]

Validate token data against this validator’s constraints before it is written to token storage.

Parameters:
Raises:

TokenValidationError – On failure.

abstract after_retrieve(token_data_by_resource_server, context)[source]

Validate token data against this validator’s constraints after it is retrieved from token storage.

Parameters:
Raises:

TokenValidationError – On failure.

class globus_sdk.tokenstorage.TokenValidationContext(prior_identity_id, token_data_identity_id)[source]

A data object of information available to TokenDataValidators during validation.

Variables:
  • prior_identity_id (str | None) – The identity ID associated with the ValidatingTokenStorage before the operation began, if there was one.

  • token_data_identity_id (str | None) – The identity ID extracted from the token data being validated.

class globus_sdk.tokenstorage.TokenValidationError[source]

The class of errors raised when a token fails validation.

Concrete Validators

class globus_sdk.tokenstorage.NotExpiredValidator[source]

A validator to validate that token data has not expired.

  • This validator only runs after_retrieve.

Raises:

ExpiredTokenError – If any token data shows has expired.

class globus_sdk.tokenstorage.HasRefreshTokensValidator[source]

A validator to validate that token data contains refresh tokens.

  • This validator only runs after_retrieve.

Raises:

MissingTokenError – If any token data does not contain a refresh token.

class globus_sdk.tokenstorage.ScopeRequirementsValidator(scope_requirements, consent_client)[source]

A validator to validate that token data meets scope requirements.

A scope requirement, i.e., “transfer:all[collection:data_access]”, can be broken into two parts: the root scope, “transfer:all”, and one or more dependent scopes, “collection:data_access”.

  • On before_store, this validator only evaluates root scope requirements.

  • On after_retrieve, this validator evaluates both root and dependent scope requirements.

Note

Dependent scopes are only evaluated if an identity ID is extractable from token grants. If no identity ID is available, dependent scope evaluation is silently skipped.

Parameters:
  • scope_requirements (t.Mapping[str, t.Sequence[globus_sdk.Scope]]) – A mapping of resource servers to required scopes.

  • consent_client (globus_sdk.AuthClient) – An AuthClient to fetch consents with. This auth client must have (or have access to) any valid Globus Auth scoped token.

Raises:

UnmetScopeRequirementsError – If any scope requirements are not met.

class globus_sdk.tokenstorage.UnchangingIdentityIDValidator[source]

A validator to validate that user identity does not change across token grants.

  • This validator only runs before_store.

Raises:
  • IdentityMismatchError – If identity info changes across token storage operations.

  • MissingIdentityError – If the token data did not have any identity information.