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]

MutableScope objects

In order to support optional and dependent scopes, an additional type is provided by globus_sdk.scopes: the MutableScope class.

MutableScope can be constructed directly, from full scope strings, or via a ScopeBuilder’s make_mutable method, given a scope’s short name.

For example, one can create a MutableScope from the Groups “all” scope as follows:

from globus_sdk.scopes import GroupsScopes

scope = GroupsScopes.make_mutable("all")

MutableScopes provide the most value when handling scope dependencies. For example, given a Globus Connect Server Mapped Collection, it may be desirable to construct a “data_access” scope as an optional dependency for the Transfer Scope. To do so, one first creates the mutable scope object, then adds the dependency to it:

from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes

MAPPED_COLLECTION_ID = "...ID HERE..."

transfer_scope = TransferScopes.make_mutable("all")
transfer_scope.add_dependency(
    GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).data_access, optional=True
)

MutableScopes can be used in most of the same locations where scope strings can be used, but you can also call str() on them to get a stringified representation.

ScopeBuilder Types and Constants

class globus_sdk.scopes.ScopeBuilder(resource_server: str, *, known_scopes: Optional[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[str], 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 of str, optional) – A list of scope names to pre-populate on this instance. This will set attributes on the instance using the URN scope format.

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

make_mutable(scope: str) → globus_sdk.scopes.MutableScope[source]

For a given scope, create a MutableScope object.

The scope name given refers to the name of a scope attached to the ScopeBuilder. It is given by attribute name, not by the full scope string.

Examples

Using the TransferScopes object, one could reference all as follows:

>>> TransferScopes.all
'urn:globus:auth:scope:transfer.api.globus.org:all'
>>> TransferScopes.make_mutable("all")
MutableScope('urn:globus:auth:scope:transfer.api.globus.org:all')

This is equivalent to constructing a MutableScope object from the resolved scope string, as in

>>> MutableScope(TransferScopes.all)
MutableScope('urn:globus:auth:scope:transfer.api.globus.org:all')
Parameters

scope (str) – The name of the scope to convert to a MutableScope

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[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[str], 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[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[str], 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
>>> https_scope = sb.https
class globus_sdk.scopes.MutableScope(scope_string: str, *, optional: bool = False)[source]

Bases: object

A mutable scope is a representation of a scope which allows modifications to be made. In particular, it supports handling scope dependencies via add_dependency. A MutableScope can be created

str(MutableScope(…)) produces a valid scope string for use in various methods.

Parameters

  • scope_string (str) – The scope which will be used as the basis for this MutableScope

  • optional (bool) – The scope may be marked as optional. This means that the scope can be declined by the user without declining consent for other scopes

add_dependency(scope: str, *, optional: bool = False) → globus_sdk.scopes.MutableScope[source]

Add a scope dependency. The dependent scope relationship will be stored in the MutableScope and will be evident in its string representation.

Parameters

  • scope (str) – The scope upon which the current scope depends

  • optional (bool, optional) – Mark the dependency an optional one. By default it is not. An optional scope dependency can be declined by the user without declining consent for the primary scope

static scopes2str(obj: Union[str, globus_sdk.scopes.MutableScope, Iterable[str], Iterable[globus_sdk.scopes.MutableScope], Iterable[Union[str, globus_sdk.scopes.MutableScope]]]) → str[source]

Given a scope string, a collection of scope strings, a MutableScope object, a collection of MutableScope objects, or a mixed collection of strings and MutableScopes, convert to a string which can be used in a request.

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