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, from full scope strings, 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")
MutableScopes provide the most value when handling scope dependencies. For example, given a Globus Connect Server Mapped Collection, it may be desirable to construct a “data_access” scope as an optional dependency for the Transfer Scope. To do so, one first creates the mutable scope object, then adds the dependency to it:
from globus_sdk.scopes import GCSCollectionScopeBuilder, TransferScopes
MAPPED_COLLECTION_ID = "...ID HERE..."
transfer_scope = TransferScopes.make_mutable("all")
transfer_scope.add_dependency(
GCSCollectionScopeBuilder(MAPPED_COLLECTION_ID).data_access, optional=True
)
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.
ScopeBuilder Types and Constants¶
- class globus_sdk.scopes.ScopeBuilder(resource_server: str, *, known_scopes: Optional[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[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) globus_sdk.scopes.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") MutableScope('urn:globus:auth:scope:transfer.api.globus.org:all')
This is equivalent to constructing a MutableScope object from the resolved scope string, as in
>>> MutableScope(TransferScopes.all) MutableScope('urn:globus:auth:scope:transfer.api.globus.org:all')
- Parameters
scope (str) – The name of the scope to convert to a MutableScope
- 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: Optional[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[str], str]] = None)[source]¶
Bases:
globus_sdk.scopes.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: Optional[Union[List[str], str]] = None, known_url_scopes: Optional[Union[List[str], str]] = None)[source]¶
Bases:
globus_sdk.scopes.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.MutableScope(scope_string: str, *, optional: bool = False)[source]¶
Bases:
object
A mutable scope is a representation of a scope which allows modifications to be made. In particular, it supports handling scope dependencies via
add_dependency
. A MutableScope can be createdstr(MutableScope(…)) produces a valid scope string for use in various methods.
- Parameters
- add_dependency(scope: str, *, optional: bool = False) globus_sdk.scopes.MutableScope [source]¶
Add a scope dependency. The dependent scope relationship will be stored in the MutableScope and will be evident in its string representation.
- static scopes2str(obj: Union[str, globus_sdk.scopes.MutableScope, Iterable[str], Iterable[globus_sdk.scopes.MutableScope], Iterable[Union[str, globus_sdk.scopes.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 MutableScopes, convert to a string which can be used in a request.
- globus_sdk.scopes.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.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.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.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.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