Scopes and ScopeBuilders

OAuth2 Scopes for various Globus services are represented by ScopeBuilder objects.

A number of pre-set scope builders are provided and populated with useful data, and they are also accessible via the relevant client classes.

Direct Use (as constants)

To use the scope builders directly, import from globus_sdk.scopes.

For example, one might use the Transfer “all” scope during a login flow like so:

import globus_sdk
from globus_sdk.scopes import TransferScopes

CLIENT_ID = "<YOUR_ID_HERE>"

client = globus_sdk.NativeAppAuthClient(CLIENT_ID)
client.oauth2_start_flow(requested_scopes=[TransferScopes.all])
...

As Client Class Attributes

Because the scopes for a token are associated with some concrete client which will use that token, it makes sense to associate a scope with a client class.

The Globus SDK does this by providing the ScopeBuilder for a service as an attribute of the client. For example,

import globus_sdk

CLIENT_ID = "<YOUR_ID_HERE>"

client = globus_sdk.NativeAppAuthClient(CLIENT_ID)
client.oauth2_start_flow(requested_scopes=[globus_sdk.TransferClient.scopes.all])
...

# or, potentially, after there is a concrete client
_tc = globus_sdk.TransferClient()
client.oauth2_start_flow(requested_scopes=[_tc.scopes.all])

Using a Scope Builder to Get Matching Tokens

A ScopeBuilder contains the resource server name used to get token data from a token response. To elaborate on the above example:

import globus_sdk
from globus_sdk.scopes import TransferScopes

CLIENT_ID = "<YOUR_ID_HERE>"

client = globus_sdk.NativeAppAuthClient(CLIENT_ID)
client.oauth2_start_flow(requested_scopes=[TransferScopes.all])
authorize_url = client.oauth2_get_authorize_url()
print("Please go to this URL and login:", authorize_url)
auth_code = input("Please enter the code you get after login here: ").strip()
token_response = client.oauth2_exchange_code_for_tokens(auth_code)

# use the `resource_server` of a ScopeBuilder to grab the associated token
# data from the response
tokendata = token_response.by_resource_server[TransferScopes.resource_server]

ScopeBuilder Types and Constants

class globus_sdk.scopes.ScopeBuilder(resource_server: str, *, known_scopes: Optional[List[str]] = None)[source]

Bases: object

Utility class for creating scope strings for a specified resource server.

Parameters

  • resource_server (str) – The identifier, usually a domain name or a UUID, for the resource server to return scopes for.

  • known_scopes (list, optional) – A list of scope names to pre-populate on this instance. This will set attributes on the instance using the URN scope format.

url_scope_string(scope_name: str) → str[source]

Return a complete string representing the scope with a given name for this client, in URL format.

Examples

>>> sb = ScopeBuilder("actions.globus.org")
>>> sb.url_scope_string("actions.globus.org", "hello_world")
"https://auth.globus.org/scopes/actions.globus.org/hello_world"
Parameters

scope_name (str) – The short name for the scope involved.

urn_scope_string(scope_name: str) → str[source]

Return a complete string representing the scope with a given name for this client, in the Globus Auth URN format.

Note that this module already provides many such scope strings for use with Globus services.

Examples

>>> sb = ScopeBuilder("transfer.api.globus.org")
>>> sb.urn_scope_string("transfer.api.globus.org", "all")
"urn:globus:auth:scope:transfer.api.globus.org:all"
Parameters

scope_name (str) – The short name for the scope involved.

class globus_sdk.scopes.GCSEndpointScopeBuilder(resource_server: str, *, known_scopes: Optional[List[str]] = None)[source]

Bases: globus_sdk.scopes.ScopeBuilder

A ScopeBuilder with a named property for the GCS manage_collections scope. “manage_collections” is a scope on GCS Endpoints. The resource_server string should be the GCS Endpoint ID.

Examples

>>> sb = GCSEndpointScopeBuilder("xyz")
>>> mc_scope = sb.manage_collections
class globus_sdk.scopes.GCSCollectionScopeBuilder(resource_server: str, *, known_scopes: Optional[List[str]] = None)[source]

Bases: globus_sdk.scopes.ScopeBuilder

A ScopeBuilder with a named property for the GCS data_access scope. “data_access” is a scope on GCS Collections. The resource_server string should be the GCS Collection ID.

Examples

>>> sb = GCSCollectionScopeBuilder("xyz")
>>> da_scope = sb.data_access
globus_sdk.scopes.AuthScopes

Globus Auth scopes.

Various scopes are available as attributes of this object. For example, access the view_identity_set scope with

>>> AuthScopes.view_identity_set

Supported Scopes

  • openid

  • email

  • profile

  • view_authentications

  • view_clients

  • view_clients_and_scopes

  • view_identities

  • view_identity_set

globus_sdk.scopes.GroupsScopes

Groups scopes.

Various scopes are available as attributes of this object. For example, access the all scope with

>>> GroupsScopes.all

Supported Scopes

  • all

  • view_my_groups_and_memberships

globus_sdk.scopes.NexusScopes

Nexus scopes (internal use only).

Various scopes are available as attributes of this object. For example, access the groups scope with

>>> NexusScopes.groups

Supported Scopes

  • groups

globus_sdk.scopes.SearchScopes

Globus Search scopes.

Various scopes are available as attributes of this object. For example, access the all scope with

>>> SearchScopes.all

Supported Scopes

  • all

  • globus_connect_server

  • ingest

  • search

globus_sdk.scopes.TransferScopes

Globus Transfer scopes.

Various scopes are available as attributes of this object. For example, access the all scope with

>>> TransferScopes.all

Supported Scopes

  • all

  • gcp_install

  • monitor_ongoing