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 mutable 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: list[MutableScope] | None = 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: str | MutableScope, *, optional: bool | None = None) → 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: str | MutableScope | Iterable[str] | Iterable[MutableScope] | Iterable[str | 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.

Parameters:

obj (str, MutableScope, iterable of str or MutableScope) – The object or collection to convert to a string

ScopeBuilders#

ScopeBuilder Types#

class globus_sdk.scopes.ScopeBuilder(resource_server: str, *, known_scopes: None | str | Tuple[str, str] | List[str | Tuple[str, str]] = None, known_url_scopes: None | str | Tuple[str, str] | List[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) → 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: None | str | Tuple[str, str] | List[str | Tuple[str, str]] = None, known_url_scopes: None | str | Tuple[str, str] | List[str | Tuple[str, str]] = None)[source]#

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

Bases: 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

  • manage_projects

  • 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