GlobusApps¶

Note

Currently GlobusApp can only be used in scripts (e.g., notebooks or automation) and applications directly responsible for a user’s login flow.

Web services and other hosted applications operating as an OAuth2 resource server should see Globus Authorizers instead.

GlobusApp is a high level construct designed to simplify authentication for interactions with globus-sdk services.

A GlobusApp uses an OAuth2 client to obtain and manage OAuth2 tokens required for API interactions. OAuth2 clients must be created external to the SDK by registering an application at the Globus Developer’s Console.

The following section provides a comparison of the specific types of GlobusApps to aid in selecting the proper one for your use case.

Types of GlobusApps¶

There are two flavors of GlobusApp available in the SDK:

UserApp, for interactions in which an end user communicates with Globus services and
ClientApp, for interactions in which an OAuth2 client, operating as a “service account”, communicates with Globus services.

The following table provides a comparison of these two options:

UserApp	ClientApp
Appropriate for performing actions as a specific end user (e.g., the Globus CLI)	Appropriate for automating actions as a service account
Created resources (e.g., collections or flows) by default are owned by an end user	Created resources (e.g., collections or flows) by default are owned by the OAuth2 client
Existing resource access is evaluated based on an end user’s permissions	Existing resource access is evaluated based on the OAuth2 client’s permissions
OAuth2 tokens are obtained by putting an end user through a login flow (this occurs in a web browser)	OAuth2 tokens are obtained by programmatically exchanging an OAuth2 client’s secret
Should typically use a “native” OAuth2 client (Register a thick client) May use a “confidential” OAuth2 client (Register a portal or science gateway)	Must use a “confidential” OAuth2 client (Register a service account)

Note

Not all Globus operations support both app types.

Particularly when dealing with sensitive data, services may enforce that a a user be the primary data access actor. In these cases, a ClientApp will be rejected and a UserApp must be used instead.

Reference¶

The interfaces of these classes, defined below, intentionally include many “sane defaults” (i.e., storing oauth2 access tokens in a json file). These defaults may be overridden to customize the app’s behavior. For more information on what you can customize and how, see GlobusApp Configuration.

class globus_sdk.GlobusApp[source]¶

The abstract base class for managing authentication across services.

A single GlobusApp may be bound to many service clients, providing each them with dynamically updated authorization tokens. The app is responsible for ensuring these tokens are up-to-date and validly scoped; including initiating login flows to acquire new tokens when necessary.

See UserApp to oversee interactions with a human.

See ClientApp to oversee interactions with a service account.

Warning

GlobusApp is not thread safe.

Variables:

token_storage (ValidatingTokenStorage) – The interface used by the app to store, retrieve, and validate Globus Auth-issued tokens.
scope_requirements (dict[str, list[Scope]]) – A copy of the app’s aggregate scope requirements. Modifying the returned dict will not affect the app’s internal store. To add scope requirements, instead use the add_scope_requirements() method.

login(*, auth_params=None, force=False)[source]¶

Log a user or client into the app, if needed, storing the resulting tokens.

A login flow will be performed if any of the following are true:

The kwarg auth_params is provided.
The kwarg force is set to True.
The method self.login_required() evaluates to True.

Parameters:

auth_params (GlobusAuthorizationParameters | None) – An optional set of authorization parameters to establish requirements and controls for the login flow.
force (bool) – If True, perform a login flow even if one does not appear to be necessary.

login_required()[source]¶

Determine if a login flow will be required to interact with resource servers under the current scope requirements.

This will return false if any of the following are true:

Access tokens have never been issued.
Access tokens have been issued but have insufficient scopes.
Access tokens have expired and wouldn’t be resolved with refresh tokens.

Returns:: True if a login flow appears to be required, False otherwise.
Return type:: bool

logout()[source]¶

Log the current user or client out of the app.

This will remove and revoke all tokens stored for the current app user.

add_scope_requirements(scope_requirements)[source]¶

Add given scope requirements to the app’s scope requirements. Any duplicate requirements will be deduplicated with existing requirements.

Parameters:: scope_requirements (t.Mapping[str, ScopeCollectionType]) – a dict of Scopes indexed by resource server that will be added to this app’s scope requirements

get_authorizer(resource_server)[source]¶

Get a GlobusAuthorizer for a resource server.

This method will be called by service clients while making HTTP requests.

Parameters:: resource_server (str) – The resource server for which the requested Authorizer should provide authorization headers.
Return type:: GlobusAuthorizer

Implementations¶

class globus_sdk.UserApp(app_name='Unnamed Globus App', *, login_client=None, client_id=None, client_secret=None, scope_requirements=None, config=GlobusAppConfig(login_flow_manager=None, login_redirect_uri=None, token_storage='json', request_refresh_tokens=False, token_validation_error_handler=<function resolve_by_login_flow>, environment='production'))[source]¶

A GlobusApp for managing authentication state of a user for use in service clients.

Typically, a UserApp will use a native client, requiring a client_id created in a Globus Project. More advanced use cases however, may additionally supply a client_secret or full login_client with confidential client credentials.

UserApps are configured by supplying a GlobusAppConfig object to the config parameter. Of note, login flow behavior involves printing and prompting the user for input using std::in and std::out. This behavior can be customized with the login_flow_manager config attribute.

See GlobusApp for method signatures.

Example Usage:

app = UserApp("myapp", client_id=NATIVE_CLIENT_ID)
transfer_client = TransferClient(app=app)
res = transfer_client.endpoint_search("Tutorial Collection")

Parameters:

app_name (str) – A human-readable string to identify this app.
login_client (AuthLoginClient | None) – A login client bound to a specific native client id or confidential client id/secret. Mutually exclusive with client_id and client_secret.
client_id (UUIDLike | None) – A native or confidential client ID. Mutually exclusive with login_client.
client_secret (str | None) – A confidential client secret. Mutually exclusive with login_client.
scope_requirements (t.Mapping[str, ScopeCollectionType] | None) – A mapping of resource server to initial scope requirements.
config (GlobusAppConfig) – A data class containing configuration parameters for the app.

class globus_sdk.ClientApp(app_name='Unnamed Globus App', *, login_client=None, client_id=None, client_secret=None, scope_requirements=None, config=GlobusAppConfig(login_flow_manager=None, login_redirect_uri=None, token_storage='json', request_refresh_tokens=False, token_validation_error_handler=<function resolve_by_login_flow>, environment='production'))[source]¶

A GlobusApp for managing authentication state of a service account for use in service clients.

A ClientApp requires the use of a confidential client created in a Globus Project <https://app.globus.org/settings/developers>. Client info may be passed either with the client_id and client_secret parameters or as a full login_client.

ClientApps are configured by supplying a GlobusAppConfig object to the config parameter. Of note however, login_flow_manager must not be set; a ClientApp does not use a login flow manager.

See GlobusApp for method signatures.

Example Usage:

app = ClientApp("myapp", client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
transfer_client = TransferClient(app=app)
res = transfer_client.endpoint_search("Tutorial Collection")

Parameters:

app_name (str) – A human-readable string to identify this app.
login_client (ConfidentialAppAuthClient | None) – A login client bound to a specific native client id or confidential client id/secret. Mutually exclusive with client_id and client_secret.
client_id (UUIDLike | None) – A confidential client ID. Mutually exclusive with login_client.
client_secret (str | None) – A confidential client secret. Mutually exclusive with login_client.
scope_requirements (dict[str, ScopeCollectionType] | None) – A mapping of resource server to initial scope requirements.
config (GlobusAppConfig) – A data class containing configuration parameters for the app.