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.
Scope
s 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)
Scope
s 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:
- 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.
- 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.
- 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.
- 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:
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:
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 referenceall
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:
- Return type:
- 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"
- 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"
- 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 nameTimerScopes
.
- 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