Globus Auth

There are several types of client object for communicating with the Globus Auth service. A client object may represent your application (as the driver of authentication and authorization flows), in which case the NativeAppAuthClient or ConfidentialAppAuthClient classes should generally be used.

Client Classes

class globus_sdk.AuthClient(client_id=None, environment=None, base_url=None, app=None, app_scopes=None, authorizer=None, app_name=None, transport_params=None)[source]

Bases: BaseClient

A client for using the Globus Auth API

This class provides helper methods for most common resources in the Auth API, and the common low-level interface from BaseClient of get, put, post, and delete methods, which can be used to access any API resource.

Examples

Initializing an AuthClient to authenticate a user making calls to the Globus Auth service with an access token takes the form

>>> from globus_sdk import AuthClient, AccessTokenAuthorizer
>>> ac = AuthClient(authorizer=AccessTokenAuthorizer('<token_string>'))

Other authorizers, most notably RefreshTokenAuthorizer, are also supported.

Methods

error_class

alias of AuthAPIError

scopes: ScopeBuilder | None = <globus_sdk.scopes.data.auth._AuthScopesBuilder object>

the scopes for this client may be present as a ScopeBuilder

get_openid_configuration()[source]

Fetch the OpenID Connect configuration data from the well-known URI for Globus Auth.

Return type:

GlobusHTTPResponse

get_jwk(openid_configuration: None | GlobusHTTPResponse | dict[str, Any], *, as_pem: Literal[True]) → RSAPublicKey[source]
get_jwk(openid_configuration: None | GlobusHTTPResponse | dict[str, Any], *, as_pem: Literal[False]) → dict[str, Any]

Fetch the Globus Auth JWK.

Returns either a dict or an RSA Public Key object depending on as_pem.

Parameters:

  • openid_configuration (None | GlobusHTTPResponse | dict[str, Any]) – The OIDC config as a GlobusHTTPResponse or dict. When not provided, it will be fetched automatically.

  • as_pem (bool) – Decode the JWK to an RSA PEM key, typically for JWT decoding

userinfo()[source]

Call the Userinfo endpoint of Globus Auth. Userinfo is specified as part of the OpenID Connect (OIDC) standard, and Globus Auth’s Userinfo is OIDC-compliant.

The exact data returned will depend upon the set of OIDC-related scopes which were used to acquire the token being used for this call. For details, see the API Info below.

ac = AuthClient(...)
info = ac.oauth2_userinfo()
print(
    'Effective Identity "{info["sub"]}" has '
    f'Full Name "{info["name"]}" and '
    f'Email "{info["email"]}"'
)

GET /v2/oauth2/userinfo

See Get Userinfo in the API documentation for details.

Return type:

GlobusHTTPResponse

oauth2_userinfo()[source]

A deprecated alias for userinfo.

Return type:

GlobusHTTPResponse

get_identities(*, usernames=None, ids=None, provision=False, query_params=None)[source]

Given usernames=<U> or (exclusive) ids=<I> as keyword arguments, looks up identity information for the set of identities provided. <U> and <I> in this case are comma-delimited strings listing multiple Identity Usernames or Identity IDs, or iterables of strings, each of which is an Identity Username or Identity ID.

If Globus Auth’s identity auto-provisioning behavior is desired, provision=True may be specified.

Available with any authentication/client type.

Parameters:

  • usernames (Iterable[str] | str | None) – A username or list of usernames to lookup. Mutually exclusive with ids

  • ids (Iterable[UUID | str] | UUID | str | None) – An identity ID or list of IDs to lookup. Mutually exclusive with usernames

  • provision (bool) – Create identities if they do not exist, allowing clients to get username-to-identity mappings prior to the identity being used

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GetIdentitiesResponse

>>> ac = globus_sdk.AuthClient(...)
>>> # get by ID
>>> r = ac.get_identities(ids="46bd0f56-e24f-11e5-a510-131bef46955c")
>>> r.data
{
  'identities': [
    {
      'email': None,
      'id': '46bd0f56-e24f-11e5-a510-131bef46955c',
      'identity_provider': '7daddf46-70c5-45ee-9f0f-7244fe7c8707',
      'name': None,
      'organization': None,
      'status': 'unused',
      'username': 'globus@globus.org'
    }
  ]
}
>>> ac.get_identities(
...     ids=",".join(
...         ("46bd0f56-e24f-11e5-a510-131bef46955c", "168edc3d-c6ba-478c-9cf8-541ff5ebdc1c")
...     )
... )
>>> # or by usernames
>>> ac.get_identities(usernames="globus@globus.org")
>>> ac.get_identities(usernames="globus@globus.org,auth@globus.org")

You could also use iterables:

ac.get_identities(usernames=["globus@globus.org", "auth@globus.org"])

ac.get_identities(
    ids=["46bd0f56-e24f-11e5-a510-131bef46955c", "168edc3d-c6ba-478c-9cf8-541ff5ebdc1c"]
)

The result itself is iterable, so you can use it like so:

for identity in ac.get_identities(usernames=["globus@globus.org", "auth@globus.org"]):
    print(identity["id"])

GET /v2/api/identities

See Get Identities in the API documentation for details.

get_identity_providers(*, domains=None, ids=None, query_params=None)[source]

Look up information about identity providers by domains or by IDs.

Parameters:

  • domains (Iterable[str] | str | None) – A domain or iterable of domains to lookup. Mutually exclusive with ids.

  • ids (Iterable[UUID | str] | UUID | str | None) – An identity provider ID or iterable of IDs to lookup. Mutually exclusive with domains.

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GetIdentityProvidersResponse

>>> ac = globus_sdk.AuthClient(...)
>>> # get by ID
>>> r = ac.get_identity_providers(ids="41143743-f3c8-4d60-bbdb-eeecaba85bd9")
>>> r.data
{
  'identity_providers': [
    {
      'alternative_names': [],
      'name': 'Globus ID',
      'domains': ['globusid.org'],
      'id': '41143743-f3c8-4d60-bbdb-eeecaba85bd9',
      'short_name': 'globusid'
    }
  ]
}
>>> ac.get_identities(
...     ids=["41143743-f3c8-4d60-bbdb-eeecaba85bd9", "927d7238-f917-4eb2-9ace-c523fa9ba34e"]
... )
>>> # or by domain
>>> ac.get_identities(domains="globusid.org")
>>> ac.get_identities(domains=["globus.org", "globusid.org"])

The result itself is iterable, so you can use it like so:

for idp in ac.get_identity_providers(domains=["globus.org", "globusid.org"]):
    print(f"name: {idp['name']}")
    print(f"id: {idp['id']}")
    print(f"domains: {idp['domains']}")
    print()

{
  "identity_providers": [
    {
      "short_name": "globusid",
      "id": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
      "alternative_names": [],
      "domains": [
        "globusid.org"
      ],
      "name": "Globus ID"
    },
    {
      "short_name": "globus.org",
      "id": "927d7238-f917-4eb2-9ace-c523fa9ba34e",
      "alternative_names": [],
      "domains": [
        "globus.org"
      ],
      "name": "Globus Staff"
    }
  ]
}

GET /v2/api/identity_providers

See Get Identity Providers in the API documentation for details.

get_project(project_id)[source]

Look up a project. Requires the manage_projects scope.

Parameters:

project_id (UUID | str) – The ID of the project to lookup

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_project("927d7238-f917-4eb2-9ace-c523fa9ba34e")
>>> r.data
{
  'project': {
    'admin_ids': ['41143743-f3c8-4d60-bbdb-eeecaba85bd9']
    'contact_email': 'support@globus.org',
    'display_name': 'Globus SDK Demo Project',
    'admin_group_ids': None,
    'id': '927d7238-f917-4eb2-9ace-c523fa9ba34e',
    'project_name': 'Globus SDK Demo Project',
    'admins': {
      'identities': ['41143743-f3c8-4d60-bbdb-eeecaba85bd9'],
      'groups': [],
    },
  }
}

{
  "project": {
    "admin_ids": [
      "bcc646ac-b768-11ef-8ee1-0242ac110002"
    ],
    "contact_email": "support@guardians.galaxy",
    "display_name": "Guardians of the Galaxy Portal",
    "admin_group_ids": null,
    "id": "bcc6472e-b768-11ef-8ee1-0242ac110002",
    "project_name": "Guardians of the Galaxy Portal",
    "admins": {
      "identities": [
        {
          "identity_provider": "bcc644d6-b768-11ef-8ee1-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bcc6460c-b768-11ef-8ee1-0242ac110002",
          "name": "Star Lord",
          "username": "star.lord@guardians.galaxy",
          "email": "star.lord2@guardians.galaxy"
        },
        {
          "identity_provider": "bcc644d6-b768-11ef-8ee1-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bcc646ac-b768-11ef-8ee1-0242ac110002",
          "name": "Rocket",
          "username": "rocket@guardians.galaxy",
          "email": "star.lord@guardians.galaxy"
        }
      ],
      "groups": []
    }
  }
}

GET /v2/api/projects/{project_id}

See Get Projects in the API documentation for details.

get_projects()[source]

Look up projects on which the authenticated user is an admin. Requires the manage_projects scope.

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_projects()
>>> r.data
{
  'projects': [
    {
      'admin_ids': ['41143743-f3c8-4d60-bbdb-eeecaba85bd9']
      'contact_email': 'support@globus.org',
      'display_name': 'Globus SDK Demo Project',
      'admin_group_ids': None,
      'id': '927d7238-f917-4eb2-9ace-c523fa9ba34e',
      'project_name': 'Globus SDK Demo Project',
      'admins': {
        'identities': ['41143743-f3c8-4d60-bbdb-eeecaba85bd9'],
        'groups': [],
      },
    }
  ]
}

The result itself is iterable, so you can use it like so:

for project in ac.get_projects():
    print(f"name: {project['display_name']}")
    print(f"id: {project['id']}")
    print()

{
  "projects": [
    {
      "admin_ids": [
        "bcc71f1e-b768-11ef-8ee1-0242ac110002"
      ],
      "contact_email": "eviltestproject@guardians.galaxy",
      "display_name": "Evil Test Project Full of Evil",
      "admin_group_ids": null,
      "id": "bcc71fb4-b768-11ef-8ee1-0242ac110002",
      "project_name": "Evil Test Project Full of Evil",
      "admins": {
        "identities": [
          {
            "identity_provider": "bcc71d8e-b768-11ef-8ee1-0242ac110002",
            "identity_type": "login",
            "organization": "Guardians of the Galaxy",
            "status": "used",
            "id": "bcc71f1e-b768-11ef-8ee1-0242ac110002",
            "name": "Rocket",
            "username": "rocket@guardians.galaxy",
            "email": "star.lord@guardians.galaxy"
          }
        ],
        "groups": []
      }
    },
    {
      "admin_ids": [
        "bcc71f1e-b768-11ef-8ee1-0242ac110002"
      ],
      "contact_email": "support@guardians.galaxy",
      "display_name": "Guardians of the Galaxy Portal",
      "admin_group_ids": null,
      "id": "bcc7204a-b768-11ef-8ee1-0242ac110002",
      "project_name": "Guardians of the Galaxy Portal",
      "admins": {
        "identities": [
          {
            "identity_provider": "bcc71d8e-b768-11ef-8ee1-0242ac110002",
            "identity_type": "login",
            "organization": "Guardians of the Galaxy",
            "status": "used",
            "id": "bcc71e88-b768-11ef-8ee1-0242ac110002",
            "name": "Star Lord",
            "username": "star.lord@guardians.galaxy",
            "email": "star.lord2@guardians.galaxy"
          },
          {
            "identity_provider": "bcc71d8e-b768-11ef-8ee1-0242ac110002",
            "identity_type": "login",
            "organization": "Guardians of the Galaxy",
            "status": "used",
            "id": "bcc71f1e-b768-11ef-8ee1-0242ac110002",
            "name": "Rocket",
            "username": "rocket@guardians.galaxy",
            "email": "star.lord@guardians.galaxy"
          }
        ],
        "groups": []
      }
    }
  ]
}

GET /v2/api/projects

See Get Projects in the API documentation for details.

Return type:

IterableResponse

create_project(display_name, contact_email, *, admin_ids=None, admin_group_ids=None)[source]

Create a new project. Requires the manage_projects scope.

At least one of admin_ids or admin_group_ids must be provided.

Parameters:

  • display_name (str) – The name of the project

  • contact_email (str) – The email address of the project’s point of contact

  • admin_ids (Iterable[UUID | str] | UUID | str | None) – A list of user IDs to be added as admins of the project

  • admin_group_ids (Iterable[UUID | str] | UUID | str | None) – A list of group IDs to be added as admins of the project

Return type:

GlobusHTTPResponse

When creating a project, your account is not necessarily included as an admin. The following snippet uses the manage_projects scope as well as the openid and email scopes to get the current user ID and email address and use those data to setup the project.

>>> ac = globus_sdk.AuthClient(...)
>>> userinfo = ac.oauth2_userinfo()
>>> identity_id = userinfo["sub"]
>>> email = userinfo["email"]
>>> r = ac.create_project(
...     "My Project",
...     contact_email=email,
...     admin_ids=identity_id,
... )
>>> project_id = r["project"]["id"]

{
  "project": {
    "contact_email": "support@globus.org",
    "id": "bcc81c52-b768-11ef-8ee1-0242ac110002",
    "admins": {
      "identities": [
        {
          "identity_provider": "bcc81d2e-b768-11ef-8ee1-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bcc81da6-b768-11ef-8ee1-0242ac110002",
          "name": "Star Lord",
          "username": "star.lord@guardians.galaxy",
          "email": "star.lord2@guardians.galaxy"
        }
      ],
      "groups": []
    },
    "project_name": "Guardians of the Galaxy",
    "admin_ids": [
      "bcc81da6-b768-11ef-8ee1-0242ac110002"
    ],
    "admin_group_ids": null,
    "display_name": "Guardians of the Galaxy"
  }
}

POST /v2/api/projects

See Create Project in the API documentation for details.

update_project(project_id, *, display_name=None, contact_email=None, admin_ids=None, admin_group_ids=None)[source]

Update a project. Requires the manage_projects scope.

Parameters:

  • project_id (UUID | str) – The ID of the project to update

  • display_name (str | None) – The name of the project

  • contact_email (str | None) – The email address of the project’s point of contact

  • admin_ids (Iterable[UUID | str] | UUID | str | None) – A list of user IDs to be set as admins of the project

  • admin_group_ids (Iterable[UUID | str] | UUID | str | None) – A list of group IDs to be set as admins of the project

Return type:

GlobusHTTPResponse

The following snippet uses the manage_projects scope as well as the email scope to get the current user email address and set it as a project’s contact email:

>>> ac = globus_sdk.AuthClient(...)
>>> project_id = ...
>>> userinfo = ac.oauth2_userinfo()
>>> email = userinfo["email"]
>>> r = ac.update_project(project_id, contact_email=email)

{
  "project": {
    "contact_email": "support@globus.org",
    "id": "bcd8da92-b768-11ef-8ee1-0242ac110002",
    "admins": {
      "identities": [
        {
          "identity_provider": "bcd8dba0-b768-11ef-8ee1-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bcd8dc22-b768-11ef-8ee1-0242ac110002",
          "name": "Star Lord",
          "username": "star.lord@guardians.galaxy",
          "email": "star.lord2@guardians.galaxy"
        }
      ],
      "groups": []
    },
    "project_name": "Guardians of the Galaxy",
    "admin_ids": [
      "bcd8dc22-b768-11ef-8ee1-0242ac110002"
    ],
    "admin_group_ids": null,
    "display_name": "Guardians of the Galaxy"
  }
}

POST /v2/api/projects

See Update Project in the API documentation for details.

delete_project(project_id)[source]

Delete a project. Requires the manage_projects scope.

Parameters:

project_id (UUID | str) – The ID of the project to delete

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> project_id = ...
>>> r = ac.delete_project(project_id)

{
  "project": {
    "contact_email": "support@globus.org",
    "id": "bcd9d33e-b768-11ef-8ee1-0242ac110002",
    "admins": {
      "identities": [
        {
          "identity_provider": "bcd9d41a-b768-11ef-8ee1-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bcd9d4b0-b768-11ef-8ee1-0242ac110002",
          "name": "Star Lord",
          "username": "star.lord@guardians.galaxy",
          "email": "star.lord2@guardians.galaxy"
        }
      ],
      "groups": []
    },
    "project_name": "Guardians of the Galaxy",
    "admin_ids": [
      "bcd9d4b0-b768-11ef-8ee1-0242ac110002"
    ],
    "admin_group_ids": null,
    "display_name": "Guardians of the Galaxy"
  }
}

DELETE /v2/api/projects/{project_id}

See Delete Project in the API documentation for details.

get_policy(policy_id)[source]

Look up a policy. Requires the manage_projects scope.

Parameters:

policy_id (UUID | str) – The ID of the policy to lookup

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_policy("f5eaae7e-807f-41be-891a-ec86ff88df8f")
>>> r.data
{
  'policy': {
    'high_assurance': False,
    'domain_constraints_include': ['globus.org'],
    'display_name': 'Display Name',
    'description': 'Description',
    'id': 'f5eaae7e-807f-41be-891a-ec86ff88df8f',
    'domain_constraints_exclude': None,
    'project_id': 'da84e531-1afb-43cb-8c87-135ab580516a',
    'authentication_assurance_timeout': 35
  }
}

{
  "policy": {
    "high_assurance": false,
    "domain_constraints_include": [
      "greenlight.org"
    ],
    "display_name": "GreenLight domain Only Policy",
    "description": "Only allow access from @greenlight.org",
    "id": "bcdac3a2-b768-11ef-8ee1-0242ac110002",
    "domain_constraints_exclude": null,
    "project_id": "da84e531-1afb-43cb-8c87-135ab580516a",
    "authentication_assurance_timeout": 35
  }
}

GET /v2/api/policies/{policy_id}

See Get Policies in the API documentation for details.

get_policies()[source]

Look up policies in projects on which the authenticated user is an admin. Requires the manage_projects scope.

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_policies()
>>> r.data
{
  'policies': [
    {
      'high_assurance': False,
      'domain_constraints_include': ['greenlight.org'],
      'display_name': 'GreenLight domain Only Policy',
      'description': 'Only allow access from @greenlight.org',
      'id': '99d2dc75-3acb-48ff-b5e5-2eee0a5121d1',
      'domain_constraints_exclude': None,
      'project_id': 'da84e531-1afb-43cb-8c87-135ab580516a',
      'authentication_assurance_timeout': 35,
    },
    {
      'high_assurance': True,
      'domain_constraints_include': None,
      'display_name': 'No RedLight domain Policy',
      'description': 'Disallow access from @redlight.org',
      'id': '5d93ebf0-b4c6-4928-9929-4ac47fc2786d',
      'domain_constraints_exclude': ['redlight.org'],
      'project_id': 'da84e531-1afb-43cb-8c87-135ab580516a',
      'authentication_assurance_timeout': 35,
    }
  ]
}

{
  "policies": [
    {
      "high_assurance": false,
      "domain_constraints_include": [
        "greenlight.org"
      ],
      "display_name": "GreenLight domain Only Policy",
      "description": "Only allow access from @greenlight.org",
      "id": "bcdb894a-b768-11ef-8ee1-0242ac110002",
      "domain_constraints_exclude": null,
      "project_id": "da84e531-1afb-43cb-8c87-135ab580516a",
      "authentication_assurance_timeout": 35
    },
    {
      "high_assurance": true,
      "domain_constraints_include": null,
      "display_name": "No RedLight domain Policy",
      "description": "Disallow access from @redlight.org",
      "id": "bcdb8a26-b768-11ef-8ee1-0242ac110002",
      "domain_constraints_exclude": [
        "redlight.org"
      ],
      "project_id": "da84e531-1afb-43cb-8c87-135ab580516a",
      "authentication_assurance_timeout": 35
    }
  ]
}

GET /v2/api/policies

See Get Policies in the API documentation for details.

Return type:

IterableResponse

create_policy(*, project_id, display_name, description, high_assurance=MISSING, authentication_assurance_timeout=MISSING, domain_constraints_include=MISSING, domain_constraints_exclude=MISSING)[source]

Create a new Auth policy. Requires the manage_projects scope.

Parameters:

  • project_id (UUID | str) – ID of the project for the new policy

  • high_assurance (bool | MissingType) – Whether or not this policy is applied to sessions.

  • authentication_assurance_timeout (int | MissingType) – Number of seconds within which someone must have authenticated to satisfy the policy

  • display_name (str) – A user-friendly name for the policy

  • description (str) – A user-friendly description to explain the purpose of the policy

  • domain_constraints_include (Iterable[str] | None | MissingType) – A list of domains that can satisfy the policy

  • domain_constraints_exclude (Iterable[str] | None | MissingType) – A list of domains that cannot satisfy the policy

Return type:

GlobusHTTPResponse

Note

project_id, display_name, and description are all required arguments, although they are not declared as required in the function signature. This is due to a backwards compatible behavior with earlier versions of globus-sdk, and will be changed in a future release which removes the compatible behavior.

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> r = ac.create_policy(
...     project_id="da84e531-1afb-43cb-8c87-135ab580516a",
...     high_assurance=True,
...     authentication_assurance_timeout=35,
...     display_name="No RedLight domain Policy",
...     description="Disallow access from @redlight.org",
...     domain_constraints_exclude=["redlight.org"],
... )
>>> policy_id = r["policy"]["id"]

{
  "policy": {
    "project_id": "bcdcc3e6-b768-11ef-8ee1-0242ac110002",
    "display_name": "Policy of Foo",
    "description": "Controls access to Foo",
    "id": "bcdcc544-b768-11ef-8ee1-0242ac110002"
  }
}

POST /v2/api/policies

See Create Policy in the API documentation for details.

update_policy(policy_id, *, project_id=MISSING, authentication_assurance_timeout=MISSING, display_name=MISSING, description=MISSING, domain_constraints_include=MISSING, domain_constraints_exclude=MISSING)[source]

Update a policy. Requires the manage_projects scope.

Parameters:

  • policy_id (UUID | str) – ID of the policy to update

  • project_id (UUID | str | MissingType) – ID of the project for the new policy

  • authentication_assurance_timeout (int | MissingType) – Number of seconds within which someone must have authenticated to satisfy the policy

  • display_name (str | MissingType) – A user-friendly name for the policy

  • description (str | MissingType) – A user-friendly description to explain the purpose of the policy

  • domain_constraints_include (Iterable[str] | None | MissingType) – A list of domains that can satisfy the policy

  • domain_constraints_exclude (Iterable[str] | None | MissingType) – A list of domains that can not satisfy the policy

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> policy_id = ...
>>> r = ac.update_policy(scope_id, display_name="Greenlight Policy")

{
  "policy": {
    "project_id": "bcddfa04-b768-11ef-8ee1-0242ac110002",
    "high_assurance": true,
    "authentication_assurance_timeout": 25,
    "display_name": "08bc1d56a0ae4161adff562b5b63db9c",
    "description": "b96b2674c7804c15834aab8908227506",
    "domain_constraints_include": null,
    "domain_constraints_exclude": null
  }
}

POST /v2/api/policies/{policy_id}

See Update Policy in the API documentation for details.

delete_policy(policy_id)[source]

Delete a policy. Requires the manage_projects scope.

Parameters:

policy_id (UUID | str) – The ID of the policy to delete

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> policy_id = ...
>>> r = ac.delete_policy(policy_id)

{
  "policy": {
    "high_assurance": false,
    "domain_constraints_include": [
      "greenlight.org"
    ],
    "display_name": "GreenLight domain Only Policy",
    "description": "Only allow access from @greenlight.org",
    "id": "bcdf0444-b768-11ef-8ee1-0242ac110002",
    "domain_constraints_exclude": null,
    "project_id": "da84e531-1afb-43cb-8c87-135ab580516a",
    "authentication_assurance_timeout": 35
  }
}

DELETE /v2/api/policies/{policy_id}

See Delete Policy in the API documentation for details.

get_client(*, client_id=MISSING, fqdn=MISSING)[source]

Look up a client by client_id or (exclusive) by fqdn. Requires the manage_projects scope.

Parameters:

  • client_id (UUID | str | MissingType) – The ID of the client to look up

  • fqdn (str | MissingType) – The fully-qualified domain name of the client to look up

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> # by client_id
>>> r = ac.get_client(client_id="6336437e-37e8-4559-82a8-674390c1fd2e")
>>> r.data
{
  'client': {
    'required_idp': None,
    'name': 'Great client of FOO',
    'redirect_uris': [],
    'links': {
      'privacy_policy': None,
      'terms_and_conditions': None
    },
    'scopes': [],
    'grant_types': [
      'authorization_code',
      'client_credentials',
      'refresh_token'
    ],
    'id': '6336437e-37e8-4559-82a8-674390c1fd2e',
    'prompt_for_named_grant': False,
    'fqdns': ['globus.org'],
    'project': 'da84e531-1afb-43cb-8c87-135ab580516a',
    'client_type': 'client_identity',
    'visibility': 'private',
    'parent_client': None,
    'userinfo_from_effective_identity': True,
    'preselect_idp': None,
    'public_client': False
  }
}
>>> # by fqdn
>>> fqdn = ...
>>> r = ac.get_client(fqdn=fqdn)

{
  "client": {
    "required_idp": null,
    "name": "Great client of FOO",
    "redirect_uris": [],
    "links": {
      "privacy_policy": null,
      "terms_and_conditions": null
    },
    "scopes": [],
    "grant_types": [
      "authorization_code",
      "client_credentials",
      "refresh_token"
    ],
    "id": "bce00d9e-b768-11ef-8ee1-0242ac110002",
    "prompt_for_named_grant": false,
    "fqdns": [
      "globus.org"
    ],
    "project": "da84e531-1afb-43cb-8c87-135ab580516a",
    "client_type": "client_identity",
    "visibility": "private",
    "parent_client": null,
    "userinfo_from_effective_identity": true,
    "preselect_idp": null,
    "public_client": false
  }
}

GET /v2/api/clients/{client_id} GET /v2/api/clients?fqdn={fqdn}

See Get Clients in the API documentation for details.

get_clients()[source]

Look up clients in projects on which the authenticated user is an admin. Requires the manage_projects scope.

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_clients()
>>> r.data
{
  'clients': [
    {
      'required_idp': None,
      'name': 'Great client of FOO',
      'redirect_uris': [],
      'links': {'privacy_policy': None, 'terms_and_conditions': None},
      'scopes': [],
      'grant_types': ['authorization_code', 'client_credentials', 'refresh_token'],
      'id': 'b6001d11-8765-49d3-a503-ba323fc74eee',
      'prompt_for_named_grant': False,
      'fqdns': ['foo.net'],
      'project': 'da84e531-1afb-43cb-8c87-135ab580516a',
      'client_type': 'client_identity',
      'visibility': 'private',
      'parent_client': None,
      'userinfo_from_effective_identity': True,
      'preselect_idp': None,
      'public_client': False,
    },
    {
      'required_idp': None,
      'name': 'Lessor client of BAR',
      'redirect_uris': [],
      'links': {'privacy_policy': None, 'terms_and_conditions': None},
      'scopes': [],
      'grant_types': ['authorization_code', 'client_credentials', 'refresh_token'],
      'id': 'b87f7415-ddf9-4868-8e55-d10c065f733d',
      'prompt_for_named_grant': False,
      'fqdns': ['bar.org'],
      'project': 'da84e531-1afb-43cb-8c87-135ab580516a',
      'client_type': 'client_identity',
      'visibility': 'private',
      'parent_client': None,
      'userinfo_from_effective_identity': True,
      'preselect_idp': None,
      'public_client': False,
    }
  ]
}

{
  "clients": [
    {
      "required_idp": null,
      "name": "Lessor client of BAR",
      "redirect_uris": [],
      "links": {
        "privacy_policy": null,
        "terms_and_conditions": null
      },
      "scopes": [],
      "grant_types": [
        "authorization_code",
        "client_credentials",
        "refresh_token"
      ],
      "id": "bce0df1c-b768-11ef-8ee1-0242ac110002",
      "prompt_for_named_grant": false,
      "fqdns": [
        "bar.org"
      ],
      "project": "da84e531-1afb-43cb-8c87-135ab580516a",
      "client_type": "client_identity",
      "visibility": "private",
      "parent_client": null,
      "userinfo_from_effective_identity": true,
      "preselect_idp": null,
      "public_client": false
    },
    {
      "required_idp": null,
      "name": "Great client of FOO",
      "redirect_uris": [],
      "links": {
        "privacy_policy": null,
        "terms_and_conditions": null
      },
      "scopes": [],
      "grant_types": [
        "authorization_code",
        "client_credentials",
        "refresh_token"
      ],
      "id": "bce0de40-b768-11ef-8ee1-0242ac110002",
      "prompt_for_named_grant": false,
      "fqdns": [
        "foo.net"
      ],
      "project": "da84e531-1afb-43cb-8c87-135ab580516a",
      "client_type": "client_identity",
      "visibility": "private",
      "parent_client": null,
      "userinfo_from_effective_identity": true,
      "preselect_idp": null,
      "public_client": false
    }
  ]
}

GET /v2/api/clients

See Get Clients in the API documentation for details.

Return type:

IterableResponse

create_client(name, project, *, public_client=MISSING, client_type=MISSING, visibility=MISSING, redirect_uris=MISSING, terms_and_conditions=MISSING, privacy_policy=MISSING, required_idp=MISSING, preselect_idp=MISSING, additional_fields=MISSING)[source]

Create a new client. Requires the manage_projects scope.

Parameters:

  • name (str) – The display name shown to users on consents. May not contain linebreaks.

  • project (UUID | str) – ID representing the project this client belongs to.

  • public_client (bool | MissingType) – This is used to infer which OAuth grant_types the client will be able to use. Should be false if the client is capable of keeping secret credentials (such as clients running on a server) and true if it is not (such as native apps). After creation this value is immutable. This option is mutually exclusive with client_type, exactly one must be given.

  • client_type (MissingType | Literal['client_identity', 'confidential_client', 'globus_connect_server', 'public_installed_client', 'hybrid_confidential_client_resource_server', 'resource_server']) –

    Defines the type of client that will be created. This option is mutually exclusive with public_client, exactly one must be given.

    Values for client_type

    "confidential_client"

    Applications that are OAuth confidential clients, and can manage a client secret and requests for user consent.

    "public_installed_client"

    Applications that are OAuth public clients or native applications that are distributed to users, and thus cannot manage a client secret.

    "client_identity"

    Applications that authenticate and act as the application itself. These applications are used for automation and as service or community accounts, and do NOT act on behalf of other users. Also known as a “Service Account”.

    "resource_server"

    An API (OAuth resource server) that uses Globus Auth tokens for authentication. Users accessing the service login via Globus and consent for the client to use your API.

    "globus_connect_server"

    Create a client that will service as a Globus Connect Server endpoint.

    "hybrid_confidential_client_resource_server"

    A client which can use any behavior with Globus Auth - an application (confidential or public client), service account, or API.

  • visibility (MissingType | Literal['public', 'private']) – If set to “public”, any authenticated entity can view it. When set to “private”, only entities in the same project as the client can view it.

  • redirect_uris (Iterable[str] | MissingType) – list of URIs that may be used in OAuth authorization flows.

  • terms_and_conditions (str | MissingType) – URL of client’s terms and conditions.

  • privacy_policy (str | MissingType) – URL of client’s privacy policy.

  • required_idp (UUID | str | MissingType) – In order to use this client a user must have an identity from this IdP in their identity set.

  • preselect_idp (UUID | str | MissingType) – This pre-selects the given IdP on the Globus Auth login page if the user is not already authenticated.

  • additional_fields (dict[str, Any] | MissingType) – Any additional parameters to be passed through.

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> project = ...
>>> r = ac.create_client(
...     "My client",
...     True,
...     project,
...     True,
... )
>>> client_id = r["client"]["id"]

{
  "client": {
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "fqdns": [],
    "links": {
      "privacy_policy": null,
      "terms_and_conditions": null
    },
    "parent_client": null,
    "preselect_idp": null,
    "prompt_for_named_grant": true,
    "redirect_uris": [],
    "required_idp": null,
    "scopes": [],
    "userinfo_from_effective_identity": true,
    "name": "FOO",
    "project": "bce2fc7a-b768-11ef-8ee1-0242ac110002",
    "public_client": true,
    "client_type": "public_installed_client"
  }
}

POST /v2/api/clients

See Create Client in the API documentation for details.

update_client(client_id, *, name=MISSING, visibility=MISSING, redirect_uris=MISSING, terms_and_conditions=MISSING, privacy_policy=MISSING, required_idp=MISSING, preselect_idp=MISSING, additional_fields=MISSING)[source]

Update a client. Requires the manage_projects scope.

Parameters:

  • client_id (UUID | str) – ID of the client to update

  • name (str | MissingType) – The display name shown to users on consents. May not contain linebreaks.

  • visibility (MissingType | Literal['public', 'private']) – If set to “public”, any authenticated entity can view it. When set to “private”, only entities in the same project as the client can view it.

  • redirect_uris (Iterable[str] | MissingType) – list of URIs that may be used in OAuth authorization flows.

  • terms_and_conditions (str | None | MissingType) – URL of client’s terms and conditions.

  • privacy_policy (str | None | MissingType) – URL of client’s privacy policy.

  • required_idp (UUID | str | None | MissingType) – In order to use this client a user must have an identity from this IdP in their identity set.

  • preselect_idp (UUID | str | None | MissingType) – This pre-selects the given IdP on the Globus Auth login page if the user is not already authenticated.

  • additional_fields (dict[str, Any] | MissingType) – Any additional parameters to be passed through.

Return type:

GlobusHTTPResponse

When creating a project, your account is not necessarily included as an admin. The following snippet uses the manage_projects scope as well as the openid and email scopes to get the current user ID and email address and use those data to setup the project.

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> r = ac.create_update(client_id, name="Foo Utility")

{
  "client": {
    "client_type": "public_installed_client",
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "fqdns": [],
    "links": {
      "privacy_policy": null,
      "terms_and_conditions": null
    },
    "parent_client": null,
    "preselect_idp": null,
    "prompt_for_named_grant": true,
    "redirect_uris": [],
    "required_idp": null,
    "scopes": [],
    "userinfo_from_effective_identity": true,
    "id": "bce473a2-b768-11ef-8ee1-0242ac110002"
  }
}

POST /v2/api/clients/{client_id}

See Update Client in the API documentation for details.

delete_client(client_id)[source]

Delete a client. Requires the manage_projects scope.

Parameters:

client_id (UUID | str) – The ID of the client to delete

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> r = ac.delete_policy(client_id)

{
  "client": {
    "required_idp": null,
    "name": "Great client of FOO",
    "redirect_uris": [],
    "links": {
      "privacy_policy": null,
      "terms_and_conditions": null
    },
    "scopes": [],
    "grant_types": [
      "authorization_code",
      "client_credentials",
      "refresh_token"
    ],
    "id": "bce5a812-b768-11ef-8ee1-0242ac110002",
    "prompt_for_named_grant": false,
    "fqdns": [
      "globus.org"
    ],
    "project": "da84e531-1afb-43cb-8c87-135ab580516a",
    "client_type": "client_identity",
    "visibility": "private",
    "parent_client": null,
    "userinfo_from_effective_identity": true,
    "preselect_idp": null,
    "public_client": false
  }
}

DELETE /v2/api/clients/{client_id}

See Delete Client in the API documentation for details.

get_client_credentials(client_id)[source]

Look up client credentials by client_id. Requires the manage_projects scope.

Parameters:

client_id (UUID | str) – The ID of the client that owns the credentials

Return type:

IterableResponse

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_credentials("6336437e-37e8-4559-82a8-674390c1fd2e")
>>> r.data
{
  'credentials': [
    'name': 'foo',
    'id': 'cf88318e-b2dd-43fd-8ea5-2086fc69ffac',
    'created': '2023-10-21T22:46:15.845937+00:00',
    'client': '6336437e-37e8-4559-82a8-674390c1fd2e',
    'secret': None,
  ]
}

{
  "credentials": [
    {
      "name": "foo",
      "id": "bce688e0-b768-11ef-8ee1-0242ac110002",
      "created": "2023-10-21T22:46:15.845937+00:00",
      "client": "7dee4432-0297-4989-ad23-a2b672a52b12",
      "secret": null
    }
  ]
}

GET /v2/api/clients/{client_id}/credentials

See Get Client Credentials in the API documentation for details.

create_client_credential(client_id, name)[source]

Create a new client credential. Requires the manage_projects scope.

Parameters:

  • client_id (UUID | str) – ID for the client

  • name (str) – The display name of the new credential.

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> name = ...
>>> r = ac.create_client_credential(
...     "25afc56d-02af-4175-8c90-9941ebb623dd",
...     "New Credentials",
... )
>>> r.data
{
    'name': 'New Credentials',
    'id': '3a53cb4d-edd6-4ae3-900e-25b38b5fce02',
    'created': '2023-10-21T22:46:15.845937+00:00',
    'client': '25afc56d-02af-4175-8c90-9941ebb623dd',
    'secret': 'abc123',
}

{
  "credential": {
    "name": "foo",
    "id": "bce769fe-b768-11ef-8ee1-0242ac110002",
    "created": "2023-10-21T22:46:15.845937+00:00",
    "client": "bce76aa8-b768-11ef-8ee1-0242ac110002",
    "secret": "abc123"
  }
}

POST /v2/api/clients/{client_id}/credentials

See Create Client Credentials in the API documentation for details.

delete_client_credential(client_id, credential_id)[source]

Delete a credential. Requires the manage_projects scope.

Parameters:

  • client_id (UUID | str) – The ID of the client that owns the credential to delete

  • credential_id (UUID | str) – The ID of the credential to delete

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> credential_id = ...
>>> r = ac.delete_policy(client_id, credential_id)

{
  "credential": {
    "name": "foo",
    "id": "bce86566-b768-11ef-8ee1-0242ac110002",
    "created": "2023-10-21T22:46:15.845937+00:00",
    "client": "7dee4432-0297-4989-ad23-a2b672a52b12",
    "secret": null
  }
}

DELETE /v2/api/clients/{client_id}/credentials/{credential_id}

See Delete Credential in the API documentation for details.

get_scope(scope_id)[source]

Look up a scope by scope_id. Requires the manage_projects scope.

Parameters:

scope_id (UUID | str) – The ID of the scope to look up

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> r = ac.get_scope(scope_id="6336437e-37e8-4559-82a8-674390c1fd2e")
>>> r.data
{
  'scope': {
    'scope_string': 'https://auth.globus.org/scopes/3f33d83f-ec0a-4190-887d-0622e7c4ee9a/manager',
    'allows_refresh_token': False,
    'id': '87cf7b34-e1e1-4805-a8d5-51ab59fe6000',
    'advertised': False,
    'required_domains': [],
    'name': 'Client manage scope',
    'description': 'Manage configuration of this client',
    'client': '3f33d83f-ec0a-4190-887d-0622e7c4ee9a',
    'dependent_scopes': [],
  }
}

{
  "scope": {
    "scope_string": "https://auth.globus.org/scopes/3f33d83f-ec0a-4190-887d-0622e7c4ee9a/manager",
    "allows_refresh_token": false,
    "id": "bce94b48-b768-11ef-8ee1-0242ac110002",
    "advertised": false,
    "required_domains": [],
    "name": "Client manage scope",
    "description": "Manage configuration of this client",
    "client": "3f33d83f-ec0a-4190-887d-0622e7c4ee9a",
    "dependent_scopes": []
  }
}

GET /v2/api/scopes/{scope_id}

See Get Scopes in the API documentation for details.

get_scopes(*, scope_strings=MISSING, ids=MISSING, query_params=MISSING)[source]

Look up scopes in projects on which the authenticated user is an admin. The scopes response can be filted by scope_strings or (exclusive) ids. Requires the manage_projects scope.

Parameters:
Return type:

IterableResponse

>>> ac = globus_sdk.AuthClient(...)
>>> # get all scopes
>>> r = ac.get_scopes()
>>> r.data
{
  'scopes': [
    {
      'scope_string': 'https://auth.globus.org/scopes/3f33d83f-ec0a-4190-887d-0622e7c4ee9a/manage',
      'allows_refresh_token': False,
      'id': '70147193-f88a-4da9-9d6e-677c15e790e5',
      'advertised': False,
      'required_domains': [],
      'name': 'Client manage scope',
      'description': 'Manage configuration of this client',
      'client': '3f33d83f-ec0a-4190-887d-0622e7c4ee9a',
      'dependent_scopes': [],
    },
    {
      'scope_string': 'https://auth.globus.org/scopes/dfc9a6d3-3373-4a6d-b0a1-b7026d1559d6/view',
      'allows_refresh_token': False,
      'id': '3793042a-203c-4e86-8dfe-17d407d0bb5f',
      'advertised': False,
      'required_domains': [],
      'name': 'Client view scope',
      'description': 'View configuration of this client',
      'client': 'dfc9a6d3-3373-4a6d-b0a1-b7026d1559d6',
      'dependent_scopes': [],
    }
  ]
}

>>> # by all scope ids
>>> scope_ids = ...
>>> r = ac.get_scopes(ids=scopes_ides)

>>> # by all scope strings
>>> scope_strings = ...
>>> r = ac.get_scopes(scope_strings=scope_strings)

{
  "scopes": [
    {
      "scope_string": "https://auth.globus.org/scopes/3f33d83f-ec0a-4190-887d-0622e7c4ee9a/manage",
      "allows_refresh_token": false,
      "id": "bcea380a-b768-11ef-8ee1-0242ac110002",
      "advertised": false,
      "required_domains": [],
      "name": "Client manage scope",
      "description": "Manage configuration of this client",
      "client": "3f33d83f-ec0a-4190-887d-0622e7c4ee9a",
      "dependent_scopes": []
    },
    {
      "scope_string": "https://auth.globus.org/scopes/dfc9a6d3-3373-4a6d-b0a1-b7026d1559d6/view",
      "allows_refresh_token": false,
      "id": "bcea38e6-b768-11ef-8ee1-0242ac110002",
      "advertised": false,
      "required_domains": [],
      "name": "Client view scope",
      "description": "View configuration of this client",
      "client": "dfc9a6d3-3373-4a6d-b0a1-b7026d1559d6",
      "dependent_scopes": []
    }
  ]
}

GET /v2/api/scopes GET /v2/api/scopes?ids=... GET /v2/api/scopes?scope_strings=...

See Get Scopes in the API documentation for details.

create_scope(client_id, name, description, scope_suffix, *, required_domains=MISSING, dependent_scopes=MISSING, advertised=MISSING, allows_refresh_token=MISSING)[source]

Create a new scope. Requires the manage_projects scope.

Parameters:

  • client_id (UUID | str) – ID of the client for the new scope

  • name (str) – A display name used to display consents to users, along with description

  • description (str) – A description used to display consents to users, along with name

  • scope_suffix (str) – String consisting of lowercase letters, number, and underscores. This will be the final part of the scope_string

  • required_domains (Iterable[str] | MissingType) – Domains the user must have linked identities in in order to make use of the scope

  • dependent_scopes (Iterable[DependentScopeSpec] | MissingType) – Scopes included in the consent for this new scope

  • advertised (bool | MissingType) – If True, scope is visible to anyone regardless of client visibility, otherwise, scope visibility is based on client visibility.

  • allows_refresh_token (bool | MissingType) – Whether or not the scope allows refresh tokens to be issued.

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> client_id = ...
>>> r = ac.create_scope(
...     client_id,
...     "Client Management",
...     "Manage client configuration",
...     "manage",
... )
>>> scope_id = r["scope"]["id"]

{
  "scope": {
    "scope_string": "https://auth.globus.org/scopes/bceb8638-b768-11ef-8ee1-0242ac110002/manage",
    "allows_refresh_token": true,
    "id": "bceb876e-b768-11ef-8ee1-0242ac110002",
    "advertised": false,
    "required_domains": [],
    "name": "Client manage scope",
    "description": "Manage configuration of this client",
    "client": "bceb8638-b768-11ef-8ee1-0242ac110002",
    "dependent_scopes": []
  }
}

POST /v2/api/clients/{client_id}/scopes

See Create Scope in the API documentation for details.

update_scope(scope_id, *, name=MISSING, description=MISSING, scope_suffix=MISSING, required_domains=MISSING, dependent_scopes=MISSING, advertised=MISSING, allows_refresh_token=MISSING)[source]

Update a scope. Requires the manage_projects scope.

Parameters:

  • scope_id (UUID | str) – ID of the scope to update

  • name (str | MissingType) – A display name used to display consents to users, along with description

  • description (str | MissingType) – A description used to display consents to users, along with name

  • scope_suffix (str | MissingType) – String consisting of lowercase letters, number, and underscores. This will be the final part of the scope_string

  • required_domains (Iterable[str] | MissingType) – Domains the user must have linked identities in in order to make use of the scope

  • dependent_scopes (Iterable[DependentScopeSpec] | MissingType) – Scopes included in the consent for this new scope

  • advertised (bool | MissingType) – If True, scope is visible to anyone regardless of client visibility, otherwise, scope visibility is based on client visibility.

  • allows_refresh_token (bool | MissingType) – Whether or not the scope allows refresh tokens to be issued.

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> scope_id = ...
>>> r = ac.update_scope(scope_id, scope_suffix="manage")

{
  "scope": {
    "scope_string": "https://auth.globus.org/scopes/bcecd3c6-b768-11ef-8ee1-0242ac110002/dc7a3725ef58420da0a3cd8fd473fe4f",
    "allows_refresh_token": true,
    "id": "bcecd29a-b768-11ef-8ee1-0242ac110002",
    "advertised": false,
    "required_domains": [],
    "name": "7dd04137bc1c417e94184ce2a8c2c638",
    "description": "7c15cfab252e44c68a56d80ad189eb0e",
    "client": "bcecd510-b768-11ef-8ee1-0242ac110002",
    "dependent_scopes": []
  }
}

POST /v2/api/scopes/{scope_id}

See Update Scope in the API documentation for details.

delete_scope(scope_id)[source]

Delete a scope. Requires the manage_projects scope.

Parameters:

scope_id (UUID | str) – The ID of the scope to delete

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> scope_id = ...
>>> r = ac.delete_scope(scope_id)

{
  "scope": {
    "scope_string": "https://auth.globus.org/scopes/3f33d83f-ec0a-4190-887d-0622e7c4ee9a/manager",
    "allows_refresh_token": false,
    "id": "bcedea72-b768-11ef-8ee1-0242ac110002",
    "advertised": false,
    "required_domains": [],
    "name": "Client manage scope",
    "description": "Manage configuration of this client",
    "client": "3f33d83f-ec0a-4190-887d-0622e7c4ee9a",
    "dependent_scopes": []
  }
}

DELETE /v2/api/scopes/{scope_id}

See Delete Scopes in the API documentation for details.

get_consents(identity_id, *, all=False)[source]

Look up consents for a user.

If requesting “all” consents, the view_consents scope is required.

Parameters:

  • identity_id (UUID | str) – The ID of the identity to look up consents for

  • all (bool) – If true, return all consents, including those that have been issued to other clients. If false, return only consents rooted at this client id for the requested identity. Most clients should pass False.

Return type:

GetConsentsResponse

>>> ac = globus_sdk.AuthClient(...)
>>> identity_id = ...
>>> forest = ac.get_consents(identity_id).to_forest()

{
  "consents": [
    {
      "created": "2022-09-21T17:10:14.270581+00:00",
      "id": 142632,
      "status": "approved",
      "updated": "2022-09-21T17:10:14.270581+00:00",
      "allows_refresh": true,
      "dependency_path": [
        142632
      ],
      "scope_name": "urn:globus:auth:scope:transfer.api.globus.org:all",
      "atomically_revocable": false,
      "effective_identity": "8ca28797-3541-4a5d-a264-05b00f91e608",
      "auto_approved": false,
      "last_used": "2024-03-18T17:34:04.719126+00:00",
      "scope": "89ecabba-4acf-4e2e-a98d-ce592ccc2818",
      "client": "065db752-2f43-4fe1-a633-2ee68c9da889"
    },
    {
      "created": "2024-03-18T17:32:51.496893+00:00",
      "id": 433892,
      "status": "approved",
      "updated": "2024-03-18T17:32:51.496893+00:00",
      "allows_refresh": true,
      "dependency_path": [
        142632,
        433892
      ],
      "scope_name": "https://auth.globus.org/scopes/542a86fc-1766-450d-841f-065488a2ec01/data_access",
      "atomically_revocable": true,
      "effective_identity": "8ca28797-3541-4a5d-a264-05b00f91e608",
      "auto_approved": false,
      "last_used": "2024-03-18T17:33:05.178254+00:00",
      "scope": "fe334c19-4fe6-4d03-ac73-8992beb231b6",
      "client": "2fbdda78-a599-4cb5-ac3d-1fbcfbc6a754"
    }
  ]
}

GET /v2/api/identities/{identity_id}/consents

class globus_sdk.AuthLoginClient(client_id=None, environment=None, base_url=None, authorizer=None, app_name=None, transport_params=None)[source]

Bases: BaseClient

This client class provides the common base for clients providing login functionality via Globus Auth

Parameters:

client_id (UUIDLike | None) – The ID of the application provided by registration with Globus Auth.

All other initialization parameters are passed through to BaseClient.

Methods

error_class

alias of AuthAPIError

scopes: ScopeBuilder | None = <globus_sdk.scopes.data.auth._AuthScopesBuilder object>

the scopes for this client may be present as a ScopeBuilder

property default_scope_requirements: list[Scope]

Scopes that will automatically be added to this client’s app’s scope_requirements during _finalize_app.

For clients with static scope requirements this can just be a static value. Clients with dynamic requirements should use @property and must return sane results while the Base Client is being initialized.

get_openid_configuration()[source]

Fetch the OpenID Connect configuration data from the well-known URI for Globus Auth.

Return type:

GlobusHTTPResponse

get_jwk(openid_configuration: None | GlobusHTTPResponse | dict[str, Any], *, as_pem: Literal[True]) → RSAPublicKey[source]
get_jwk(openid_configuration: None | GlobusHTTPResponse | dict[str, Any], *, as_pem: Literal[False]) → dict[str, Any]

Fetch the Globus Auth JWK.

Returns either a dict or an RSA Public Key object depending on as_pem.

Parameters:

  • openid_configuration – The OIDC config as a GlobusHTTPResponse or dict. When not provided, it will be fetched automatically.

  • as_pem – Decode the JWK to an RSA PEM key, typically for JWT decoding

oauth2_get_authorize_url(*, session_required_identities=None, session_required_single_domain=None, session_required_policies=None, session_required_mfa=None, prompt=None, query_params=None)[source]

Get the authorization URL to which users should be sent. This method may only be called after oauth2_start_flow has been called on this AuthClient.

Parameters:

  • session_required_identities (Iterable[UUID | str] | UUID | str | None) – A list of identities must be added to the session.

  • session_required_single_domain (Iterable[str] | str | None) – A list of domain requirements which must be satisfied by identities added to the session.

  • session_required_policies (Iterable[UUID | str] | UUID | str | None) – A list of IDs for policies which must be satisfied by the user.

  • session_required_mfa (bool | None) – Whether MFA is required for the session.

  • prompt (Literal['login'] | None) –

    Control whether a user is required to log in before the authorization step.

    If set to “login”, the user must authenticate with an identity provider even if they are already logged in. Setting this parameter can help ensure that a user’s session meets known or unknown session requirement policies and avoid additional login flows.

  • query_params (dict[str, Any] | None) – Additional query parameters to include in the authorize URL. Primarily for internal use

Return type:

str

oauth2_exchange_code_for_tokens(auth_code)[source]

Exchange an authorization code for a token or tokens.

Parameters:

auth_code (str) – An auth code typically obtained by sending the user to the authorize URL. The code is a very short-lived credential which this method is exchanging for tokens. Tokens are the credentials used to authenticate against Globus APIs.

Return type:

OAuthAuthorizationCodeResponse

oauth2_refresh_token(refresh_token, *, body_params=None)[source]

Exchange a refresh token for a OAuthTokenResponse, containing an access token.

Does a token call of the form

refresh_token=<refresh_token>
grant_type=refresh_token

plus any additional parameters you may specify.

Parameters:

  • refresh_token (str) – A Globus Refresh Token as a string

  • body_params (dict[str, Any] | None) – A dict of extra params to encode in the refresh call.

Return type:

OAuthRefreshTokenResponse

oauth2_validate_token(token, *, body_params=None)[source]

Deprecated. Because the validity of a token may be dependent on policies enforced both by Globus Auth and the resource server, this method is not considered a reliable way to check token validity. Users are encouraged to treat tokens as valid until proven otherwise instead.

Parameters:

  • token (str) – The token which should be validated. Can be a refresh token or an access token

  • body_params (dict[str, Any] | None) – Additional parameters to include in the validation body. Primarily for internal use

Return type:

GlobusHTTPResponse

oauth2_revoke_token(token, *, body_params=None)[source]

Revoke a token. It can be an Access Token or a Refresh token.

This call should be used to revoke tokens issued to your client, rendering them inert and not further usable. Typically, this is incorporated into “logout” functionality, but it should also be used if the client detects that its tokens are in an unsafe location (e.x. found in a world-readable logfile).

You can check the “active” status of the token after revocation if you want to confirm that it was revoked.

Parameters:

  • token (str) – The token which should be revoked

  • body_params (dict[str, Any] | None) – Additional parameters to include in the revocation body, which can help speed the revocation process. Primarily for internal use

Return type:

GlobusHTTPResponse

Examples

>>> from globus_sdk import ConfidentialAppAuthClient
>>> ac = ConfidentialAppAuthClient(CLIENT_ID, CLIENT_SECRET)
>>> ac.oauth2_revoke_token('<token_string>')
oauth2_token(form_data: dict[str, Any] | PayloadWrapper) → OAuthTokenResponse[source]
oauth2_token(form_data: dict[str, Any] | PayloadWrapper, *, body_params: dict[str, Any] | None) → OAuthTokenResponse
oauth2_token(form_data: dict[str, Any] | PayloadWrapper, *, response_class: type[RT]) → RT
oauth2_token(form_data: dict[str, Any] | PayloadWrapper, *, body_params: dict[str, Any] | None, response_class: type[RT]) → RT

This is the generic form of calling the OAuth2 Token endpoint. It takes form_data, a dict which will be encoded in a form POST body on the request.

Generally, users of the SDK should not call this method unless they are implementing OAuth2 flows.

Parameters:

  • response_class – This is used by calls to the oauth2_token endpoint which need to specialize their responses. For example, oauth2_get_dependent_tokens requires a specialize response class to handle the dramatically different format of the Dependent Token Grant response

  • form_data – The main body of the request

  • body_params – Any additional parameters to be passed through as body parameters.

Return type:

response_class if set, defaults to OAuthTokenResponse

class globus_sdk.NativeAppAuthClient(client_id, environment=None, base_url=None, app_name=None, transport_params=None)[source]

Bases: AuthLoginClient

This type of AuthLoginClient is used to represent a Native App’s communications with Globus Auth. It requires a Client ID, and cannot take an authorizer.

Native Apps are applications, like the Globus CLI, which are run client-side and therefore cannot keep secrets. Unable to possess client credentials, several Globus Auth interactions have to be specialized to accommodate the absence of a secret.

Any keyword arguments given are passed through to the AuthClient constructor.

Methods

oauth2_start_flow(requested_scopes=None, *, redirect_uri=None, state='_default', verifier=None, refresh_tokens=False, prefill_named_grant=None)[source]

Starts a Native App OAuth2 flow.

This is done internally by instantiating a GlobusNativeAppFlowManager

While the flow is in progress, the NativeAppAuthClient becomes non thread-safe as temporary state is stored during the flow.

Parameters:

  • requested_scopes (ScopeCollectionType | None) – The scopes on the token(s) being requested. Defaults to openid profile email urn:globus:auth:scope:transfer.api.globus.org:all

  • redirect_uri (str | None) – The page that users should be directed to after authenticating at the authorize URL. Defaults to ‘https://auth.globus.org/v2/web/auth-code’, which displays the resulting auth_code for users to copy-paste back into your application (and thereby be passed back to the GlobusNativeAppFlowManager)

  • state (str) – The redirect_uri page will have this included in a query parameter, so you can use it to pass information to that page if you use a custom page. It defaults to the string ‘_default’

  • verifier (str | None) – A secret used for the Native App flow. It will by default be a freshly generated random string, known only to this GlobusNativeAppFlowManager instance

  • refresh_tokens (bool) – When True, request refresh tokens in addition to access tokens. [Default: False]

  • prefill_named_grant (str | None) – Prefill the named grant label on the consent page

Return type:

GlobusNativeAppFlowManager

You can see an example of this flow in the usage examples.

The Globus Auth specification for Native App grants details modifications to the Authorization Code grant flow as The PKCE Security Protocol.

oauth2_refresh_token(refresh_token, *, body_params=None)[source]

NativeAppAuthClient specializes the refresh token grant to include its client ID as a parameter in the POST body. It needs this specialization because it cannot authenticate the refresh grant call with client credentials, as is normal.

Parameters:

  • refresh_token (str) – The refresh token to use to get a new access token

  • body_params (dict[str, Any] | None) – Extra parameters to include in the POST body

Return type:

OAuthRefreshTokenResponse

create_native_app_instance(template_id, name)[source]

Create a new native app instance. The new instance is a confidential client.

param template_id:

The client ID of the calling native app

param name:

The name given to the new app instance

>>> ac = globus_sdk.NativeAppAuthClient(...)
>>> template_id = ...
>>> r = ac.create_native_app_instance(
...     template_id,
...     "My new native app instance",
... )
>>> client_id = r["client"]["id"]

{
  "client": {
    "client": {
      "fqdns": [],
      "name": "bcfecce8b76811ef8ee10242ac110002",
      "id": "e634cc2a-d528-494e-8dda-92ec54a883c9",
      "public_client": false,
      "scopes": [],
      "required_idp": null,
      "grant_types": [
        "authorization_code",
        "client_credentials",
        "refresh_token"
      ],
      "userinfo_from_effective_identity": true,
      "client_type": "confidential_client",
      "prompt_for_named_grant": false,
      "links": {
        "privacy_policy": null,
        "terms_and_conditions": null
      },
      "visibility": "private",
      "preselect_idp": null,
      "parent_client": "bcfecbbc-b768-11ef-8ee1-0242ac110002",
      "project": null,
      "redirect_uris": []
    },
    "included": {
      "client_credential": {
        "name": "Auto-created at client creation",
        "id": "b4840855-2de8-4035-b1b4-4e7c8f518943",
        "client": "e634cc2a-d528-494e-8dda-92ec54a883c9",
        "secret": "cgK1HG9Y0DcZw79YlQEJpZCF4CMxIbaFf5sohWxjcfY="
      }
    }
  }
}

POST /v2/api/clients

See Create Client in the API documentation for details.

Return type:

GlobusHTTPResponse

class globus_sdk.ConfidentialAppAuthClient(client_id, client_secret, environment=None, base_url=None, app_name=None, transport_params=None)[source]

Bases: AuthLoginClient

This is a specialized type of AuthLoginClient used to represent an App with a Client ID and Client Secret wishing to communicate with Globus Auth. It must be given a Client ID and a Client Secret, and furthermore, these will be used to establish a BasicAuthorizer for authorization purposes. Additionally, the Client ID is stored for use in various calls.

Confidential Applications are those which have their own credentials for authenticating against Globus Auth.

Parameters:

  • client_id (UUIDLike) – The ID of the application provided by registration with Globus Auth.

  • client_secret (str) – The secret string to use for authentication. Secrets can be generated via the Globus developers interface.

All other initialization parameters are passed through to BaseClient.

Methods

get_identities(*, usernames=None, ids=None, provision=False, query_params=None)[source]

Perform a call to the Get Identities API using the direct client credentials of this client.

This method is considered deprecated – callers should instead use client credentials to get a token and then use that token to call the API via a AuthClient.

Parameters:

  • usernames (Iterable[str] | str | None) – A username or list of usernames to lookup. Mutually exclusive with ids

  • ids (Iterable[UUID | str] | UUID | str | None) – An identity ID or list of IDs to lookup. Mutually exclusive with usernames

  • provision (bool) – Create identities if they do not exist, allowing clients to get username-to-identity mappings prior to the identity being used

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GetIdentitiesResponse

oauth2_client_credentials_tokens(requested_scopes=None)[source]

Perform an OAuth2 Client Credentials Grant to get access tokens which directly represent your client and allow it to act on its own (independent of any user authorization). This method does not use a GlobusOAuthFlowManager because it is not at all necessary to do so.

Parameters:

requested_scopes (ScopeCollectionType | None) – The scopes on the token(s) being requested. Defaults to openid profile email urn:globus:auth:scope:transfer.api.globus.org:all

Return type:

OAuthClientCredentialsResponse

For example, with a Client ID of “CID1001” and a Client Secret of “RAND2002”, you could use this grant type like so:

>>> client = ConfidentialAppAuthClient("CID1001", "RAND2002")
>>> tokens = client.oauth2_client_credentials_tokens()
>>> transfer_token_info = (
...     tokens.by_resource_server["transfer.api.globus.org"])
>>> transfer_token = transfer_token_info["access_token"]
oauth2_start_flow(redirect_uri, requested_scopes=None, *, state='_default', refresh_tokens=False)[source]

Starts or resumes an Authorization Code OAuth2 flow.

Under the hood, this is done by instantiating a GlobusAuthorizationCodeFlowManager

Parameters:

  • redirect_uri (str) – The page that users should be directed to after authenticating at the authorize URL.

  • requested_scopes (ScopeCollectionType | None) – The scopes on the token(s) being requested. Defaults to openid profile email urn:globus:auth:scope:transfer.api.globus.org:all

  • state (str) – This string allows an application to pass information back to itself in the course of the OAuth flow. Because the user will navigate away from the application to complete the flow, this parameter lets the app pass an arbitrary string from the starting page to the redirect_uri

  • refresh_tokens (bool) – When True, request refresh tokens in addition to access tokens. [Default: False]

Return type:

GlobusAuthorizationCodeFlowManager

You can see an example of this flow in the usage examples.

The Authorization Code Grant flow is described in the Globus Auth Specification.

oauth2_get_dependent_tokens(token, *, refresh_tokens=False, scope=MISSING, additional_params=None)[source]

Fetch Dependent Tokens from Globus Auth.

This exchanges a token given to this client for a new set of tokens which give it access to resource servers on which it depends. This grant type is intended for use by Resource Servers playing out the following scenario:

  1. User has tokens for Service A, but Service A requires access to Service B on behalf of the user

  2. Service B should not see tokens scoped for Service A

  3. Service A therefore requests tokens scoped only for Service B, based on tokens which were originally scoped for Service A…

In order to do this exchange, the tokens for Service A must have scopes which depend on scopes for Service B (the services’ scopes must encode their relationship). As long as that is the case, Service A can use this Grant to get those “Dependent” or “Downstream” tokens for Service B.

Parameters:

  • token (str) – An access token as a string

  • refresh_tokens (bool) – When True, request dependent refresh tokens in addition to access tokens. [Default: False]

  • scope (Iterable[str] | str | MissingType) – The scope or scopes of the dependent tokens which are being requested. Applications are recommended to provide this string to ensure that they are receiving the tokens they expect. If omitted, all available dependent tokens will be returned.

  • additional_params (dict[str, Any] | None) – Additional parameters to include in the request body

Return type:

OAuthDependentTokenResponse

Given a token, getting a dependent token for Globus Groups might look like the following:

ac = globus_sdk.ConfidentialAppAuthClient(CLIENT_ID, CLIENT_SECRET)
dependent_token_data = ac.oauth2_get_dependent_tokens(
    "<token_string>",
    scope="urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships",
)

group_token_data = dependent_token_data.by_resource_server["groups.api.globus.org"]
group_token = group_token_data["access_token"]

[
  {
    "scope": "urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships",
    "access_token": "groupsToken",
    "token_type": "bearer",
    "expires_in": 120,
    "resource_server": "groups.api.globus.org"
  }
]

POST /v2/oauth2/token

See Dependent Token Grant in the API documentation for details.

oauth2_token_introspect(token, *, include=None, query_params=None)[source]

Get information about a Globus Auth token.

Parameters:

  • token (str) – An Access Token as a raw string, being evaluated

  • include (str | None) – A value for the include parameter in the request body. Default is to omit the parameter.

  • query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params.

Return type:

GlobusHTTPResponse

ac = globus_sdk.ConfidentialAppAuthClient(CLIENT_ID, CLIENT_SECRET)
ac.oauth2_token_introspect("<token_string>")

Get information about a Globus Auth token including the full identity set of the user to whom it belongs

ac = globus_sdk.ConfidentialAppAuthClient(CLIENT_ID, CLIENT_SECRET)
data = ac.oauth2_token_introspect("<token_string>", include="identity_set")
for identity in data["identity_set"]:
    print('token authenticates for "{}"'.format(identity))

POST /v2/oauth2/token/introspect

See Token Introspection in the API documentation for details.

create_child_client(name, *, public_client=MISSING, client_type=MISSING, visibility=MISSING, redirect_uris=MISSING, terms_and_conditions=MISSING, privacy_policy=MISSING, required_idp=MISSING, preselect_idp=MISSING, additional_fields=MISSING)[source]

Create a new client. Requires the manage_projects scope.

Parameters:

  • name (str) – The display name shown to users on consents. May not contain linebreaks.

  • public_client (bool | MissingType) – This is used to infer which OAuth grant_types the client will be able to use. Should be false if the client is capable of keeping secret credentials (such as clients running on a server) and true if it is not (such as native apps). After creation this value is immutable. This option is mutually exclusive with client_type, exactly one must be given.

  • client_type (Literal['client_identity', 'confidential_client', 'globus_connect_server', 'public_installed_client', 'hybrid_confidential_client_resource_server', 'resource_server'] | ~globus_sdk.utils.MissingType) –

    Defines the type of client that will be created. This option is mutually exclusive with public_client, exactly one must be given.

    Values for client_type

    "confidential_client"

    Applications that are OAuth confidential clients, and can manage a client secret and requests for user consent.

    "public_installed_client"

    Applications that are OAuth public clients or native applications that are distributed to users, and thus cannot manage a client secret.

    "client_identity"

    Applications that authenticate and act as the application itself. These applications are used for automation and as service or community accounts, and do NOT act on behalf of other users. Also known as a “Service Account”.

    "resource_server"

    An API (OAuth resource server) that uses Globus Auth tokens for authentication. Users accessing the service login via Globus and consent for the client to use your API.

    "globus_connect_server"

    Create a client that will service as a Globus Connect Server endpoint.

    "hybrid_confidential_client_resource_server"

    A client which can use any behavior with Globus Auth - an application (confidential or public client), service account, or API.

  • visibility (Literal['public', 'private'] | ~globus_sdk.utils.MissingType) – If set to “public”, any authenticated entity can view it. When set to “private”, only entities in the same project as the client can view it.

  • redirect_uris (Iterable[str] | MissingType) – list of URIs that may be used in OAuth authorization flows.

  • terms_and_conditions (str | MissingType) – URL of client’s terms and conditions.

  • privacy_policy (str | MissingType) – URL of client’s privacy policy.

  • required_idp (UUID | str | MissingType) – In order to use this client a user must have an identity from this IdP in their identity set.

  • preselect_idp (UUID | str | MissingType) – This pre-selects the given IdP on the Globus Auth login page if the user is not already authenticated.

  • additional_fields (dict[str, Any] | MissingType) – Any additional parameters to be passed through.

Return type:

GlobusHTTPResponse

>>> ac = globus_sdk.AuthClient(...)
>>> project_id = ...
>>> r = ac.create_child_client(
...     "My client",
...     True,
...     True,
... )
>>> client_id = r["client"]["id"]

{
  "client": {
    "grant_types": [
      "authorization_code",
      "refresh_token"
    ],
    "fqdns": [],
    "links": {
      "privacy_policy": null,
      "terms_and_conditions": null
    },
    "parent_client": null,
    "preselect_idp": null,
    "prompt_for_named_grant": true,
    "redirect_uris": [],
    "required_idp": null,
    "scopes": [],
    "userinfo_from_effective_identity": true,
    "name": "FOO",
    "visibility": "public",
    "public_client": true,
    "client_type": "public_installed_client"
  }
}

POST /v2/api/clients

See Create Client in the API documentation for details.

Helper Objects

The IdentityMap is a specialized object which aids in the particular use-case in which the Globus Auth AuthClient.get_identities() API is being used to resolve large numbers of usernames or IDs. It combines caching, request batching, and other functionality.

class globus_sdk.IdentityMap(auth_client, identity_ids=None, *, id_batch_size=None, cache=None)[source]

Bases: object

There’s a common pattern of having a large batch of Globus Auth Identities which you want to inspect. For example, you may have a list of identity IDs fetched from Access Control Lists on Globus Endpoints. In order to display these identities to an end user, you may want to resolve them to usernames.

However, naively looking up the identities one-by-one is very inefficient. It’s best to do batched lookups with multiple identities at once. In these cases, an IdentityMap can be used to do those batched lookups for you.

An IdentityMap is a mapping-like type which converts Identity IDs and Identity Names to Identity records (dictionaries) using the Globus Auth API.

Note

IdentityMap objects are not full Mappings in the same sense as python dicts and similar objects. By design, they only implement a small part of the Mapping protocol.

The basic usage pattern is

  • create an IdentityMap with an AuthClient which will be used to call out to Globus Auth

  • seed the IdentityMap with IDs and Usernames via add() (you can also do this during initialization)

  • retrieve identity IDs or Usernames from the map

Because the map can be populated with a collection of identity IDs and Usernames prior to lookups being performed, it can improve the efficiency of these operations up to 100x over individual lookups.

If you attempt to retrieve an identity which has not been previously added to the map, it will be immediately added. But adding many identities beforehand will improve performance.

The IdentityMap will cache its results so that repeated lookups of the same Identity will not repeat work. It will also map identities both by ID and by Username, regardless of how they’re initially looked up.

Warning

If an Identity is not found in Globus Auth, it will trigger a KeyError when looked up. Your code must be ready to handle KeyErrors when doing a lookup.

Correct usage looks something like so:

ac = globus_sdk.AuthClient(...)
idmap = globus_sdk.IdentityMap(
    ac, ["foo@globusid.org", "bar@uchicago.edu"]
)
idmap.add("baz@xsede.org")
# adding by ID is also valid
idmap.add("c699d42e-d274-11e5-bf75-1fc5bf53bb24")
# map ID to username
assert (
    idmap["c699d42e-d274-11e5-bf75-1fc5bf53bb24"]["username"]
    == "go@globusid.org"
)
# map username to ID
assert (
    idmap["go@globusid.org"]["id"]
    == "c699d42e-d274-11e5-bf75-1fc5bf53bb24"
)

And simple handling of errors:

try:
    record = idmap["no-such-valid-id@example.org"]
except KeyError:
    username = "NO_SUCH_IDENTITY"
else:
    username = record["username"]

or you may achieve this by using the get() method:

# internally handles the KeyError and returns the default value
record = idmap.get("no-such-valid-id@example.org", None)
username = record["username"] if record is not None else "NO_SUCH_IDENTITY"
Parameters:

  • auth_client (AuthClient | ConfidentialAppAuthClient) – The client object which will be used for lookups against Globus Auth

  • identity_ids (t.Iterable[str] | None) – A list or other iterable of usernames or identity IDs (potentially mixed together) which will be used to seed the IdentityMap ‘s tracking of unresolved Identities.

  • id_batch_size (int | None) – A non-default batch size to use when communicating with Globus Auth. Leaving this set to the default is strongly recommended.

  • cache (None | t.MutableMapping[str, dict[str, t.Any]]) – A dict or other mapping object which will be used to cache results. The default is that results are cached once per IdentityMap object. If you want multiple IdentityMaps to share data, explicitly pass the same cache to both.

Methods

__delitem__(key)[source]

IdentityMap supports del map[key]. Note that this only removes lookup values from the cache and will not impact the set of unresolved/pending IDs.

__getitem__(key)[source]

IdentityMap supports dict-like lookups with map[key]

Return type:

Any

__init__(auth_client, identity_ids=None, *, id_batch_size=None, cache=None)[source]
add(identity_id)[source]

Add a username or ID to the IdentityMap for batch lookups later.

Returns True if the ID was added for lookup. Returns False if it was rejected as a duplicate of an already known name.

Parameters:

identity_id (str) – A string Identity ID or Identity Name (a.k.a. “username”) to add

Return type:

bool

get(key, default=None)[source]

A dict-like get() method which accepts a default value.

Parameters:

  • key (str) – The username or ID to look up

  • default (Any | None) – The default value to return if the key is not found

Return type:

Any

class globus_sdk.DependentScopeSpec(scope, optional, requires_refresh_token)[source]

Utility class for creating dependent scope values as parameters to AuthClient.create_scope and AuthClient.update_scope.

Parameters:

  • scope (UUID | str) – The ID of the dependent scope

  • optional (bool) – Whether or not the user can decline this specific scope without declining the whole consent.

  • requires_refresh_token (bool) – Whether or not the dependency requires a refresh token.

Auth Responses

class globus_sdk.OAuthTokenResponse(*args, **kwargs)[source]

Bases: GlobusHTTPResponse

Class for responses from the OAuth2 code for tokens exchange used in 3-legged OAuth flows.

property by_resource_server: dict[str, dict[str, Any]]

Representation of the token response in a dict indexed by resource server.

Although OAuthTokenResponse.data is still available and valid, this representation is typically more desirable for applications doing inspection of access tokens and refresh tokens.

property by_scopes: _ByScopesGetter

Representation of the token response in a dict-like object indexed by scope name (or even space delimited scope names, so long as they match the same token).

If you request scopes scope1 scope2 scope3, where scope1 and scope2 are for the same service (and therefore map to the same token), but scope3 is for a different service, the following forms of access are valid:

>>> tokens = ...
>>> # single scope
>>> token_data = tokens.by_scopes['scope1']
>>> token_data = tokens.by_scopes['scope2']
>>> token_data = tokens.by_scopes['scope3']
>>> # matching scopes
>>> token_data = tokens.by_scopes['scope1 scope2']
>>> token_data = tokens.by_scopes['scope2 scope1']
decode_id_token(openid_configuration=None, jwk=None, jwt_params=None)[source]

Parse the included ID Token (OIDC) as a dict and return it.

If you provide the jwk, you must also provide openid_configuration.

Parameters:

  • openid_configuration (None | GlobusHTTPResponse | dict[str, Any]) – The OIDC config as a GlobusHTTPResponse or dict. When not provided, it will be fetched automatically.

  • jwk (RSAPublicKey | None) – The JWK as a cryptography public key object. When not provided, it will be fetched and parsed automatically.

  • jwt_params (dict[str, Any] | None) – An optional dict of parameters to pass to the jwt decode step. If "leeway" is included, it will be passed as the leeway parameter, and all other values are passed as options.

Return type:

dict[str, Any]

class globus_sdk.OAuthAuthorizationCodeResponse(*args, **kwargs)[source]

Bases: OAuthTokenResponse

Class for responses from the OAuth2 ‘authorization_code’ grant.

This class of response is returned by methods which get new tokens via a code-exchange, as in 3-legged OAuth or PKCE.

For example, globus_sdk.ConfidentialAppAuthClient.oauth2_exchange_code_for_tokens() will return an OAuthAuthorizationCodeResponse.

class globus_sdk.OAuthRefreshTokenResponse(*args, **kwargs)[source]

Bases: OAuthTokenResponse

Class for responses from the OAuth2 ‘refresh_token’ grant.

This class of response is returned by methods which get new tokens from an existing Refresh Token, e.g., globus_sdk.NativeAppAuthClient.oauth2_refresh_token().

class globus_sdk.OAuthClientCredentialsResponse(*args, **kwargs)[source]

Bases: OAuthTokenResponse

Class for responses from the OAuth2 ‘client_credentials’ grant.

This class of response is returned by methods which get new tokens by means of client credentials, namely globus_sdk.ConfidentialAppAuthClient.oauth2_client_credentials_tokens().

class globus_sdk.OAuthDependentTokenResponse(*args, **kwargs)[source]

Bases: OAuthTokenResponse

Class for responses from the OAuth2 ‘urn:globus:auth:grant_type:dependent_token’ grant.

This is an extension grant type defined by Globus.

oauth2_get_dependent_tokens provides this response, and includes some documentation on its proper usage.

decode_id_token(openid_configuration=None, jwk=None, jwt_params=None)[source]

Parse the included ID Token (OIDC) as a dict and return it.

If you provide the jwk, you must also provide openid_configuration.

Parameters:

  • openid_configuration (None | GlobusHTTPResponse | dict[str, Any]) – The OIDC config as a GlobusHTTPResponse or dict. When not provided, it will be fetched automatically.

  • jwk (RSAPublicKey | None) – The JWK as a cryptography public key object. When not provided, it will be fetched and parsed automatically.

  • jwt_params (dict[str, Any] | None) – An optional dict of parameters to pass to the jwt decode step. If "leeway" is included, it will be passed as the leeway parameter, and all other values are passed as options.

Return type:

dict[str, Any]

class globus_sdk.GetConsentsResponse(response, client=None, *, iter_key=None)[source]

Bases: IterableResponse

Response class specific to the Get Consents API

Provides iteration on the “consents” array in the response.

to_forest()[source]

Creates a ConsentForest from the consents in this response.

ConsentForest is a convenience class to make interacting with the

tree of consents simpler.

Return type:

ConsentForest

class globus_sdk.GetIdentitiesResponse(response, client=None, *, iter_key=None)[source]

Bases: IterableResponse

Response class specific to the Get Identities API

Provides iteration on the “identities” array in the response.

Errors

exception globus_sdk.AuthAPIError(r, *args, **kwargs)[source]

Error class for the API components of Globus Auth.

OAuth2 Flow Managers

These objects represent in-progress OAuth2 authentication flows. Most typically, you should not use these objects directly, but rather rely on the NativeAppAuthClient or ConfidentialAppAuthClient objects to manage these for you through their oauth2_* methods.

All Flow Managers inherit from the GlobusOAuthFlowManager abstract class. They are a combination of a store for OAuth2 parameters specific to the authentication method you are using and methods which act upon those parameters.

class globus_sdk.services.auth.GlobusNativeAppFlowManager(auth_client, requested_scopes=None, redirect_uri=None, state='_default', verifier=None, refresh_tokens=False, prefill_named_grant=None)[source]

Bases: GlobusOAuthFlowManager

This is the OAuth flow designated for use by clients wishing to authenticate users in the absence of a Client Secret. Because these applications run “natively” in the user’s environment, they cannot protect a secret. Instead, a temporary secret is generated solely for this authentication attempt.

Parameters:

  • auth_client (globus_sdk.NativeAppAuthClient) – The client object on which this flow is based. It is used to extract default values for the flow, and also to make calls to the Auth service.

  • requested_scopes (ScopeCollectionType | None) – The scopes on the token(s) being requested. Defaults to openid profile email urn:globus:auth:scope:transfer.api.globus.org:all

  • redirect_uri (str | None) – The page that users should be directed to after authenticating at the authorize URL. Defaults to ‘https://auth.globus.org/v2/web/auth-code’, which displays the resulting auth_code for users to copy-paste back into your application (and thereby be passed back to the GlobusNativeAppFlowManager)

  • state (str) – The redirect_uri page will have this included in a query parameter, so you can use it to pass information to that page if you use a custom page. It defaults to the string ‘_default’

  • verifier (str | None) – A secret used for the Native App flow. It will by default be a freshly generated random string, known only to this GlobusNativeAppFlowManager instance

  • refresh_tokens (bool) – When True, request refresh tokens in addition to access tokens. [Default: False]

  • prefill_named_grant (str | None) – Prefill the named grant label on the consent page

exchange_code_for_tokens(auth_code)[source]

The second step of the Native App flow, exchange an authorization code for access tokens (and refresh tokens if specified).

Parameters:

auth_code (str) – The short-lived code to exchange for tokens

Return type:

OAuthAuthorizationCodeResponse

get_authorize_url(query_params=None)[source]

Start a Native App flow by getting the authorization URL to which users should be sent.

Parameters:

query_params (dict[str, Any] | None) – Additional query parameters to include in the authorize URL. Primarily for internal use

Return type:

str

The returned URL string is encoded to be suitable to display to users in a link or to copy into their browser. Users will be redirected either to your provided redirect_uri or to the default location, with the auth_code embedded in a query parameter.

class globus_sdk.services.auth.GlobusAuthorizationCodeFlowManager(auth_client, redirect_uri, requested_scopes=None, state='_default', refresh_tokens=False)[source]

Bases: GlobusOAuthFlowManager

This is the OAuth flow designated for use by Clients wishing to authenticate users in a web application backed by a server-side component (e.g. an API). The key constraint is that there is a server-side system that can keep a Client Secret without exposing it to the web client. For example, a Django application can rely on the webserver to own the secret, so long as it doesn’t embed it in any of the pages it generates.

The application sends the user to get a temporary credential (an auth_code) associated with its Client ID. It then exchanges that temporary credential for a token, protecting the exchange with its Client Secret (to prove that it really is the application that the user just authorized).

Parameters:

  • auth_client (globus_sdk.ConfidentialAppAuthClient) – The client used to extract default values for the flow, and also to make calls to the Auth service.

  • redirect_uri (str) – The page that users should be directed to after authenticating at the authorize URL.

  • requested_scopes (ScopeCollectionType | None) – The scopes on the token(s) being requested. Defaults to openid profile email urn:globus:auth:scope:transfer.api.globus.org:all

  • state (str) – This string allows an application to pass information back to itself in the course of the OAuth flow. Because the user will navigate away from the application to complete the flow, this parameter lets the app pass an arbitrary string from the starting page to the redirect_uri

  • refresh_tokens (bool) – When True, request refresh tokens in addition to access tokens. [Default: False]

exchange_code_for_tokens(auth_code)[source]

The second step of the Authorization Code flow, exchange an authorization code for access tokens (and refresh tokens if specified)

Parameters:

auth_code (str) – The short-lived code to exchange for tokens

Return type:

OAuthAuthorizationCodeResponse

get_authorize_url(query_params=None)[source]

Start a Authorization Code flow by getting the authorization URL to which users should be sent.

Parameters:

query_params (dict[str, Any] | None) – Additional parameters to include in the authorize URL. Primarily for internal use

Return type:

str

The returned URL string is encoded to be suitable to display to users in a link or to copy into their browser. Users will be redirected either to your provided redirect_uri or to the default location, with the auth_code embedded in a query parameter.

Abstract Flow Manager

class globus_sdk.services.auth.flow_managers.GlobusOAuthFlowManager[source]

Bases: ABC

An abstract class definition that defines the interface for the Flow Managers for Globus Auth. Flow Managers are really just bundles of parameters to Globus Auth’s OAuth2 mechanisms, along with some useful utility methods. Primarily they can be used as a simple way of tracking small amounts of state in your application as it leverages Globus Auth for authentication.

For sophisticated use cases, the provided Flow Managers will NOT be sufficient, but you should consider the provided objects a model.

This way of managing OAuth2 flows is inspired by oauth2client. However, because oauth2client has an uncertain future (as of 2016-08-31), and we would have to wrap it in order to provide a clean API surface anyway, we implement our own set of Flow objects.

abstract exchange_code_for_tokens(auth_code)[source]

This method takes an auth_code and produces a response object containing one or more tokens. Most typically, this is the second step of the flow, and consumes the auth_code that was sent to a redirect URI used in the authorize step.

The exchange process may be parameterized over attributes of the specific flow manager instance which is generating it.

Parameters:

auth_code (str) – The authorization code which was produced from the authorization flow

Return type:

OAuthAuthorizationCodeResponse

abstract get_authorize_url(query_params=None)[source]

This method consumes no arguments or keyword arguments, and produces a string URL for the Authorize Step of a 3-legged OAuth2 flow. Most typically, this is the first step of the flow, and the user may be redirected to the URL or provided with a link.

The authorize_url may be (usually is) parameterized over attributes of the specific flow manager instance which is generating it.

Parameters:

query_params (dict[str, Any] | None) – Any additional parameters to be passed through as query params on the URL.

Return type:

str