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:
JSONTokenStorage
for storing tokens in a local JSON file.SQLiteTokenStorage
for storing tokens in a local SQLite database.MemoryTokenStorage
for storing tokens in process memory.
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 byresource_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:
- 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.
- 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.
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:
token_data_by_resource_server (Mapping[str, TokenStorageData]) – The data to validate.
context (TokenValidationContext) – The validation context object, containing state of the system at the time of validation.
- 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:
token_data_by_resource_server (Mapping[str, TokenStorageData]) – The data to validate.
context (TokenValidationContext) – The validation context object, containing state of the system at the time of validation.
- 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.