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 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")

MutableScope objects primarily provide two main pieces of functionality: dynamically building a scope tree and serializing to a string.

Dynamic Scope Construction

MutableScope objects provide a tree-like interface for constructing scopes and their dependencies.

For example, the transfer scope dependent upon a collection scope may be constructed by means of MutableScope methods and the make_mutable method of scope builders thusly:

from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes

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

# create the scopes with make_mutable
transfer_scope = TransferScopes.make_mutable("all")
data_access_scope = GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).make_mutable(
    "data_access", optional=True
)
# add data_access as a dependency
transfer_scope.add_dependency(data_access_scope)

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.

Serializing Scopes

Whenever scopes are being sent to Globus services, they need to be encoded as strings. All mutabl scope objects support this by means of their defined serialize method. Note that __str__ for a MutableScope is just an alias for serialize. For example, the following is valid usage to demonstrate str(), repr(), and serialize():

>>> from globus_sdk.scopes import MutableScope
>>> foo = MutableScope("foo")
>>> bar = MutableScope("bar")
>>> bar.add_dependency("baz")
>>> foo.add_dependency(bar)
>>> print(str(MutableScope("foo")))
foo[bar *baz]
>>> print(bar.serialize())
bar[baz]
>>> alpha = MutableScope("alpha")
>>> alpha.add_dependency(MutableScope("beta", optional=True))
>>> print(repr(alpha))
MutableScope("alpha", dependencies=[MutableScope("beta", optional=True)])

MutableScope Reference

class globus_sdk.scopes.MutableScope(scope_string: str, *, optional: bool = False, dependencies: Optional[List[globus_sdk.scopes.scope_definition.MutableScope]] = None)[source]

Bases: object

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

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

Parameters

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

  • 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: Union[str, globus_sdk.scopes.scope_definition.MutableScope], *, optional: Optional[bool] = None) → globus_sdk.scopes.scope_definition.MutableScope[source]

Add a scope dependency. The dependent scope relationship will be stored in the Scope 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.scope_definition.Scope, globus_sdk.scopes.scope_definition.MutableScope, Iterable[str], Iterable[globus_sdk.scopes.scope_definition.Scope], Iterable[globus_sdk.scopes.scope_definition.MutableScope], Iterable[Union[str, globus_sdk.scopes.scope_definition.Scope, globus_sdk.scopes.scope_definition.MutableScope]], Iterable[Union[str, globus_sdk.scopes.scope_definition.Scope]], Iterable[Union[str, globus_sdk.scopes.scope_definition.MutableScope]], Iterable[Union[globus_sdk.scopes.scope_definition.Scope, globus_sdk.scopes.scope_definition.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 Scopes, convert to a string which can be used in a request.

ScopeBuilders

ScopeBuilder Types

class globus_sdk.scopes.ScopeBuilder(resource_server: str, *, known_scopes: Union[None, str, Tuple[str, str], List[Union[str, Tuple[str, str]]]] = None, known_url_scopes: Union[None, str, Tuple[str, str], List[Union[str, Tuple[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, *, optional: bool = False) → globus_sdk.scopes.scope_definition.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")
Scope('urn:globus:auth:scope:transfer.api.globus.org:all')

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

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

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

  • optional (bool) – If true, the created MutableScope object will be marked optional

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: Union[None, str, Tuple[str, str], List[Union[str, Tuple[str, str]]]] = None, known_url_scopes: Union[None, str, Tuple[str, str], List[Union[str, Tuple[str, str]]]] = None)[source]

Bases: globus_sdk.scopes.builder.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: Union[None, str, Tuple[str, str], List[Union[str, Tuple[str, str]]]] = None, known_url_scopes: Union[None, str, Tuple[str, str], List[Union[str, Tuple[str, str]]]] = None)[source]

Bases: globus_sdk.scopes.builder.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

ScopeBuilder Constants

globus_sdk.scopes.data.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.data.FlowsScopes

Globus Flows scopes.

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

>>> FlowsScopes.manage_flows

Supported Scopes

  • manage_flows

  • view_flows

  • run

  • run_status

  • run_manage

globus_sdk.scopes.data.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.data.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.data.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.data.TimerScopes

Globus Timer scopes.

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

>>> TimerScopes.timer

Supported Scopes

  • timer

globus_sdk.scopes.data.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