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)
MutableScope
s 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[globus_sdk.scopes.scope_definition.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:
- 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.
- static scopes2str(obj: str | Scope | MutableScope | Iterable[str] | Iterable[Scope] | Iterable[MutableScope] | Iterable[str | Scope | MutableScope] | Iterable[str | Scope] | Iterable[str | MutableScope] | Iterable[Scope | 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: 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 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')
- 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
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