Globus Authorizers

Globus SDK clients need credentials (tokens) to authenticate against services and authorize their various API calls. Using Globus Auth, the Globus OAuth2 service, clients can be provided with credentials which are either static or dynamic.

The interface used to handle these credentials is GlobusAuthorizer. GlobusAuthorizer defines methods which provide an Authorization header for HTTP requests, and different implementations handle Refresh Tokens, Access Tokens, Client Credentials, and their various usage modes.

A GlobusAuthorizer is an object which defines the following two operations:

  • get an Authorization header

  • handle a 401 Unauthorized error

Clients contain authorizers, and use them to get and refresh their credentials. Whenever using the Service Clients, you should be passing in an authorizer when you create a new client unless otherwise specified.

The type of authorizer you will use depends very much on your application, but if you want examples you should look at the examples section. It may help to start with the examples and come back to the reference documentation afterwards.

The Authorizer Interface

We define the interface for GlobusAuthorizer objects in terms of an Abstract Base Class:

class globus_sdk.authorizers.GlobusAuthorizer[source]

A GlobusAuthorizer is a very simple object which generates valid Authorization headers. It may also have handling for responses that indicate that it has provided an invalid Authorization header.

abstract get_authorization_header()[source]

Get the value for the Authorization header from this authorizer. If this method returns None, then no Authorization header should be used.

Return type:

str | None

handle_missing_authorization()[source]

This operation should be called if a request is made with an Authorization header generated by this object which returns a 401 (HTTP Unauthorized). If the GlobusAuthorizer thinks that it can take some action to remedy this, it should update its state and return True. If the Authorizer cannot do anything in the event of a 401, this may update state, but importantly returns False.

By default, this always returns False and takes no other action.

Return type:

bool

Authorizers within this SDK fall into two categories:

  • “Static Authorizers” already contain all authorization data and simply format it into the proper authorization header. These all inherit from the StaticGlobusAuthorizer class.

  • “Renewing Authorizer” take some initial parameters but internally define a functional behavior to acquire new authorization data as necessary. These all inherit from the RenewingGlobusAuthorizer class.

class globus_sdk.authorizers.StaticGlobusAuthorizer[source]

Bases: GlobusAuthorizer

A static authorizer has some static string as its header val which it always returns as the authz header.

class globus_sdk.authorizers.RenewingAuthorizer(access_token=None, expires_at=None, on_refresh=None)[source]

Bases: GlobusAuthorizer, Generic[ResponseT]

A RenewingAuthorizer is an abstract superclass to any authorizer that needs to get new Access Tokens in order to form Authorization headers.

It may be passed an initial Access Token, but if so must also be passed an expires_at value for that token.

It provides methods that handle the logic for checking and adjusting expiration time, callbacks on renewal, and 401 handling.

To make an authorizer that implements this class implement the _get_token_response and _extract_token_data methods for that authorization type,

Parameters:

  • access_token (str | None) – Initial Access Token to use, only used if expires_at is also set

  • expires_at (int | None) – Expiration time for the starting access_token expressed as a POSIX timestamp (i.e. seconds since the epoch)

  • on_refresh (None | t.Callable[[ResponseT], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the response object resulting from the token being refreshed. It should take only one argument, the token response object. This is useful for implementing storage for Access Tokens, as the on_refresh callback can be used to update the Access Tokens and their expiration times.

Authorizer Types

All of these types of authorizers can be imported from globus_sdk.authorizers.

class globus_sdk.AccessTokenAuthorizer(access_token)[source]

Bases: StaticGlobusAuthorizer

Implements Authorization using a single Access Token with no Refresh Tokens. This is sent as a Bearer token in the header – basically unadorned.

Parameters:

access_token (str) – An access token for Globus Auth

class globus_sdk.RefreshTokenAuthorizer(refresh_token, auth_client, *, access_token=None, expires_at=None, on_refresh=None)[source]

Bases: RenewingAuthorizer[globus_sdk.OAuthRefreshTokenResponse]

Implements Authorization using a Refresh Token to periodically fetch renewed Access Tokens. It may be initialized with an Access Token, or it will fetch one the first time that get_authorization_header() is called.

Example usage looks something like this:

>>> import globus_sdk
>>> auth_client = globus_sdk.ConfidentialAppAuthClient(client_id=..., client_secret=...)
>>> # do some flow to get a refresh token from auth_client
>>> rt_authorizer = globus_sdk.RefreshTokenAuthorizer(refresh_token, auth_client)
>>> # create a new client
>>> transfer_client = globus_sdk.TransferClient(authorizer=rt_authorizer)

Anything which inherits from BaseClient will automatically support usage of the RefreshTokenAuthorizer.

Parameters:

  • refresh_token (str) – Refresh Token for Globus Auth

  • auth_client (globus_sdk.AuthLoginClient) – AuthClient capable of using the refresh_token

  • access_token (str | None) – Initial Access Token to use, only used if expires_at is also set

  • expires_at (int | None) – Expiration time for the starting access_token expressed as a POSIX timestamp (i.e. seconds since the epoch)

  • on_refresh (None | t.Callable[[globus_sdk.OAuthRefreshTokenResponse], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the globus_sdk.OAuthRefreshTokenResponse object resulting from the token being refreshed. It should take only one argument, the token response object. This is useful for implementing storage for Access Tokens, as the on_refresh callback can be used to update the Access Tokens and their expiration times.

class globus_sdk.ClientCredentialsAuthorizer(confidential_client, scopes, *, access_token=None, expires_at=None, on_refresh=None)[source]

Bases: RenewingAuthorizer[globus_sdk.OAuthClientCredentialsResponse]

Implementation of a RenewingAuthorizer that renews confidential app client Access Tokens using a ConfidentialAppAuthClient and a set of scopes to fetch a new Access Token when the old one expires.

Example usage looks something like this:

>>> import globus_sdk
>>> confidential_client = globus_sdk.ConfidentialAppAuthClient(
    client_id=..., client_secret=...)
>>> scopes = "..."
>>> cc_authorizer = globus_sdk.ClientCredentialsAuthorizer(
>>>     confidential_client, scopes)
>>> # create a new client
>>> transfer_client = globus_sdk.TransferClient(authorizer=cc_authorizer)

any client that inherits from BaseClient should be able to use a ClientCredentialsAuthorizer to act as the client itself.

Parameters:

  • confidential_client (globus_sdk.ConfidentialAppAuthClient) – client object with a valid id and client secret

  • scopes (str | Scope | t.Iterable[str | Scope]) – A string of space-separated scope names being requested for the access tokens that will be used for the Authorization header. These scopes must all be for the same resource server, or else the token response will have multiple access tokens.

  • access_token (str | None) – Initial Access Token to use, only used if expires_at is also set. Must be requested with the same set of scopes passed to this authorizer.

  • expires_at (int | None) – Expiration time for the starting access_token expressed as a POSIX timestamp (i.e. seconds since the epoch)

  • on_refresh (None | t.Callable[[globus_sdk.OAuthClientCredentialsResponse], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the globus_sdk.OAuthClientCredentialsResponse object resulting from the token being refreshed. It should take only one positional argument, the token response object. This is useful for implementing storage for Access Tokens, as the on_refresh callback can be used to update the Access Tokens and their expiration times.

class globus_sdk.BasicAuthorizer(username, password)[source]

Bases: StaticGlobusAuthorizer

This Authorizer implements Basic Authentication. Given a “username” and “password”, they are sent base64 encoded in the header.

Parameters:

  • username (str) – Username component for Basic Auth

  • password (str) – Password component for Basic Auth

class globus_sdk.NullAuthorizer[source]

Bases: GlobusAuthorizer

This Authorizer implements No Authentication – as in, it ensures that there is no Authorization header.

get_authorization_header()[source]

Get the value for the Authorization header from this authorizer. If this method returns None, then no Authorization header should be used.