Scopes and ScopeBuilders¶

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

A number of preset 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 Attributes¶

Token scopes are associated with a particular client which will use that token. Because of this, each service client contains a ScopeBuilder attribute (client.scopes) defining the relevant scopes for that client.

For most client classes, this is a class attribute. For example, accessing TransferClient.scopes is valid:

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

As Instance Attributes and Methods¶

Some client classes only provide their scopes for instances. These cases cover services which are distributed or contain multiple subservices with their own scopes.

For example, GCSClient and SpecificFlowClient each have a scopes attribute of None on their classes.

In the case of SpecificFlowClient, scopes are populated whenever an instance is instantiated. So the following usage is valid:

import globus_sdk

FLOW_ID = "<YOUR_ID_HERE>"

client = globus_sdk.SpecificFlowClient(FLOW_ID)
flow_user_scope = client.scopes.user

In the case of GCS, a distributed service, scopes is always None. However, globus_sdk.GCSClient.get_gcs_endpoint_scopes() and globus_sdk.GCSClient.get_gcs_collection_scopes() are available helpers for getting specific collections of scopes.

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]

Scope objects¶

The SDK provides a Scope object which is the class model for a scope. Scopes can be parsed from strings and serialized to strings, and support programmatic manipulations to describe dependent scopes.

Scope can be constructed using its initializer, or one of its two main parsing methods: Scope.parse and Scope.deserialize. parse produces a list of scopes from a string, while deserialize produces exactly one.

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

from globus_sdk.scopes import GroupsScopes, Scope

group_scope = Scope.deserialize(GroupsScopes.all)

Scope objects primarily provide three main pieces of functionality:

parsing (deserializing)

stringifying (serializing)

scope tree construction

Scope Construction¶

Scope 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 Scope methods thusly:

from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes, Scope

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

# create the scope object, and get the data_access_scope as a string
transfer_scope = Scope(TransferScopes.all)
data_access_scope = GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).data_access
# add data_access as an optional dependency
transfer_scope.add_dependency(data_access_scope, optional=True)

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

Serializing Scopes¶

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

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

Scope Reference¶

class globus_sdk.scopes.Scope(scope_string, *, optional=False, dependencies=None)[source]¶

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(Scope(…)) 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

static parse(scope_string)[source]¶

Parse an arbitrary scope string to a list of scopes.

Zero or more than one scope may be returned, as in the case of an empty string or space-delimited scopes.

Warning

Parsing passes through an intermediary representation which treats scopes as a graph. This ensures that the behavior of parses matches the treatment of scope strings in Globus Auth authorization flows. However, this also means that the parsing does not allow for strings which represent consent trees with structures in which the same scope appears in multiple parts of the tree.

Parameters:: scope_string (str) – The string to parse
Return type:: list[Scope]

static merge_scopes(scopes_a, scopes_b)[source]¶

Given two lists of Scopes, merge them into one list of Scopes by parsing them as one combined scope string.

Parameters:

scopes_a (list[Scope]) – list of Scopes to be merged with scopes_b
scopes_b (list[Scope]) – list of Scopes to be merged with scopes_a

Return type:

list[Scope]

classmethod deserialize(scope_string)[source]¶

Deserialize a scope string to a scope object.

This is the special case of parsing in which exactly one scope must be returned by the parse. If more than one scope is returned by the parse, a ValueError will be raised.

Parameters:: scope_string (str) – The string to parse
Return type:: Scope

add_dependency(scope, *, optional=None)[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 | Scope) – The scope upon which the current scope depends
optional (bool | None) – 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

Return type:

Scope

class globus_sdk.scopes.ScopeParseError[source]¶: The error raised if scope parsing fails.

class globus_sdk.scopes.ScopeCycleError[source]¶: The error raised if scope parsing discovers a cycle.

Utility Functions

globus_sdk.scopes also provides helper functions which are used to manipulate scope objects.

globus_sdk.scopes.scopes_to_str(scopes)[source]¶

Normalize a scope collection to a space-separated scope string.

Parameters:: scopes (ScopeCollectionType) – A scope string or object, or an iterable of scope strings or objects.
Returns:: A space-separated scope string.
Return type:: str

Example usage:

>>> scopes_to_str(Scope("foo"))
'foo'
>>> scopes_to_str(Scope("foo"), "bar", MutableScope("qux"))
'foo bar qux'

globus_sdk.scopes.scopes_to_scope_list(scopes)[source]¶

Normalize a scope collection to a list of Scope objects.

Parameters:: scopes (ScopeCollectionType) – A scope string or object, or an iterable of scope strings or objects.
Returns:: A list of Scope objects.
Return type:: list[Scope]

Example usage:

>>> scopes_to_scope_list(Scope("foo"))
[Scope('foo')]
>>> scopes_to_scope_list(Scope("foo"), "bar baz", MutableScope("qux"))
[Scope('foo'), Scope('bar'), Scope('baz'), Scope('qux')]

ScopeBuilders¶

ScopeBuilder Types¶

class globus_sdk.scopes.ScopeBuilder(resource_server, *, known_scopes=None, known_url_scopes=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 (ScopeBuilderScopes) – 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 (ScopeBuilderScopes) – 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, *, optional=False)[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

Return type:

MutableScope

url_scope_string(scope_name)[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.
Return type:: str

urn_scope_string(scope_name)[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.
Return type:: str

class globus_sdk.scopes.GCSEndpointScopeBuilder(resource_server, *, known_scopes=None, known_url_scopes=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, *, known_scopes=None, known_url_scopes=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

class globus_sdk.scopes.SpecificFlowScopeBuilder(flow_id)[source]¶

Bases: ScopeBuilder

This defines the scopes for a single flow (as distinct from the Flows service).

It primarily provides the user scope which is typically needed to start a run of a flow.

Example usage:

sb = SpecificFlowScopeBuilder("my-flow-id-here")
flow_scope = sb.user

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_consents
view_identities
view_identity_set

globus_sdk.scopes.data.ComputeScopes¶

Compute scopes.

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

>>> ComputeScopes.all

Supported Scopes

all

globus_sdk.scopes.data.FlowsScopes¶

Globus Flows scopes.

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

>>> FlowsScopes.all

Supported Scopes

all
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.

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

>>> NexusScopes.groups

Supported Scopes

groups

Warning

Use of Nexus is deprecated. Users should use Groups instead.

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.TimersScopes¶

Globus Timers scopes.

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

>>> TimersScopes.timer

Supported Scopes

timer

Note

TimersScopes is also available under the legacy name TimerScopes.

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