Globus Auth API Reference

Table of Contents

1. API Overview
2. Client Authentication
3. User Authorization and Authentication with OAuth2/OIDC
4. Identities API
5. Developer Resource API
6. Identity Providers API
7. References

The Globus Auth API has a set of common conventions that it uses throughout, as described in the following subsections.

1. API Overview

1.1. Base URL

All Globus Auth API interactions are TLS-secured with the host auth.globus.org. Therefore, URLs to Globus Auth resources begin with https://auth.globus.org/.

1.2. Versioning

All public Globus Auth resource URL paths are prefixed by /v2/. For example:

GET https://auth.globus.org/v2/api/identities/2982f207-04c0-11e5-ac60-22000b92c6ec

Globus Auth API clients can assume the syntax and semantics of the resources defined in this specification will not change in an incompatible manner. However, the resources may be extended, as long as such extensions are backward compatible. For example:

The Globus Auth API may be extended with additional resources.
Resource URLs may be extended to support additional query parameters.
JSON documents used by resource requests and responses may contain additional fields. Clients should ignore any fields they do not recognize.

Clients SHOULD NOT use Globus Auth resource URL paths that are prefixed by /p/, as these are private, internal resources that may change at any time without warning.

1.3. Request Authentication

Unless otherwise noted, all REST calls are authenticated using the HTTP Authorization header. Clients will need to include either a Bearer Token (i.e. access token) if the request is made on behalf of a user, or a Basic Auth header if the request is made on behalf of the client itself.

Globus Auth will return HTTP 401 Unauthorized for any call that is missing the relevant header information, or if the access token has expired or been revoked, unless it is specifically noted that the call requires no authentication or some other form of authentication. It is recommended that resource owner APIs do the same.

1.4. Access Control

Access policies for specific resources are covered in their respective sections.

Any GET, PUT, or POST request, unless otherwise noted, returns a HTTP 404 Not Found if the authenticated entity is not allowed to view it, so as to avoid leaking information about the (non-) existence of resources.

1.5. POST and PUT validation

Unless otherwise noted, all POST and PUT parameters not listed are ignored silently, including parameters that exist in the resource but which cannot be updated.

If any required parameter is omitted, a 400 Bad Request is returned detailing which parameter(s) is/are missing.

Syntactically invalid values (e.g., value foo when a UUID is expected) returns a 400 Bad Request response and an error body with "code": "INVALID_PARAMETERS".

1.6. Resource Envelopes

Resources returned by Globus Auth API endpoints, except for those governed by some existing specification (such as OAuth2 endpoints), are wrapped in an envelope. The envelope is a singular or plural form of the returned resource, for example:

{"client" : <client_resource> }

or:

{"clients" : [ <client1_resource>, <client2_resource> ] }

1.7. Including associated resources ("side-loading")

Some resource requests can have an "include" query parameter, followed by a list of fields that specify what associated resources should be included in the response. For example:

GET /v2/api/identities/2982f207-04c0-11e5-ac60-22000b92c6ec?include=identity_provider

will respond not just with requested identity resource document, but also the associated identity_provider resource document. Included resources are also wrapped in an included envelope. For example:

{
  "identity": <identity_resource>,
  "included": {
    "identity_provider": <identity_provider_resource>
  }
}

1.8. CORS

https://auth.globus.org supports CrossOrigin Resource Sharing (CORS) to allow any client to directly access the Globus Auth API.

2. Client Authentication

OAuth2 clients can authenticate against Globus Auth using a basic authorization header, where the client identifier and client secret are combined with a single colon (:) and base64-encoded.

For example, a client with id 7e24adb0-eee2-4ca4-99c6-586fefcb91db and secret abc123 would use the header:

Authorization: Basic N2UyNGFkYjAtZWVlMi00Y2E0LTk5YzYtNTg2ZmVmY2I5MWRiOmFiYzEyMw==

For additional details, see RFC 7617.

3. User Authorization and Authentication with OAuth2/OIDC

3.1. Overview

All applications follow a basic pattern when accessing Globus-enabled resources using OAuth 2.0.

At a high level, you’ll need to follow four steps:

Register your app to receive credentials.

Visit the Client Registration Page to obtain OAuth 2.0 credentials such as a client ID and client secret that are used to identify your application to Globus Auth.
Obtain one or more access tokens from Globus Auth

Before your application can access private data on a Globus-enabled resource server, it must obtain an access token that grants access to those resources. A single access token is valid for a particular resource server’s API, but it can grant varying degrees of access to APIs. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter. There are several ways to make this request, and they vary based on the type of application you are building. For example, a JavaScript application might request an access token using a browser redirect, while an application installed on a device that has no browser uses direct HTTP requests. Some requests require an authentication step where the user logs in to Globus Auth using one of their identities. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. If the user grants the permission, Globus Auth sends your application an access token (or an authorization code that your application can use to obtain an access token). If the user does not grant the permission, the server returns an error. It is generally a best practice to request the minimum scopes your application needs to properly function.
Send the access token to an API.

After an application obtains an access token, it sends the token to a resource server API in an HTTP authorization header. Access tokens are valid only for a particular resource server and the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the Globus Transfer API, it does not grant access to the XSEDE User Profile API. You can, however, send the same access token to a resource server multiple times for similar operations.
Refresh the access token, if necessary.

Access tokens have limited lifetimes. If your application needs access to a resource server beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens.

3.2. Obtaining authorization - Supported OAuth2 Grant Types

Globus Auth Supports the following OAuth2 grant types (detailed below):

Authorization Code Grant (Most secure, preferred)
Dependent Token Grant (Custom extension grant, used by resource servers)
Resource Owner Password Credentials Grant (Not generally supported)
Implicit Grant (Limited to specific, trusted apps)
Client Credentials Grant

These grants all share the same HTTP endpoints:

Authorization: https://auth.globus.org/v2/oauth2/authorize

Token: https://auth.globus.org/v2/oauth2/token

3.3. Authorization Code Grant (preferred)

Authorization Code Grant: For obtaining an access token, via browser redirection, for a web server-based client to access a resource server.

Preparing to start the OAuth 2.0 flow

You will need:

The client_id and client_secret from your client registration.
The scopes your client is requesting.

Redirecting the user to the OAuth 2.0 server

Construct a URL for the OAuth2 authorization endpoint https://auth.globus.org/v2/oauth2/authorize with the following query-string parameters:

Parameter	Values	Description
response_type	`code`	Determines whether Globus Auth returns an authorization code. For the authorization code grant, this value is always `code`
client_id	The client ID you obtained when registering your client.	Identifies the client that is making the request. The value passed in this parameter must exactly match the value issued for your client on registration.
redirect_uri	One of the redirect_uri values you registered for your client.	Determines where the response is sent. The value of this parameter must exactly match one of the values listed for this client in the registration system. (including the http or https scheme, case, and trailing '/').
scope	Space-separated set of permissions that the application requests.	Identifies the access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user and the number of access tokens returned.
state	Any string	Provides any state that might be useful to your application upon receipt of the response. Whatever value you send here will be returned to your application unmodified. To mitigate against cross-site request forgery (CSRF), it is strongly recommended to include an anti-forgery token in the state, and confirm it in the response. See here for further suggestions on how to use the state parameter.
access_type [OPTIONAL]	`online` (default) or `offline`	Indicates whether your application needs to access resources when the user is not present at the browser. If access_type is `offline`, your application will be issued a refresh token along with the access token the first time it exchanges an authorization code for a token.
prompt [OPTIONAL]	`login`	The user will be redirected to log in before the authorization step.
session_required_identities [OPTIONAL]	A comma-separated list of identity IDs from a single user’s set of linked identities	All the provided identities are required in session before proceeding to the authorization step. If they are not, the user will be redirected to log in before proceeding. Note that this cannot be used in combination with `session_required_single_domain`.
session_required_single_domain [OPTIONAL]	A comma-separated set of domains	An identity from one of the domains is required in the user’s session, otherwise the user is redirected to log in or link an identity from one of the domains. If `session_required_single_domain` is used in conjunction with `prompt=login`, the user will be required to log in regardless of whether there is an identity from one of the domains in session. Note that this cannot be used in combination with `session_required_identities`.
session_required_mfa [OPTIONAL]	A boolean flag	If set to `true` this will require that an MFA device is asserted when the user authorizes with their Identity Provider. Currently this can only be used in conjunction with one of `session_required_single_domain` or `session_required_identities`. Note: Not all identity providers pass information to Globus about whether an MFA device was used.
session_required_policies [OPTIONAL]	A comma-separated list of policy IDs	Each policy in the list is evaluated one at a time against the linked identities (standard policies) or the identities in the current session (high assurance policies). For each policy, if none of the identities satisfy it, then the user is asked to link an identity that will. This can result in the user being required to link more than one new identity when requiring multiple policies be satisfied. Note this cannot be used in combination with `session_required_single_domain`, `session_required_identities`, or `session_required_mfa`.

An example URL is shown below, with line breaks and spaces for readability.

https://auth.globus.org/v2/oauth2/authorize?
scope=urn:globus:auth:scope:auth.globus.org:view_identities+openid+email+profile&
state=security_token%3D138r5719ru3e1%26url%3Dhttps://oa2cb.example.com/myHome&
redirect_uri=https://oauth2-login-demo.example.com/callback&
response_type=code&
client_id=d430e6c8-b06f-4446-a060-2b6b2bc3e54a

After you create the request URL, redirect the user to it.

Handling the OAuth 2.0 server response

The OAuth 2.0 server responds to your application’s access request by redirecting the user’s browser to the redirect_uri specified in the request.

If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. All responses are returned to your application on the query string, as shown below:

An error response:

https://oauth2-login-demo.example.com/callback?error=access_denied

A successful authorization code response:

https://oauth2-login-demo.example.com/callback?code=P7q7W91a-oMsCeLvIaQm6bTrgtp7

Important

If your response endpoint renders an HTML page, any resources on that page will be able to see the authorization code in the URL. Scripts can read the URL directly, and all resources may be sent the URL in the Referer HTTP header. Carefully consider if you want to send authorization credentials to all resources on that page (especially third-party scripts such as social plugins and analytics). To avoid this issue, we recommend that the server first handle the request, then redirect to another URL that doesn’t include the response parameters.

After the web server receives the authorization code, it can exchange the authorization code for one or more access tokens.

To exchange an authorization code for an access token, POST to the https://auth.globus.org/v2/oauth2/token endpoint, with an Authorization header containing an HTTP Basic Auth header for your client_id and client_secret, and including the following fields with parameters sent as "application/x-www-form-urlencoded".

Field	Description
code	The authorization code returned from the previous authorization request.
redirect_uri	The same value you sent in the previous authorization request.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of `authorization_code`.

The actual request might look like the following:

POST /v2/oauth2/token
Host: auth.globus.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NDFjYTIwM2QtNzcwMy00NDYxLWFiNGItNjVhNjA0YjE2NjE5OjxDTElFTlRfU0VDUkVUPg==

code=P7q7W91a-oMsCeLvIaQm6bTrgtp7&
redirect_uri=https://oauth2-login-demo.example.com/callback&
grant_type=authorization_code

A successful response to this request contains the following fields:

Field	Description
access_token	The token that can be used to access resources.
scope	Space-separated list of scopes the access token authorizes.
resource_server	The resource server for which the access_token token is intended.
expires_in	The remaining lifetime of the access token.
token_type	Identifies the type of token returned. At this time, this field will always have the value bearer.
refresh_token	A token that may be used to obtain a new access token. Refresh tokens are valid until the user revokes access. This field is only present if the authorization request asked for offline access.
id_token	A JWT containing details about the user as defined in the OpenIDConnect specification. Note: Only included if your client requests the `openid` scope during the authorization request.
state	The state parameter your client application provided during the authorization request.
other_tokens	If the client requested scopes that span multiple resource servers, this field will be present, and it will contain an array of access token responses containing separate tokens for each resource server.

Note

If the client has requested any scopes against the Auth resource server (auth.globus.org) itself (e.g. openid, email, profile or urn:globus:auth:scope:auth.globus.org:view_identities) then the access token returned in the top level of the response object will be valid for use with Auth. Tokens for other resource servers will be found under other_tokens.

A successful response is returned as a JSON object, similar to the following:

{
  "access_token": "E3SfxOvlvsQ49lTn6cA0RGfRXHcwy85q...",
  "expires_in": 3600,
  "refresh_token": "IlLACxpsG53v2zIuGCNPkoJXSF8gHbu8",
  "id_token": "eyJ0eXAiOiJKV1QiLA0KICJh...",
  "resource_server": "auth.globus.org",
  "scope": "urn:globus:auth:scope:auth.globus.org:view_identities",
  "state": "provided_by_client_to_prevent_replay_attacks",
  "token_type": "bearer",
  "other_tokens": [
    {
      "access_token": "OCsTf8AMydkPXTsv4stzT2QK5MA_S3a3...",
      "expires_in": 3600,
      "refresh_token": "TgwS5_BEFLsZbED42-agjfcriH0-pIee",
      "resource_server": "groups.api.globus.org",
      "scope": "urn:globus:auth:scope:nexus.api.globus.org:groups",
      "token_type": "bearer"
    },
    {
      "access_token": "oreTykUqQZfXXMqa5Zr9GoHaJsyF1AGX...",
      "expires_in": 3600,
      "refresh_token": "H-qpG4yMQqkfGLhwjHYy_73TY2PSSAVh",
      "resource_server": "atmosphere.jetstream.xsede.org",
      "scope": "urn:globus:auth:scope:atmosphere.jetstream.xsede.org:manage_data",
      "token_type": "bearer"
    },
    {
      "access_token": "tggaKq69-qJiDRHp5oPW_lllll5syWfZ...",
      "expires_in": 3600,
      "refresh_token": "auqmwrC5qb841p9QsxqwbPgABuiDqUUJ",
      "resource_server": "transfer.api.globus.org",
      "scope": "urn:globus:auth:scope:transfer.api.globus.org:monitor_ongoing",
      "token_type": "bearer"
    }
  ]
}

3.3.1. Refresh Token Grant

Refreshing an Access Token: If your application requires access beyond the lifetime of a single access token, it can request offline access, and then use a refresh token to obtain fresh access tokens. Refresh tokens will remain valid indefinitely if they are being used, but they expire after six months of inactivity. They can also be explicitly revoked by a user.

POST request to https://auth.globus.org/v2/oauth2/token, with an HTTP Basic Authorization header containing your client_id and client_secret. The request must include the following parameters sent as "application/x-www-form-urlencoded":

Field	Description
refresh_token	The refresh token returned from the authorization code exchange.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token.

Such a request will look similar to the following:

POST /v2/oauth2/token
Host: auth.globus.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NDFjYTIwM2QtNzcwMy00NDYxLWFiNGItNjVhNjA0YjE2NjE5OjxDTElFTlRfU0VDUkVUPg==

refresh_token=6BMfW9j53gdGImsiyUH5kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

As long as the refresh_token has not expired or been revoked the response includes a new access token. A response from such a request is shown below:

{
  "access_token": "fFBGRNJru1FQd44AzqT3Zg...",
  "refresh_token": "6BMfW9j53gdGImsiyUH5kU5RsR4zwI9lUVX-tqf8JX",
  "expires_in": 3920,
  "token_type": "Bearer"
}

3.4. Implicit Grant

Implicit Grant: For obtaining an access token, via browser redirection, for a Javascript client running in a browser.

Similar to the Authorization Code grant, except a token is returned directly to the browser.

This flow is not recommended, because it is less secure than the Authorization Code grant.

3.5. Resource Owner Password Credentials Grant

The Resource Owner Password Credentials Grant is only supported for a small number of specific use-cases, and is not generally available. It must be explicitly enabled by Globus both for a particular client and identity provider.

Non-browser based apps (such as command line, mobile, or desktop apps) are recommended to use native apps as described in the developer guide.

3.6. Client Credentials Grant

In some situations, you may want your Globus App to be able to take actions "as itself", rather than on behalf of a user. For example, a data portal application might have resources that are owned by the portal, rather than belonging to a human user.

To accommodate this use case, Globus Auth supports what we call "client-identities". Unlike a human identity that might have a username in the form, jane.doe@uchicago.edu, client-identities have a username of the form <client_id>@clients.auth.globus.org, where <client_id> is the UUID your Globus App was issued at registration time. This identity can be used in permissions or for interactions with other services.

In order to take actions as the client-identity, you will need to use the OAuth2 client_credentials grant to retrieve an access_token (or multiple access tokens) valid for that identity.

Note

Only confidential clients that have been issued a client_secret may use the client_credentials grant.

POST to the https://auth.globus.org/v2/oauth2/token endpoint, with an Authorization header containing an HTTP Basic Auth header for your client_id and client_secret, and including the following fields encoded as "application/x-www-form-urlencoded":

Field	Description
scope	Plus-separated or space-separated list of scopes your client is requesting.
grant_type	As defined in the OAuth 2.0 specification, this field must contain a value of `client_credentials`.

The actual request might look like the following:

POST /v2/oauth2/token
Host: auth.globus.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NDFjYTIwM2QtNzcwMy00NDYxLWFiNGItNjVhNjA0YjE2NjE5OjxDTElFTlRfU0VDUkVUPg==

scope=openid+email+profile+urn:globus:auth:scope:transfer.api.globus.org:all&
grant_type=client_credentials

A successful response to this request contains the following fields:

Field	Description
access_token	The token that can be used to access resources.
scope	Space-separated list of scopes the access token authorizes.
resource_server	The resource server for which the access_token token is intended.
expires_in	The remaining lifetime of the access token.
token_type	Identifies the type of token returned. At this time, this field will always have the value bearer.
other_tokens	If the client requested scopes that span multiple resource servers, this field will be present, and it will contain an array of access token responses containing separate tokens for each resource server.

Note

3.7. Verifying identity (via OpenID Connect ID Token)

Globus Auth’s OAuth2 grants accept the following OpenID Connect scopes:

openid: Requests that an OpenID Connect id_token be returned as part of the OAuth2 Access Token Response, with the following claims:
- sub: The Globus Auth identity id of the effective identity of the logged in Globus account. This effective may be the primary identity, or the appropriate linked identity if this client requires an identity from a particular provider.
- iss: The URL "https://auth.globus.org"
- at_hash: Per OpenID Connect specification.
- aud: Per OpenID Connect specification.
- exp: Per OpenID Connect specification.
- iat: Per OpenID Connect specification.
- nonce: Per OpenID Connect specification.
- last_authentication: The last time that this identity authenticated, returned as a Unix/epoch timestamp.
- identity_set: The identities linked to this account.
email: Adds the following claim in the id_token:
- email: The email address associated with the identity provided in the "sub" claim.
profile: Adds the following claim in the id_token:
- name: The identity’s full name (e.g. Jane Doe) in displayable form.
- organization: The identity’s organization.
- preferred_username: The identity username for the effective identity ID provided by the 'sub' claim.
- identity_provider: The ID of the identity provider for this identity.
- identity_provider_display_name: The name of the identity provider for this identity.

These claims are being made by Globus Auth (iss), on behalf of an identity provider, about an identity (sub, name, email) that has been provisioned by the identity provider with Globus Auth, and authenticated by the identity provider via Globus Auth.

In order to verify the signature of the id_token, you can use the our public keys at https://auth.globus.org/jwk.json

3.8. OIDC Userinfo Endpoint

This endpoint can be used instead of an ID token to get information about a user. However, using an id_token is the generally recommended method because it doesn’t require an additional HTTP round trip.

GET or POST to /v2/oauth2/userinfo

Field	Type	Required Scope(s)	Description
sub	UUID	openid	Globus Auth issued identity id, guaranteed to uniquely identify a single identity.
last_authentication	Integer	openid	The last time that this identity authenticated, returned as a Unix/epoch timestamp.
identity_set	Object	openid	The full identity set for this account. The identity set items contain the same structure as the primary ID.
email	String	openid and email	The email address associated with the identity, if known.
name	String	openid and profile	The user’s name (e.g. Jane Doe).
organization	String	openid and profile	The identity’s organization.
preferred_username	String	openid and profile	The identity username for the effective identity ID provided by the 'sub' claim. NOTE: This field is renamed to `username` in the identity set.
identity_provider	String	openid and profile	The ID of the identity provider for this identity.
identity_provider_display_name	String	openid and profile	The name of the identity provider for this identity.

As described in Section 5.3 of the OpenID Connect specification, this resource returns 'claims' about a user’s identity. These are the same claims that are returned in the JWT id_token alongside the access token. In order to access this resource, your request MUST be authenticated with an access token in the HTTP Authorization header, and valid for at least the openid scope. Additional claims will be returned if the bearer token is valid for the profile and email scopes.

Example request:

GET /v2/oauth2/userinfo
Host: auth.globus.org
Authorization: Bearer A7oU1xJ8-ddvRiMf-ZFDvXb

Example response:

{
  "email": "ztaylor@example.com",
  "name": "Zachary Taylor",
  "preferred_username": "ztaylor@globusid.org",
  "identity_provider_display_name": "Globus ID",
  "identity_provider": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
  "organization": "Organization",
  "last_authentication": 1585947107,
  "sub": "e9a5903a-cb98-11e5-a7fa-afe061bd0f40",
  "identity_set": [
    "..."
  ]
}

3.9. Token Introspection (POST /v2/oauth2/token/introspect)

Token introspection is meant to be used by resource servers when they first receive an access token, to verify the validity of the token and find out information about the user the token represents. It should not be used by any other clients.

This resource conforms to the RFC 7662, OAuth 2.0 Token Introspection.

When a resource server receives a request from a client, it must validate the access token included in the request (<request access token>), and learn more information about the authorization granted by this request access token. The resource server does so by performing an HTTP POST on /v2/oauth2/token/introspect, with parameters sent as "application/x-www-form-urlencoded" data as defined in W3C recommendations.

Construct a URL for the OAuth2 introspect endpoint with the following query-string parameters:

Parameter	Description
authentication_policies	Comma-separated list of policy IDs. Each policy in the list is evaluated one at a time against the linked identities (standard policies) or the identities in the current session (high assurance policies).

The request parameters are:

Parameter Description

Parameter	Description
token	The request access token on which this request is performing introspection.
include	Comma-separated list of optional fields be included in the response. Currently supported values are: - `session_info`: The response will include information about which identities have authenticated in the current Session and when the authentication occurred - `identity_set`: The response will include a summary list of all identities IDs (primary and linked) that are associated with this Globus Auth account - `identity_set_detail`: The response will include a detailed list of all identities (primary and linked) that are associated with this Globus Auth account - `identities_set`: The same result as `identity_set`, this flag has been deprecated in favor of `identity_set`

token

The request access token on which this request is performing introspection.

include

Comma-separated list of optional fields be included in the response. Currently supported values are:

- session_info: The response will include information about which identities have authenticated in the current Session and when the authentication occurred

- identity_set: The response will include a summary list of all identities IDs (primary and linked) that are associated with this Globus Auth account

- identity_set_detail: The response will include a detailed list of all identities (primary and linked) that are associated with this Globus Auth account

- identities_set: The same result as identity_set, this flag has been deprecated in favor of identity_set

This request’s Authorization header must contain the resource server’s client identifier (client_id) and client secret (client_secret) in a base64-encoded "Basic Authorization" scheme.

The response to this POST is an RFC7662 compliant JSON document. Invalid (revoked or expired) tokens return only {"active": false}, while valid tokens return all fields not marked as OPTIONAL below.

Field	Type	Description
active	Bool	False if the token has expired or been revoked, true otherwise. If the token is invalid this is the only field that is returned.
token_type	String	Identifies the type of token returned. At this time, this field will always have the value `"Bearer"`.
dependent_tokens_cache_id	String	Resource Servers should store refresh tokens obtained from dependent token grants using dependent_token_cache_id as a key. When introspecting an access token received from a client, it should check if it already has a refresh token stored, and if so use that token instead of performing a new dependent token grant.
scope	Space-separated list of Strings	List of scopes to which this access token authorizes access. A resource server receiving a token MUST validate that the listed scope(s) allows access to the resource being requested.
sub	UUID	An effective identity id belonging to the account associated with this access token. This effective identity is either the primary identity of the account, or if the client requires an identity issued by a particular identity provider, then it may be the appropriate linked identity from the account.
username	String	The identity username for the effective identity id provided by the sub field.
name	String/null	The display name for the effective identity of this token, typically a full name. May be null, if the user has restricted their identity visibility.
email*	String/null	The email address associated with the effective identity of this token. May be null, if the user has restricted their identity visibility.
client_id	UUID	The Globus Auth issued client id of the client to which this token was issued.
aud	List of strings	Identifier of the audiences for whom this token is intended. This will include both the `client_id` of the client to which this token was issued, and the name of the resource server it was issued for. In order to avoid a 'confused deputy' attack, clients and resource servers SHOULD validate that they are among the intended audience for a token.
iss	String	String representing the issuer of this token, which will always be `https://auth.globus.org`. Note: During the transition from Globus Nexus to Globus Auth, legacy tokens will have iss set to `https://nexus.api.globusonline.org`.
exp	Timestamp	Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire.
iat	Timestamp	Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued.
nbf	Timestamp	Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token is not to be used before.
session_info* [OPTIONAL]	Object	Contains information about the Session the token derives from. For more information please see the Sessions Guide.
identity_set or identities_set* [OPTIONAL]	List of UUIDs	A summary list of all identity IDs (primary and linked) that are associated with this Globus Auth account, which are visible to this resource server. For performance reasons, this field is only included when the client requests it with the parameter `include=identity_set` or `include=identities_set` (deprecated) in the POST body.
identity_set_detail* [OPTIONAL]	List of Objects	A detailed list of all identities (primary and linked) that are associated with this Globus Auth account, which are visible to this resource server. The response structure is the same as the Userinfo Endpoint. For performance reasons, this field is only included when the client requests it with the parameter `include=identity_set_detail` in the POST body.
policy_evaluations* [OPTIONAL]	Object	Containing information about the policy evaluations when the client requests it with the query parameter `authentication_polcies=policy_id list`.

Warning

Some identity providers reuse identity usernames, so over time an identity username may map to different identity ids. Clients must use the identity id as the persistent identifier of an identity.

* = Not part of RFC7662, Globus Auth-specific extension fields.

If the <request access token> does not exist, or was issued by Globus Auth for use with a different resource server, then the HTTP response will be 401 Unauthorized.

Example request:

POST /v2/oauth2/token/introspect?authentication_policies="d8da7e6c-11c6-476f-bafd-5120d8cd91bc,f03ac240-03ff-4661-8625-dec2a08ac9ff"
Host: auth.globus.org
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MmZkYTQxNDktODJmZi00OTM3LT

token=A7oU1xJ8-ddvRiMf-ZFDvXb&include=session_info,identity_set,identity_set_detail

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "active": true,
    "scope": "urn:globus:auth:scope:service.example.com:all",
    "client_id": "d430e6c8-b06f-4446-a060-2b6b2bc3e54a",
    "sub": "2982f207-04c0-11e5-ac60-22000b92c6ec",
    "username": "user1@example.com",
    "aud": [
        "service.example.com",
        "d430e6c8-b06f-4446-a060-2b6b2bc3e54a"
    ],
    "iss": "https://auth.globus.org/",
    "exp": 1419356238,
    "iat": 1419350238,
    "nbf": 1419350238,
    "name": "Joe User",
    "email": "user1@example.dom",
    "identity_set": [
        "2982f207-04c0-11e5-ac60-22000b92c6ec",
        "3982f207-04c0-11e5-ac60-22000b92c6ed"
    ],
    "session_info": {
        "session_id": "bf133a70-5e59-404a-b3ab-83728e030372",
        "authentications": {
            "2982f207-04c0-11e5-ac60-22000b92c6ec": {
                "auth_time": 1535238478,
                "idp": "5243639b-accc-44eb-9017-f9246ebccae4",
                "acr": "https://refeds.org/profile/mfa",
                "amr": ["mfa"]
            }
        }
    },
    "identity_set_detail": [
        {
            "name": "Joe User",
            "username": "user1@example.dom",
            "identity_provider_display_name": "Example IdP",
            "identity_provider": "53461402-42ac-4391-b335-70e2eb9e4302",
            "last_authentication": 1585947107,
            "sub": "2982f207-04c0-11e5-ac60-22000b92c6ec",
            "email": "user1@example.com",
            "organization": "Example Organization"
        },
        {
            "name": "Joe User",
            "username": "user1@anotherexample.dom",
            "identity_provider_display_name": "Another Example IdP"
            "identity_provider": "7daddf46-70c5-45ee-9f0f-7244fe7c8707",
            "last_authentication": 1585674851,
            "sub": "3982f207-04c0-11e5-ac60-22000b92c6ed",
            "email": "user1@example.com",
        }
    ]
    "policy_evaluations": {
        "d8da7e6c-11c6-476f-bafd-5120d8cd91bc": {
            "evaluation": true,
            "compliant_identities": [
              "2982f207-04c0-11e5-ac60-22000b92c6ec"
            ],
            "latest_time_compliant": 1535238478,
        },
        "f03ac240-03ff-4661-8625-dec2a08ac9ff": {
            "evaluation": false,
            "compliant_identities": [],
            "latest_time_compliant": None
        }
    }
}

Note

Globus Auth uses POST rather than GET in accordance with RFC7662 because of security concerns with passing an access token as part of a URL. An access token is a bearer token, so great care must be taken to ensure its confidentiality. However, web servers, proxies, and clients routinely log URLs. If URLs contain access tokens, and the logs are not properly sanitized or kept sufficiently confidential, they become a potential target for an attacker. By using a POST with the <request access token> included in the request body, the access token is not included in the URL.

3.10. Dependent Token Grant (POST /v2/oauth2/token)

The Dependent Token grant type is used by services which in turn need to call other services on behalf of a user.

3.10.1. Example

The Globus Transfer service needs to check group memberships in order to make access decisions. To accomplish this the Transfer scope has a dependency on the urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships scope of the Globus Groups service.

When an app, via an authorization request, asks the user for access to their Transfer resources via the urn:globus:auth:scope:transfer.api.globus.org:all scope the user is also asked to consent to the Transfer service accessing the Groups service on their behalf.

When the app subsequently calls Transfer using the access token it obtained (<request access token> below), and after validating it via token introspection, Transfer turns around and does a dependent token grant request to Globus Auth as described below. Globus Auth issues and returns a new dependent access token, which the Transfer service then uses to call the Groups service to determine the group memberships of the user.

3.10.2. Setup

Dependent scopes are configured via the Clients and Scopes API.

The scopes for which tokens are ultimately issued depends entirely on what the user has consented to, not on the registered dependencies. Registering a dependency only means that the user will be prompted for consent on the next authorization request.

Similarly, removing a scope dependency does not revoke the consent, and unless the service limits itself by using the scope parameter as described below the service will continue to receive tokens for those scopes until the user revokes the consent.

For these reasons service SHOULD use the scope parameter to manage change, both when adding and removing dependencies.

3.10.3. Grant Request

The Dependent Token Grant is an OAuth2 Extension Grant. Similar to the common authorization code grant, tokens are obtained by performing an HTTP POST to /v2/oauth2/token, with parameters sent as "application/x-www-form-urlencoded" data as defined in W3C recommendations.

Request parameters:

Parameter	Value	Description
grant_type	`urn:globus:auth:grant_type:dependent_token`	Custom OAuth2 extension grant type
token	`<request access token>`	The access token issued for the resource server.
access_type [OPTIONAL]	`online` or `offline` (default: `online`)	If `offline`, include any refresh tokens to which the resource server is entitled. Whether or not refresh tokens are included depends on whether the scope policies allow it.
scope [RECOMMENDED BUT NOT REQUIRED]	Plus-separated or space-separated list of scope strings.	List of scopes the service expects to receive tokens for. If a scope is listed which the user has not consented to, an error with code `DEPENDENT_CONSENT_REQUIRED` will be returned, and the service can float the error to the calling app so that it can obtain the required consent.

This request’s Authorization header must contain resource server’s client identifier (client_id) and client secret (client_secret) in a base64-encoded "Basic Authorization" scheme.

Example request:

POST /v2/oauth2/token
Host: auth.globus.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <Resource Server's Client Credentials>

grant_type=urn:globus:auth:grant_type:dependent_token&token=A7oU1xJ8-ddvRiMf-ZFDvXb&scope=urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships

3.10.4. Grant Response

The response will be a JSON document containing an array of standard access_token response document. Similar to the authorization code grant, the response will contain one token document per service access was requested for, although each token can contain multiple scopes.

For example, if the above request was made by the transfer.api.globus.org resource server upon receipt of a request using its urn:globus:auth:scope:service.example.com:all scope, and that scope is configured to require dependent scopes of urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships and urn:globus:auth:scope:auth.globus.org:view_identities scopes, which the user has consented to, then an example response would be:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "access_token": "r5qwkEz0lWJdpdknlDBmndC2G7wpTSOk...",
    "resource_server": "auth.globus.org",
    "scope": "urn:globus:auth:scope:auth.globus.org:view_identities",
    "expires_in": 3600,
    "refresh_token": "kUKDtLe_xDA4Qxd-ZI-rcFqrBlJj7zXx",
    "token_type": "bearer"
  },
  {
    "access_token": "7ZdPhhvija1MUDw6koBYgAAGnbrU79qF...",
    "resource_server": "groups.api.globus.org",
    "scope": "urn:globus:auth:scope:groups.api.globus.org:view_my_groups_and_memberships",
    "expires_in": 3600,
    "refresh_token": "dPVJBKAUs0x8UW4zhgQWv6snDmo2X72E",
    "token_type": "bearer"
  }
]

3.11. Token Revocation (POST /v2/oauth2/token/revoke)

Token revocation is meant to be used to revoke either access or refresh tokens. Revoking an access token should be used when an end-user logs out or when the token should no longer be used. Similarly refresh token should be revoked when the refresh token will no longer be used to issue access tokens.

This resource conforms to the RFC 7009, OAuth 2.0 Token Revocation.

Requests to revoke a token should always result in a status code 200 regardless of whether a valid token was specified.

Request parameters are:

Parameter	Description
token	The access or request token on which should be revoked.

Note: we do not support the use of the optional parameter token_type_hint specified in RFC 7009

This request’s Authorization header must contain resource server’s client identifier (client_id) and client secret (client_secret) in a base64-encoded "Basic Authorization" scheme.

The response to a successful POST is always {"active": false} but verifying the status code 200 is sufficient.

4. Identities API

4.1. Identity Resource

Resource envelope: identity / identities

Field	Type	Description
id	UUID	Globus Auth issued identity id, guaranteed to uniquely identify a single identity, even if the identity username associated with the identity is changed or reused by the identity provider. An id will never be reused. This field is visible to all clients.
username	String	The username of the identity. The identity username is guaranteed to be unique amongst all Globus Auth identities at any given time. However, since identity providers can change or reuse usernames the following caveats apply: * The identity username associated with a given identity id is NOT guaranteed to remain constant over time. * A single identity username MAY be associated with different identity ids over time The identity username is defined by the issuing identity provider. It may or may not also be a valid email address. This field is visible to all clients.
status	String enum	One of: - "unused", indicating that no user has proven ownership of this identity by authenticating with it. Resource servers may assign permissions to an unused identity. (See GET /v2/api/identities/<name>.) - "used", indicating that a user has proven ownership of this identity. The identity will typically, but not necessarily, be associated with a Globus Account. - "private", indicating that the user has restricted visibility of their identity. - "closed", indicating that this identity is no longer valid, typically because the provider has revoked it and perhaps reused the identity username. When an identity is closed, it will be removed from all Globus accounts, and end-users can no longer authenticate with this identity. Resource servers MAY remove any permissions associated with a closed identity, though since it is removed from all Globus accounts it will never be included in a token’s identities list, so will never result in matching a permission.
email	String	Identity provider specified email address for this identity. This email address may be used by Globus Auth, clients and resource servers for email notifications related to this identity. Globus Auth provides no guarantees about the email address, including whether the email address has been verified, or if emails sent to this address will be successfully delivered.
name	String	Identity provider specified display name (e.g., user’s full name) for this identity.
organization	String	The name of the organization this identity is associated with. This may be set by the provider or, if the provider does not set it, by the user themselves.

4.2. Get Identity

GET /v2/api/identities/<id>

Responds with an Identity Resource document for the identity with the specified <id>.

The response may not include all fields, depending on the identity’s visibility policy. However, the identity id, category, and name fields are always visible to all clients.

4.3. Get Identities

GET /v2/api/identities

Returns a list of Identity Resource documents for the requested usernames or identity IDs. If a requested identity does not exist, it will not be present in the list.

An identity document may not include all fields, depending on the identity’s visibility policy.

Table 1. Query Parameters
Parameter	Description
`ids`	A comma-delimited list of identity IDs.
`usernames`	A comma-delimited list of identity usernames.
`provision`	`true` or `false`. When set to `true`, Globus Auth will automatically create an identity ID for any username that does not already have a value. Defaults to `true`.

Exactly one of ids or usernames must be used.

For example,

GET /v2/api/identities?ids=<list-of-identity-ids>

GET /v2/api/identities?usernames=<list-of-identity-names>

Warning

An identity username must not be used as the unique identifier for an identity, because an identity provider may reuse an identity username over time. Clients must always use an identity id as the unique identifier when persisting an identity in its own records (e.g., in an access control policy).

If a field in an identity resource is not visible to the client (e.g., due to that identity’s visibility policy), that field will have a value of null.

Example request:

GET /v2/api/identities?usernames=webapptester1@globusid.org,webapptester2@globusid.org&include=identity_provider
Accept: application/json
Host: auth.globus.org
Authorization: Bearer A7oU1xJ8-ddvRiMf-ZFDvXb

Example response:

{
  "included": {
    "identity_providers": [
      {
        "id": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
        "name": "Globus ID"
      }
    ]
  },
  "identities": [
    {
      "username": "webapptester1@globusid.org",
      "status": "used",
      "name": "Jane Tester",
      "id": "e9873f94-032a-11e6-afde-cb613ccc97a9",
      "identity_provider": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
      "organization": "Globus",
      "email": "webapptester1@example.com"
    },
    {
      "username": "webapptester2@globusid.org",
      "status": "private",
      "name": null,
      "id": "e987941c-032a-11e6-afdf-7b65304db5f1",
      "identity_provider": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
      "organization": null,
      "email": null
    }
  ]
}

5. Developer Resource API

These APIs provide ways for programmatic access of resources available at the Globus developers page including projects, scopes, policies, and clients.

Projects are buckets that can provide shared control of various developer resources. By setting admins on projects, a user can share access to clients, scopes, and policies.

A client is any app or resource server using Globus Auth. It can perform OAuth authorization flows to receive user tokens to access protected resources, and register scopes of its own to allow users to delegate access to other clients.

Scopes are the unit-of-permission issued by Globus Auth; each valid access token grants one or more scope, each of which belongs to the same client.

5.1. Parent and Child Clients

When a client creates a new client (i.e., the call is authenticated with client credentials), the created client becomes a child of the client that created it. Child clients can authenticate using the credentials of the parent client. However, the parent cannot authenticate using credentials created specifically for the child client.

This behavior is used by GCS to allow each Collection to be separate client without forcing admins to juggle multiple sets of client credentials. Creating child clients is not necessary, or advised, for most use-cases.

5.2. Access Control

All API calls for developer resources can be authenticated using access tokens that have the urn:globus:auth:scope:auth.globus.org:manage_projects scope. Operations on a project or on resources associated with a project must be made by an admin of the project. Clients, additionally, can update themselves with client credentials. Additionally, to edit a project, client, scope, or policy, the identity of the admin must be authenticated in the session within the last 30 minutes.

A client can be viewed by any other client if its visibility is public. If visibility is private, it can only be viewed by itself or by its parent client.

Scope visibility is based on the visibility of the client it belongs to, except for scopes for which advertised is true which are viewable to anyone regardless of the client visibility.

5.3. Projects Resource

Resource envelope: project / projects

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`project_name`	String	The name of the project. (Deprecated alias for `display_name`)
`display_name`	String	The name of the project.
`contact_email`	String	An email address at which to contact the admins or owners about the project.
`admins`	List of objects	This is a list of identities that are administrators of the project.

5.3.1. Example

{
  "project": {
    "project_name": "My Globus Project",
    "display_name": "My Globus Project",
    "id": "6f29b1bc-58b7-4770-acff-948ac6ebc7c4",
    "contact_email": "main-contact@example.edu",
    "admins": {
      "identities": [
        {
          "username": "another-admin@globusid.org",
          "status": "used",
          "name": "Jane Administrator",
          "id": "035cffa7-9078-4e55-87f8-dda5b8f44821",
          "identity_provider": "d0f1e297-5c7c-4677-88ac-4d7cc8cedf09",
          "organization": "Example University",
          "email": "another-admin@example.edu"
        }
      ]
    }
  }
}

5.4. Client Resource

Resource envelope: client / clients.

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`parent_client`	UUID	The `id` of the client’s parent, or `null` if the client has no parent.
`name`	String	The display name shown to users on consents. May not contain linebreaks.
`public_client`	Boolean	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.
`grant_types`	List of strings	List of OAuth grant types the client can use. This has the possible values of `["authorization_code", "client_credentials", "refresh_token", "urn:globus:auth:grant_type:dependent_token"]`. If `public_client` is `true` the listed grants will usually only include `["authorization_code", "refresh_token"]`.
`visibility`	String	`private` means that only entities in the same project as the client can view it. `public` means that any authenticated entity can view it.
`scopes`	List of UUIDs	A list of scopes IDs belonging to this client.
`fqdns`	List of strings	A list of all FQDNs the client has proven possession of.
`redirect_uris`	List of string	A list of URIs that may be used in OAuth authorization flows. The redirect URI must use the HTTPS protocol and it may contain a port number. For development and testing purposes, HTTP URIs may be used if the hostname is a loopback address (e.g., `localhost` or `127.0.0.1`). For example, `http://localhost:5000/login` is allowed.
`links`	Object	URLs for the `terms_and_conditions` and `privacy_policy` of this client.
`required_idp`	UUID or `null`	ID representing an Identity Provider. In order to use this client a user must have an identity from this IdP in their identity set.
`preselect_idp`	UUID or `null`	ID representing an Identity Provider. This pre-selects the given IdP on the Globus Auth login page if the user is not already authenticated.
`project`	UUID or `null`	ID representing the project this client belongs to.

The links object should look like {"terms_of_service": <url>, "privacy_policy": <url>}. These URLs will be displayed to users on the consent screen. If left blank, the user will see a message that the client has not provided Terms of Service and/or a Privacy Policy.

5.4.1. Example

{
  "client": {
    "id": "cf01eb30-9884-11e5-8d77-87f1f8b059db",
    "name": "Globus Transfer",
    "public_client": false,
    "grant_types": [
      "authorization_code",
      "client_credentials",
      "refresh_token",
      "urn:globus:auth:grant_type:dependent_token"
    ],
    "visibility": "private",
    "scopes": [
      "be0a590d-0990-4a11-9876-38ff99dde445"
    ],
    "fqdns": [],
    "redirect_uris": [],
    "links": {
      "privacy_policy": "https://www.globus.org/legal/privacy",
      "terms_and_conditions": "https://www.globus.org/legal/terms"
    },
    "required_idp": null,
    "preselect_idp": "0dcf5063-bffd-40f7-b403-24f97e32fa47",
    "project": null
  }
}

5.5. Scope Resource

Resource envelope: scope / scopes.

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`client`	UUID	The ID of the client owning the scope.
`scope_string`	String	The string used in authorization requests, token responses, etc. Has the format `https://auth.globus.org/scopes/{midfix}/{suffix}`, where `{midfix}` is either the ID of the client owning the scope or a FQDN owned by the client, and `{suffix}` is the `scope_suffix` used to create the scope.
`name`	String	A display name used to display consents to users, along with `description`.
`description`	String	A description used to display consents to users, along with `name`.
`dependent_scopes`	List	A list of static scope dependencies.
`advertised`	Boolean	Whether or not the scope should show up in searches.
`allows_refresh_token`	Boolean	Whether or not the scope allows refresh tokens to be issued.

5.5.1. Scope Dependencies

If scope A has a dependency on scope B, that means that when an app requests access to scope A the user will also be prompted to give the client that owns scope A access to scope B.

As an example, when you request access to Globus Transfer, the user will also be prompted to give Transfer access to Globus Groups.

Each static dependency has the following fields:

Field	Type	Description
`scope`	UUID	The ID of the dependent scope
`optional`	Boolean	Whether or not the user can decline this specific scope without declining the whole consent.
`requires_refresh_token`	Boolean	Whether or not the dependency requires a refresh token.

5.5.2. Example

{
  "scope": {
    "id": "bc17272d-7c40-4c42-8828-ff3f20d1267b",
    "scope_string": "https://auth.globus.org/scopes/51c27a39-29df-4514-a2e3-d643ccd6eace/things",
    "name": "Permission to do things!",
    "description": "Read/write access to Things!",
    "dependent_scopes": [
      {
        "scope": "be0a590d-0990-4a11-9876-38ff99dde445",
        "optional": false,
        "requires_refresh_token": false
      },
      {
        "scope": "828d63c2-3d1c-4553-aeca-2cc86c16b83d",
        "optional": true,
        "requires_refresh_token": true
      }
    ],
    "client": "51c27a39-29df-4514-a2e3-d643ccd6eace",
    "advertised": false,
    "allows_refresh_token": true
  }
}

5.6. Client Credential Resource

Resource envelope: credential / credentials.

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`client`	UUID	The ID of the client owning the credential.
`name`	String	A display name used to identify credentials to users.
`secret`	String	The client credential secret, only visible in the creation response.
`created`	String	The timestamp of when the credential was created.

5.6.1. Example

{
  "credential": {
    "secret": null,
    "client": "10c7c2b6-391a-4cc9-80f4-beaebe8a4df0",
    "id": "0e7c8b27-7f6c-4fb0-a3ff-ba88434c0718",
    "name": "Testing",
    "created": "2020-02-24T01:47:16.408446+00:00"
  }
}

5.7. Policy Resource

Resource envelope: policy / policies

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`project_id`	UUID	The id of a project this policy belongs to.
`high_assurance`	Bool	Whether or not this policy is applied to sessions. This value may not be updated.
`authentication_assurance_timeout`	Integer	Number of seconds within which someone must have authenticated to satisfy the policy.
`display_name`	String	A user-friendly name for the policy.
`description`	String	A user-friendly description to explain the purpose of the policy.
`domain_constraints_include` [Optional]	List of strings	A list of domains that can satisfy the policy. These may include wildcards. E.g. `["*.edu", "globus.org"]`. See the developer guide for more details.
`domain_constraints_exclude` [Optional]	List of strings	A list of domains that can not satisfy the policy. These may include wildcards. E.g. `["*.edu", "globus.org"]`. See the developer guide for more details.
`required_mfa` [Optional]	Bool	If `true`, then multi-factor authentication is required. This can only be set to `true` for high-assurance policies. The default is `false`.

5.7.1. Example

{
  "policy": {
    "authentication_assurance_timeout": 300,
    "high_assurance": true,
    "display_name": "test_policy",
    "id": "579c7af6-200a-4eb2-b4aa-6ccd9f38f2fa",
    "project_id": "1ea2de2a-64f2-4296-a171-b61f3a5d6c09",
    "domain_constraints_include": [
      "*.edu",
      "uchicago.edu"
    ],
    "description": "blah",
    "domain_constraints_exclude": null,
    "required_mfa": true
  }
}

5.8. Get Projects

GET /v2/api/projects

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Returns a list of projects the authenticated entity is an admin of.

GET /v2/api/projects/<project_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Returns a specific project if the authenticated entity is an admin of the project.

5.9. Create Project

POST /v2/api/projects

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Create a new project with a set of admins.

At least one of admin_ids or admin_group_ids must be provided.

Field	Type	Description
`display_name`	String (REQUIRED)	The name of the project.
`contact_email`	String (REQUIRED)	An email address at which to contact the admins or owners about the project.
`admin_ids`	List of uuids (OPTIONAL, SEE ABOVE)	This is a list of identity ids that will be granted admin privileges on the project.
`admin_group_ids`	List of uuids (OPTIONAL, SEE ABOVE)	This is a list of group ids whose members will be granted admin privileges on the project.

5.9.1. Example POST Request

{
  "display_name": "Guardians of the Galaxy",
  "contact_email": "star.lord2@guardians.galaxy",
  "admin_ids": [
    "bd420b5e-2739-11ee-9eec-0242ac110002"
  ],
  "admin_group_ids": []
}

5.9.2. Example Response

{
  "project": {
    "contact_email": "support@globus.org",
    "id": "bd4209a6-2739-11ee-9eec-0242ac110002",
    "admins": {
      "identities": [
        {
          "identity_provider": "bd420ad2-2739-11ee-9eec-0242ac110002",
          "identity_type": "login",
          "organization": "Guardians of the Galaxy",
          "status": "used",
          "id": "bd420b5e-2739-11ee-9eec-0242ac110002",
          "name": "Star Lord",
          "username": "star.lord@guardians.galaxy",
          "email": "star.lord2@guardians.galaxy"
        }
      ],
      "groups": []
    },
    "project_name": "Guardians of the Galaxy",
    "admin_ids": [
      "bd420b5e-2739-11ee-9eec-0242ac110002"
    ],
    "admin_group_ids": null,
    "display_name": "Guardians of the Galaxy"
  }
}

5.10. Update Project

PUT /v2/api/projects/<project_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Update any of the fields on the project All fields are optional on the update payload.

Field	Type	Description
`display_name`	String	The name of the project.
`contact_email`	String	An email address at which to contact the admins or owners about the project.
`admin_ids`	List of uuids	This is a list of identity ids that will be granted admin privileges on the project.
`admin_group_ids`	List of uuids	This is a list of group ids whose members will be granted admin privileges on the project.

5.11. Delete Project

DELETE /v2/api/projects/<project_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Permanently delete a project. Attempting to delete a project with clients or policies will result in an error.

5.12. Get Clients

GET /v2/api/clients

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Returns a list of clients the authenticated entity is an owner of.

GET /v2/api/clients/<client_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Returns a specific client.

GET /v2/api/clients?fqdn=<fqdn>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Returns the client owning the FQDN, or a 404 if it is unclaimed.

5.13. Create Client

POST /v2/api/clients

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Field	Description
`name`	String without line-breaks, with no more than 100 characters. (REQUIRED)
`public_client`	Boolean. Used to infer which `grant_types` the client will be able to use. `false` gives `["authorization_code", "client_credentials", "refresh_token", "urn:globus:auth:grant_type:dependent_token"]` and `true` gives `["authorization_code", "refresh_token"]`. (REQUIRED)
`project`	ID of the project the client belongs to. (REQUIRED if creating as a user, IMPLICIT if creating as a client)
`visibility`	String, `public` or `private`. (OPTIONAL, defaults to `private`)
`redirect_uris`	List of URL strings. (OPTIONAL)
`links`	`{"terms_of_service": <url>, "privacy_policy": <url>}`. (OPTIONAL)
`required_idp`	UUID representing an IdP. (OPTIONAL)
`preselect_idp`	UUID representing an IdP. (OPTIONAL)

For more details on the parameters see Client Resource above.

Returns: A client document.

5.13.1. Create Native App Instance

POST /v2/api/clients

A special case of client creation is creating a native app instance. The endpoint is the same as for normal client creation, but it only takes the following two parameters:

Field	Description
`template_id`	UUID of a previously registered native app template. (REQUIRED)
`name`	String without line-breaks, with no more than 100 characters. (REQUIRED)

Unlike every other call to Globus Auth this call does not need to be authenticated, since it’s intended to be made by publicly distributed installation packages.

5.14. Update Client

PUT /v2/api/clients/<client_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

Update supports the same parameters as create, except for public_client and project which are immutable. All parameters are optional, and unsupported parameters are ignored silently.

Field	Description
`name`	String without line-breaks, with no more than 100 characters.
`visibility`	String, `public` or `private`.
`redirect_uris`	List of URL strings.
`links`	`{"terms_of_service": <url>, "privacy_policy": <url>}`.
`required_idp`	UUID representing an IdP.
`preselect_idp`	UUID representing an IdP.

5.15. Delete Client

Warning

Deleting a client deletes all resources associated with it. This includes user consents, scopes (which means this operation can cause other apps and services that depend on those scopes to stop working as well), and any child clients owned by the client (which in turn means that all resources associated with the child clients would get deleted as well). This action cannot be undone.

DELETE /v2/api/clients/<client_id>

Required scope: urn:globus:auth:scope:auth.globus.org:manage_projects

5.16. Get Scopes

GET /v2/api/scopes/<scope_id> or GET /v2/api/clients/<client_id>/scopes/<scope_id>

Retrieves a single scope.

GET /v2/api/scopes?ids=<comma-separated-list-of-scope-ids>

Retrieves a list of scopes.

GET /v2/api/scopes?scope_strings=<comma-separated-list-of-scope-strings>

Retrieves a list of scopes.

GET /v2/api/scopes

Retrieves a list of all scopes the authenticated entity is an owner of.

Scopes are viewable if the authenticated entity is allowed to view the client that owns the scope, or if the scope is publicly advertised ("advertised": true).

5.17. Create Scope

POST /v2/api/clients/<client_id>/scopes

Creates a scope for each registered FQDN + the id of the client. For example, if a client with ID cf01eb30-9884-11e5-8d77-87f1f8b059db and FQDN example.com, POSTS "scope_suffix": "things, this will create the two scopes https://auth.globus.org/scopes/cf01eb30-9884-11e5-8d77-87f1f8b059db/things and https://auth.globus.org/scopes/example.com/things.

Field	Description
`name`	String without line breaks, with no more than 100 characters. (REQUIRED)
`description`	String with no more than 5000 characters. (REQUIRED)
`scope_suffix`	String consisting of lowercase letters, number, and underscores. This will be the final part of the `scope_string`. (REQUIRED)
`dependent_scopes`	List of dicts: `{"scope": <scope_id>, "optional": <boolean>, "requires_refresh_token": <boolean>}`. (OPTIONAL)
`advertised`	Boolean. Default: `false`. (OPTIONAL)
`allows_refresh_token`	Boolean. Default: `true`. (OPTIONAL)

Returns: A list of scope documents.

For more details on the parameters see Scope Resource above.

5.18. Update Scope

PUT /v2/api/scopes/<id>

Parameters: Same as for scope creation above, except that scope_suffix is omitted. All parameters are optional, and unsupported parameters are ignored silently.

5.19. Delete Scope

Warning

Deleting a scope deletes all resources associated with it, including revoking associated tokens. This operation can cause other apps and services that depend on the scope to stop working. This action cannot be undone and a new scope with the same suffix can not be created for the same client.

DELETE /v2/api/scopes/<scope_id>

5.20. Get Client Credentials

GET /v2/api/clients/<client_id>/credentials

Retrieves a list of all credentials owned by the authenticated entity. Note that the secrets are not returned when getting credentials - the secret is only displayed on credential creation.

5.21. Create Client Credential

POST /v2/api/clients/<client_id>/credentials

Creates a client credential for the respective Globus Auth client. The request body contains the name of the credential.

Field	Description
`name`	String without line breaks, with no more than 100 characters. (REQUIRED)

Returns: The credential created and the generated secret.

Note

This is the only time the secret is visible. Globus cannot recover a lost secret.

5.22. Delete Client Credential

DELETE /v2/api/clients/<client_id>/credentials/<credential_id>

Delete a client credential from the client.

5.23. Get Policies

GET /v2/api/policies

Returns a list of policies the authenticated entity is an admin of.

GET /v2/api/policies/<policy_id>

Returns a specific policy if the authenticated entity is an admin of the project owning the policy.

5.24. Create Policy

POST /v2/api/policies

Create a new policy in a given project

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`project_id`	UUID	The id of a project this policy belongs to.
`high_assurance`	Bool	Whether or not this policy is applied to sessions.
`authentication_assurance_timeout`	Integer	Number of seconds with which time someone must have authenticated to satisfy the policy.
`display_name`	String	A user friendly name for the policy.
`description`	String	A user friendly description to explain the purpose of the policy.
`domain_constraints_include` [Optional]	List of strings	A list of domains that can satisfy the policy. These may include wildcards. E.g. `["*.edu", "globus.org"]`. See the developer guide for more details.
`domain_constraints_exclude` [Optional]	List of strings	A list of domains that can not satisfy the policy. These may include wildcards. E.g. `["*.edu", "globus.org"]`. See the developer guide for more details.
`required_mfa` [Optional]	Bool	If `true`, then multi-factor authentication is required. This can only be set to `true` for high-assurance policies. The default is `false`.

5.25. Update Policy

PUT /v2/api/policies/<policy_id>

Update any of the fields on the policy. All fields are optional on the update payload.

5.26. Add FQDN

POST /v2/api/clients/<client_id>/fqdns

Parameters: - fqdn: A FQDN string which the client of the RS can prove possession of.

Possession is proven by, before performing this call, adding a DNS TXT record to the FQDN containing the ID of the client.

If the expected TXT record is not found, a 403 Forbidden HTTP response is returned. Note that DNS records may take a while to propagate fully, and because of this clients are permitted to keep retrying for certain period of time. Clients should limit their retries to no more than one request per seconds for a total of no more than 30 minutes.

This call has a side effect of creating scopes for previously registered `scope_suffix`es, similar to how Create Scope creates one scope for each previously registered FQDN.

Example response:

{
  "fqdn": "foo.bar.org",
  "included": {
    "scopes": [
      {
        "advertised": false,
        "allows_refresh_token": true,
        "dependent_scopes": [],
        "description": "Read/write access to Things!",
        "id": "0d38bf9a-33c2-4995-b5bb-90bca2ac3c52",
        "name": "Things!",
        "scope_string": "https://auth.globus.org/scopes/foo.bar.org/things"
      }
    ]
  }
}

6. Identity Providers API

Identity providers registered via this API can assert identities from a specified set of domains to Globus Auth. Globus Auth is a client to these identity providers and will direct to the identity provider when a login is requested from one of the registered domain(s). The API allows existing identity providers to be integrated into Globus Connect Server installations.

Registering an identity provider requires that you validate your ownership of the domain(s). To prove this, the domain must be registered as an FQDN for the client making the call. This ensures that the asserted domains are owned by the client. Please refer to the Add FQDN section above for more information.

Note

Identity providers registered via this API are intended to be used with Globus Connect Server Storage Gateway domain restrictions and registered instances will not be listed in the Globus login page. If you wish to use your identity provider for normal user login, please refer to the Alternate Identity Provider Registration page.

6.1. Access Control

Identity provider API calls should be made with client credentials.

Updates and deletions calls are restricted to the same client that performed the creation of the identity provider (i.e. their owners).

6.2. Identity Provider Resource

Resource envelope: identity_provider / identity_providers.

Field	Type	Description
`id`	UUID	A unique ID generated by Globus Auth.
`name`	String	The display name for the identity provider. May not contain linebreaks.
`short_name`	String	The internal name for the identity provider.
`alternative_names`	List of String	The alternative names given the identity provider, used for search terms.
`domains`	List of String	List of domains that this identity provider can assert identities for.

6.2.1. Example

{
  "identity_provider": {
    "id": "41143743-f3c8-4d60-bbdb-eeecaba85bd9",
    "name": "Globus ID",
    "short_name": "globusid",
    "alternative_names": [],
    "domains": [
      "globusid.org"
    ]
  }
}

6.3. Get Identity Providers

GET /v2/api/identity_providers?domains=globusid.org,google.com

Returns a list of identity providers that assert the domains specified in the comma-delimited domain query parameter.

GET /v2/api/identity_providers?ids=41143743-f3c8-4d60-bbdb-eeecaba85bd9

Returns a list of identity providers identified by the comma-delimited ids query parameter.

6.4. Create Identity Provider

POST /v2/api/identity_providers

Field	Type	Description
`name`	String	The display name for the identity provider. May not contain linebreaks and must be unique.
`discovery_url`	String	The OpenID Connect discovery URL for the identity provider. The URL must from the same domain that is asserted by the identity provider. Note that the domain name from the well-known is asserted as the domain name for the identities. Please refer to the FQDN client requirement below.
`domains`	List of String	Optional list of additional domains that are asserted by the identity provider. The domain of the discovery URL will always be included, this is only necessary if additional domains should be asserted. Please refer to the FQDN client requirement below.
`attribute_map`	Dictionary	A map that indicates which identity provider claims should map to the user name and immutable ID. In general this should be `{"username": "preferred_username", "immutable_id": "sub"}`.
`client_credentials`	Dictionary	The credentials that Globus Auth should use to authenticate with the new identity provider, in the format `{ "client_id": "…", "client_secret": "…"}`.
`contact_name`	String	The name of the administrator of the identity provider.
`contact_email`	String	The email address of the administrator of the identity provider.

Note

All domains that must be registered as FQDNs for the client before making the create call. This ensures that the domains are managed by the client, and includes the domain of the well-known as well as the optional domains. Please refer to the Add FQDN section above for more information.

6.5. Update Identity Provider

PUT /v2/api/identity_providers/<identity_provider_id>

Update supports the same parameters as create, and must be called as the same client that created the identity provider. The name and discovery URL may not be updated.

6.6. Delete Identity Provider

Warning

Deleting an identity provider deletes all resources associated with it. This action cannot be undone.

DELETE /v2/api/identity_providers/<identity_provider_id>

Deletes the identity provider and all associated elements. This includes all identities and the associated domains so that the domains may be potentially reused in the future. Globus Auth will not be able to assert any identities from the deleted domains, so any Storage Gateways using the identity provider will have to be reconfigured. As with update, DELETE must be called as the same client that created the identity provider.

7. References

[OIDC] N. Sakimura, N., J. Bradley, J., M. Jones, M., B. de Medeiros, B., C. Mortimore, C., "OpenID Connect Core 1.0", November 8, 2014, <http://openid.net/specs/openid-connect-core-1_0.html>.
[REFEDS-RS] "REFEDS Research and Scholarship Entity Category, Version 1.2", November 2014, <https://refeds.org/category/research-and-scholarship/>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <http://www.rfc-editor.org/info/rfc6749>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, <http://www.rfc-editor.org/info/rfc7159>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, <http://www.rfc-editor.org/info/rfc7231>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC6749, October 2015, <https://www.rfc-editor.org/info/rfc7662>.
[W3C.REC-html5-20141028] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Navara, E., O’Connor, E., and S. Pfeiffer, "HTML5", World Wide Web Consortium Recommendation REC-html5-20141028, October 2014, <http://www.w3.org/TR/2014/REC-html5-20141028>.

Portions of this document were adapted from Google documentation under the terms of the Creative Commons.