API Authorization#

Authorizing calls against Globus can be a complex process. In particular, if you are using Refresh Tokens and short-lived Access Tokens, you may need to take particular care managing your Authorization state.

Within the SDK, we solve this problem by using GlobusAuthorizers, which are attached to clients. A GlobusAuthorizer is an object which defines the following two operations:

  • get an Authorization header

  • handle a 401 Unauthorized error

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 full 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

GlobusAuthorizer objects that fetch new access tokens when their existing ones expire or a 401 is received implement the RenewingAuthorizer class

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

Bases: GlobusAuthorizer

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[[OAuthTokenResponse], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the OAuthTokenResponse 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.

get_authorization_header()[source]#

Check to see if a new token is needed and return “Bearer <access_token>”

Return type:

str

handle_missing_authorization()[source]#

The renewing authorizer can respond to a service 401 by immediately invalidating its current Access Token. When this happens, the next call to set_authorization_header() will result in a new Access Token being fetched.

Return type:

bool

GlobusAuthorizer objects which have a static authorization header are all implemented using the static authorizer 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.

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

Authorizer Types#

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

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.

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.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

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.OAuthTokenResponse], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the OAuthTokenResponse 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

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 (ConfidentialAppAuthClient) – client object with a valid id and client secret

  • scopes (ScopeCollectionType) – 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[[OAuthTokenResponse], t.Any]) – A callback which is triggered any time this authorizer fetches a new access_token. The on_refresh callable is invoked on the OAuthTokenResponse 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.