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


Table of Contents

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.

(Globus Auth Version 1 was an API known as "Globus Nexus" or "Globus Graph", which was only available for select uses outside Globus.)

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

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

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

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

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

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 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-delimited 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

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

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

https://auth.globus.org/v2/oauth2/authorize?
 scope=urn%3Aglobus%3Aauth%3Ascope%3Aauth.globus.org%3Aview_identities+openid+email+profile&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps://oa2cb.example.com/myHome&
 redirect_uri=https%3A%2F%2Foauth2-login-demo.example.com%2Fcallback&
 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 field:

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 HTTP/1.1
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",
  "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,
      "id_token": "eyJ0eXAiOiJKV1QiLA0KICJh...",
      "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

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:

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 HTTP/1.1
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

Resource Owner Password Credentials Grant : For obtaining an access token for a non-browser-based client (e.g., command line, mobile, or desktop application).

Note:This feature will only work with certain identity providers that are configured to support non-browser-based authentication based on username and password.

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

Field Description

scope

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 HTTP/1.1
Host: auth.globus.org
Content-Type: application/x-www-form-urlencoded
Authorization: Basic NDFjYTIwM2QtNzcwMy00NDYxLWFiNGItNjVhNjA0YjE2NjE5OjxDTElFTlRfU0VDUkVUPg==
scope=openid+email+profile+urn%3Aglobus%3Aauth%3Ascope%3Atransfer.api.globus.org%3Aall&
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: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.

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.

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

    • preferred_username: The identity username for the effective identity id provided by the ‘sub' claim.

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 Description

sub

UUID

Globus Auth issued identity id, guaranteed to uniquely identify a single identity. Included with all responses.

preferred_username

String

The username of the identity. Included with responses for the profile scope

name

String

The user’s name (e.g. Jane Doe). Included with responses for the profile scope

email

String

The email address associated with the identity, if known. Included with responses for the email scope

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 HTTP/1.1
Host: auth.globus.org
Authorization: Bearer A7oU1xJ8-ddvRiMf-ZFDvXb

Example response:

{
  "email": "ztaylor@example.com",
  "name": "Zachary Taylor",
  "preferred_username": "ztaylor@globusid.org",
  "sub": "e9a5903a-cb98-11e5-a7fa-afe061bd0f40"
}

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.

Request parameters are:

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 identities_set which will include the list of all identities ids (primary and linked) that are associated with this Globus Auth account, and session_info which will include information about which identities have authenticated in the current Session and when.

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 this POST is an RFC 7662 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.

scope

Space-separated List of Strings

List of scopes to which this access token authorizes access.

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 resource server DNS name and the client_id of the client to which this token was issued. 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.

identities_set* [OPTIONAL]

List of UUIDs

A list of all identities 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=identities_set in the POST body.

session_info* [OPTIONAL]

Object

Contains information about the Session the token derives from. For more information please see the Sessions Guide.

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 HTTP/1.1

        Host: auth.globus.org

        Accept: application/json

Content-Type: application/x-www-form-urlencoded

        Authorization: Basic MmZkYTQxNDktODJmZi00OTM3LT

        token=A7oU1xJ8-ddvRiMf-ZFDvXb&include=identities_set,session_info

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": "server.example.com",
    "iss": "https://auth.globus.org/",
    "exp": 1419356238,
    "iat": 1419350238,
    "nbf": 1419350238,
    "name": "Joe User",
    "email": "user1@example.dom",
    "identities_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"
            }
        }
    }
}
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)

This can only be used by a resource server, authorized using that resource server’s client identifier and client secret.

When a resource server receives a request from a client, after validating the access token included in the request (<request access token>) via token introspection (POST /v2/oauth2/token/introspect), the resource server may need to retrieve dependent access tokens that allow this resource server to act as a client to other resource servers on behalf of the client. The resource server does so by performing a Globus Auth "Dependent Token Grant", which is an OAuth2 Extension Grant.

In conformance with the OAuth2 standard, the resource server does so by performing an HTTP POST on /v2/oauth2/token, with parameters sent as "application/x-www-form-urlencoded" data as defined in W3C recommendations.

Request parameters are:

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

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.

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 HTTP/1.1
        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

The response will be a JSON document containing an array of OAuth2 standard access_token response documents. The number of tokens returned and their scopes are pre-determined by the scope dependencies registered with Globus Auth by the resource server administrators. The resource server does not have the ability to request particular scopes when using this grant type.

For example, if the above request was made by the transfer.api.globus.org resource server upon receipt of a request to 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:check_membership and urn:globus:auth:scope:auth.globus.org:view_identities scopes, 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:check_membership",
        "expires_in": 3600,
        "refresh_token": "dPVJBKAUs0x8UW4zhgQWv6snDmo2X72E",
        "token_type": "bearer"
    }
]

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 re-used by the identity provider. An id will never be re-used. 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 re-use 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", indicicating 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 identities

GET /v2/api/identities/<id>

Responds with an identity resource type 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.

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

Returns a list of identity resource type documents for the comma separated list of identity ids.

If the identity id does not exist, it is not in the list…

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

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

Returns a list of identity resource type documents for the comma separated list of identity ids.

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%40globusid.org,webapptester2%40globusid.org HTTP/1.1
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. Clients and Scopes API

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

Most calls in the Clients and Scopes API can only be made by clients, not by users.

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.

Resources can only be updated by their owners.

5.3. 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. Has the values ["authorization_code", "client_credentials", "refresh_token", "urn:globus:auth:grant_type:dependent_token"] if public_client is false, and ["authorization_code", "refresh_token"] if it is true.

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.

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 preselects 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.3.1. Example

{
  "client": {
    "id": "cf01eb30-9884-11e5-8d77-87f1f8b059db",
    "name": "Globus Transfer",
    "public_client": false,
    "grant_types": [
      "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.4. 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.4.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 a 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.4.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.5. Get Clients

GET /v2/api/clients

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

GET /v2/api/clients/<client_id>

Returns a specific client.

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

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

5.6. Create Client

POST /v2/api/clients

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.6.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.7. Update Client

PUT /v2/api/clients/<client_id>

Update supportis 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.8. 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>

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

Retrives a list of all scopes the authenticated entitity 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.10. 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.11. 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.12. Delete Scope

Warning:Deleting a scope deletes all resources associated with it. This operation can cause other apps and services that depend on the scope to stop working. This action cannot be undone.

DELETE /v2/api/scopes/<scope_id>

5.13. 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. References

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


© 2010- The University of Chicago Legal