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