Native Client

class fair_research_login.NativeClient(token_storage=<fair_research_login.token_storage.configparser_token_storage.MultiClientTokenStorage object>, local_server_code_handler=None, secondary_code_handler=None, code_handlers=(<fair_research_login.local_server.LocalServerCodeHandler object>, <fair_research_login.code_handler.InputCodeHandler object>), default_scopes=None, *args, **kwargs)

Bases: object

The Native Client serves as another small layer on top of the Globus SDK to automatically handle token storage and provide a customizable Local Server. It can be used both by simple scripts to simplify the auth flow, or by full command line clients that may extend various pieces and tailor them to its own needs.

An example is below:

cli = NativeClient(client_id='my_id', app_name='my cool app')
cli.login(requested_scopes=['openid', 'profile', 'email'])
Parameters:

  • client_id (str) – The id for your app. Register one at https://developers.globus.org

  • app_name (str) – The name of your app. Shows up on the named grant during consent, and the local server browser page by default. It is also propogated to globus_sdk.NativeAppAuthClient.

  • default_scopes (list) –

    A list of scopes which will serve as the default to login() if login is called with no requested_scopes parameter.

    ["openid", "profile", "email"]

  • token_storage (TokenStorage) –

    (object) Any object capable of reading/writing/clearing tokens from/to disk. The object must define these three methods: read_tokens(), write_tokens(tokens), and clear_tokens(), where tokens is a list of login groups (dicts), each of which contains a token group (dict) keyed by resource server.

    [
    {
        "auth.globus.org": {
            "scope": "openid profile email",
            "access_token": "<token>",
            "refresh_token": null,
            "token_type": "Bearer",
            "expires_at_seconds": 1234567,
            "resource_server": "auth.globus.org"
        }
    }
]

    A default token storage object is provided at fair_research_login.token_storage.MultiClientTokenStorage, which saves tokens in a section named by your clients client_id. None may be used to disable token storage.

  • code_handlers – (list of CodeHandler ) A list of Code handlers capable of fetching and returning the authorization code generated as a browser query param in Globus Auth Code handlers are executed in the order they appear in the list, and may be skipped by users with ^C or if they cannot be run (Local Server Code Handler cannot run on remote servers, for example).

login(requested_scopes: List[str] | None = None, refresh_tokens: bool | None = None, force: bool = False, prefill_named_grant: bool | None = None, query_params: dict | None = None, additional_params: dict | None = None, **kwargs)

Do a Native App Auth Flow to get tokens for requested scopes. This first attempts to load tokens and will simply return those if they are valid, and will automatically attempt to save tokens on login success (token_storage must be set for automatic load/save functionality). See load_tokens for how it handles requested_scopes.

Parameters:

  • requested_scopes –

    A list of scopes to request of Globus Auth during login.

    ["openid", "profile", "email"]

  • refresh_tokens – Ask for Globus Refresh Tokens to extend login time.

  • no_local_server – Disable spinning up a local server to automatically copy-paste the auth code. This is automatically disabled if the detected session is an SSH session. When used locally with no_local_server=False, the domain is localhost with a randomly chosen open port number.

  • force – Force a login flow, even if loaded tokens are valid.

  • no_browser – Do not automatically open the browser for the Globus Auth URL. Display the URL instead and let the user navigate to that location.

  • prefill_named_grant – Use a custom named grant on the consent page

  • query_params – Additional Params used in constructing the authorize URL for Globus Auth. Used for requesting additional features such as for using Globus Sessions. Changed from additional_params in Globus SDK v2

  • additional_params – Additional Params used in constructing the authorize URL for Globus Auth. Used for requesting additional features such as for using Globus Sessions. Deprecated. Use query_params instead.

save_tokens(tokens: Mapping[str, Mapping])

Save tokens if token_storage is set. Typically this is called automatically in a successful login(). Returns a value from the token_storage backend.

Parameters:

tokens –

A dict of token dicts, each containing a dict defined by globus_sdk.auth.token_response.OAuthTokenResponse.by_resource_server.

{
    "auth.globus.org": {
        "scope": "profile openid email",
        "access_token": "<token>",
        "refresh_token": null,
        "token_type": "Bearer",
        "expires_at_seconds": 1539984535,
        "resource_server": "auth.globus.org"
    }
}

load_tokens(requested_scopes: List[str] | None = None) → Mapping[str, Mapping]

Load saved tokens and return them keyed by resource server. If no requested_scopes are requested, will attempt to return all active tokens, automatically refreshing expired tokens where possible.

If requested_scopes are provided, load_tokens will guarantee only those scopes are returned and that the tokens have not expired (Note: Tokens can still be invalid if the user rescind consent). If the tokens have expired, a TokensExpired exception is raised. If loaded scopes do not contain requested_scopes, a ScopesMismatch exception is raised.

Parameters:

requested_scopes – A list of scopes which must be successfully loaded, or a ScopesMismatch error will be raised

Type:

list

Returns:

A dict of token dicts, each containing a dict defined by globus_sdk.auth.token_response.OAuthTokenResponse .by_resource_server

An example looks like the following

{
    "auth.globus.org": {
        "scope": "profile openid email",
        "access_token": "<token>",
        "refresh_token": null,
        "token_type": "Bearer",
        "expires_at_seconds": 1539984535,
        "resource_server": "auth.globus.org"
    },
}

Raises:
load_tokens_by_scope(requested_scopes: List[str] | None = None)

Like load_tokens(), but returns a dict keyed by token scopes instead of by resource server. If there are multiple scopes requested for the same token (such as [‘openid’, ‘profile’, ‘email’]), each scope will have a duplicate copy of the same information.

Parameters:

requested_scopes – A list of scopes which must be successfully loaded, or a ScopesMismatch error will be raised

Raises:
get_authorizers(requested_scopes: List[str] | None = None) → Mapping[str, AccessTokenAuthorizer | RefreshTokenAuthorizer]

Load tokens and create TokenAuthorizers for them. Automatically creates a globus_sdk.RefreshTokenAuthorizer if possible, otherwise an globus_sdk.AccessTokenAuthorizer. Authorizers are organized by resource server. Raises a fair_research_login.exc.LoadError if Token Storage is disabled, no tokens were saved, or if the tokens expired or the requested scopes don’t match. Calls load_tokens() internally.

Parameters:

requested_scopes – A list of scopes which must be successfully loaded, or a ScopesMismatch error will be raised

Returns:

The dict keyed by resource server, with values being authorizers. RefreshTokenAuthorizers are preferred if possible

Raises:
get_authorizers_by_scope(requested_scopes: List[str] | None = None)

Like get_authorizers(), but returns a dict keyed by scope rather than by resource server.

Parameters:

requested_scopes – A list of scopes which must be successfully loaded, or a ScopesMismatch error will be raised

Returns:

The dict of authorizers keyed by scope, with values being authorizers. RefreshTokenAuthorizers are preferred if possible

Raises:
logout()

Revoke saved tokens and clear them from storage. Raises fair_research_login.exc.TokenStorageDisabled if no token storage is set, otherwise attempts to revoke tokens then returns None.

Clients NOT using token storage should use ‘revoke_token_set’ instead to revoke tokens.