Globus Auth Developer Guide

This guide describes how to develop apps and services using Globus Auth, how to register your login provider, how to leverage linked identities to allow your users to use whichever login provider they want, which libraries and resources to use to make your life as a developer easier, and sample apps and services.

1. Developing an Application Using Globus Auth

A Globus Auth application is used to authenticate users and/or to obtain access to other services. At a very high level, the development cycle consists of:

  1. Registering an application client at https://developers.globus.org.

  2. Obtaining authorization. Applications request access to services via scopes using a standard OAuth2 flow.

  3. Using tokens to authenticate to services.

Those are the basics. Apps that want to provide their users with a more complete, integrated experience can then start looking into features such as skinning and other features such as allowing users to initiate linking identities from right inside your app.

Applications can make use of several different services, allowing them to implement features and orchestrate flows that wouldn’t be possible by using any single service.

1.1. Registering an Application

Globus requires client applications (apps) to be registered. To register a new app, visit app.globus.org/settings/developers, and sign in. Next, select the type of application you wish to register (Service Account, Portal / Science Gateway, Thick Client, API, or Advanced Application), and create a new project or select an existing one. Depending on the application type you choose to register, you may not see all of the options listed below. Complete the App Registration form using the instructions provided, and click "Register App" when you’ve finished filling out the form.

  • For the App Name, enter the name you’d like displayed on Globus login and user consent pages when users login to your app.

  • In the Redirects field, enter the Web address(es) to which Globus will redirect your users' browsers after they authenticate. This is where your app will receive the user’s identity token and any requested access tokens. Your app’s code will specify a Redirect address when it calls the Auth API, and it must match one of the Redirect addresses registered here. Most apps only have one Redirect address, but you may list more than one if necessary.

    • The redirect URI must use the HTTPS protocol and it may contain a port number. For development and testing purposes, an exception is made for http://localhost/*.

    • If you are registering an app developed by someone else (e.g., an OpenID Connect or OAuth2 authentication plugin), refer to the author’s documentation to find out what the Redirect address should be.

    • If your app is a native app (see below), the address you enter here will receive the user’s access code. Globus provides a helper page that you can use as a Redirect address for your native apps at https://auth.globus.org/v2/web/auth-code.

  • If you check the Required Identity box and select an identity provider, Globus will require anyone logging in to your app to have an identity with the selected provider. The authentication response will always contain the identity data from the required provider.

    Note
    Your app’s users may still use any identity provider to authenticate, but they must have a linked identity from the required provider to complete the login process. If someone hasn’t already linked an identity from the required provider, Globus will prompt him or her to authenticate with the required provider and then (optionally) link that identity to his or her primary identity.

  • If you check the Pre-select Identity Provider box and select an identity provider, it will be the default organization on your app’s login page. This is a good way to suggest an organization if you know that most of your users belong to it.

    Note
    This default will not be seen by anyone who has already set his or her own preferred organization in Globus.

  • Enter the Web addresses for your app’s Privacy Policy and/or Terms & Conditions. Globus will provide links to them on the login and user consent pages. If you leave these blank, Globus will state that your app does not provide them.

  • If your app is a web app hosted on a secure server, do not check the Native App checkbox. Globus will consider your app a confidential client (a client that can protect a secret) and Globus will provide authentication secrets that can be configured into the app. These secrets allow your app to use Globus’s confidential client interfaces, which support ordinary OpenID Connect authentication in a Web browser.

    You should check this box if your app will be downloaded or installed on your users' devices. (This includes mobile apps as well as downloadable/installable computer applications.) Globus will not provide authentication secrets for your app. Instead, your app will direct users to open a Web browser to a specific address and authenticate there. On successful authentication, Globus will provide a one-time access code. Your app will use this access code to obtain the user’s identity and any requested access tokens. (See the material below on Refresh Tokens for long-term/continuous authorization.)

Once you’ve registered your app, its registration data will be available in your project under the app’s name. Click your app’s name to view the registration data. Notice that Globus has added a Client ID, which you’ll need when configuring your app.

This page also allows you to generate Client Secrets, which you’ll need when configuring your app. (Remember from above that native apps don’t use client secrets.) When you generate a secret, you must provide a description.

Tip
You’ll use this description to refer to this specific secret later on, so we recommend including the current date.

If you lose your client secret, you must generate a new one. It is best to copy and paste the secret directly into your app’s configuration file.

Tip
Your app can have more than one client secret active at a time. We recommend using this for client secret rotation. When you generate a new client secret, leave the old one active until you’re certain your app has been reconfigured with the new secret.

You may delete a secret using the description you provided when you created it. Once a secret is deleted, any clients configured with that secret will no longer have access to the Auth API.

1.2. Obtaining Authorization

Globus Auth is fully spec compliant OAuth2 implementation. It is recommended that developers use an off-the-shelf OAuth2 library. Below is a description of the basic authorization flow. Sections of the OAuth2 specification are referenced for more details.

  1. Authorization request (https://tools.ietf.org/html/rfc6749#section-4.1.1). The application client constructs a link to an authorization page and directs the user to it. The URL is https://auth.globus.org/v2/oauth2/authorize with the following URL encoded query params:

    • client_id. The UUID of the client application.

    • redirect_uri. The URI the user will be redirected back to for the authorization response. Must be pre-registered for this client.

    • scope. A space-separated list of scopes the application is requesting access to. If refresh tokens are needed, include the offline_access scope.

    • state. An opaque value that is returned to the client in the authorization response. The client should use this value to prevent cross-site request forgery as described in https://tools.ietf.org/html/rfc6749#section-10.12.

    • response_type. Value must be code.

    • If the application client is a native app the request must also contain a code_challenge and code_challenge_method as described in the PKCE section below.

    • All parameters must be URL encoded.

    • Example of an app requesting access to Globus Transfer and the Globus Auth Identities API with refresh tokens: https://auth.globus.org/v2/oauth2/authorize?client_id=69ba5e62-7285-45db-952d-e0bb73b5eac7&scope=urn%3Aglobus%3Aauth%3Ascope%3Atransfer.api.globus.org%3Aall%20urn%3Aglobus%3Aauth%3Ascope%3Aauth.globus.org%3Aview_identities%20offline_access&response_type=code&redirect_uri=https%3A%2F%2Fwww.example.org%2Fmy_app%2Flogin&state=g6l14b2xlgx4dtce8d2ja714i

  2. The user is prompted to authenticate, and to consent to giving the client application access to the requested scopes if they have not previously consented (if they have already consented this screen is bypassed).

  3. Authorization response (https://tools.ietf.org/html/rfc6749#section-4.1.2). If the user successfully authenticates and consents they will be returned to the redirect_uri included in the authorization request, with the following included as URL encoded query params:

    • code. The authorization code the client application will use to exchange for access/refresh tokens.

    • state. The value the client provided in the authorization request.

  4. Access token request (https://tools.ietf.org/html/rfc6749#section-4.1.3). To exchange the code for an access token, a POST is made to https://auth.globus.org/v2/oauth2/token with the following URL encoded query params:

    • grant_type. Value must be authorization_code.

    • code. The code received in the authorization response.

    • redirect_uri. Must be identical to the value sent in the authorization request.

    • If the application client is confidential it must authenticate this call using its client credentials. If the client is a native app it must instead include a code_verifier parameter as described in the PKCE section below.

  5. Access token response (https://tools.ietf.org/html/rfc6749#section-4.1.4). The token response is described in the following section.

1.3. Using Tokens

A successful token response from Globus Auth contains one or more access tokens, and zero or more refresh tokens. The following is an example response from the request above:

{
  "access_token": "<access-token-for-globus-transfer>",
  "id_token": "<id-token>",
  "expires_in": 172800,
  "resource_server": "transfer.api.globus.org",
  "token_type": "Bearer",
  "state": "g6l14b2xlgx4dtce8d2ja714i",
  "scope": "urn:globus:auth:scope:transfer.api.globus.org:all",
  "refresh_token": "<refresh-token-for-globus-transfer>",
  "other_tokens": [
    {
      "access_token": "<access-token-for-globus-auth>",
      "expires_in": 172800,
      "resource_server": "auth.globus.org",
      "token_type": "Bearer",
      "state": "g6l14b2xlgx4dtce8d2ja714i",
      "scope": "urn:globus:auth:scope:auth.globus.org:view_identities",
      "refresh_token": "<refresh-token-for-globus-auth>"
    }
  ]
}

Globus Auth, unlike most OAuth2 implementations, supports providing access to multiple different resource servers, and can therefore return multiple access/refresh tokens in the same response. In order to conform to standards (and to allow off-the-shelf libraries to work) the token response for the first requested scope looks like that of any other standards compliant OAuth2 server, and any additional tokens are included in the other_tokens array.

After receiving the response the application client should do the following:

  • Verify that it received the expected scopes.

  • Verify that the state parameter matches what was sent in the authorization request.

  • Store the token(s) for future use, along with their expiry time. Application clients should always inspect the expires_in value (in seconds) of all received tokens; it may differ from one request to the next.

Access tokens are then used to authenticate against services by including them in the Authorization header of HTTP requests, e.g:

Authorization: Bearer <access-token-for-globus-transfer>

When an access token is nearing its expiry time the application needs to retrieve a new one, either by performing another authorization flow as described above (except this time the user won’t be prompted for consent again), or by performing a refresh token grant.

Refresh tokens are long lived credentials and should never be sent over the wire except when doing a refresh token grant against Globus Auth. Please store them securely.

1.3.1. Token Invalidation

For the security of their users application clients should invalidate tokens when they are done with them, for example as part of a logout operation. This is particularly important for long-lived refresh tokens.

1.4. Client Authentication

Clients authenticate to Globus Auth with a HTTP basic auth header, using client credentials created in the registration interface:

Authorization: Basic <credential>,

where <credential> is the base64 encoded client ID and client credential, separated by a single colon. For instance, in Python the header could be constructed as:

client_id = "69ba5e62-7285-45db-952d-e0bb73b5eac7"
client_credential = "QWxhZGRpbjpPcGVuU2VzYW1l"
client_auth_header = "Authorization: Basic {0}".format(
	base64.b64encode("{0}:{1}".format(client_id, client_credential)))

1.5. PKCE

PKCE (RFC 7636) is a security protocol that allows unauthenticated ("native") application clients to use the three-legged OAuth2 authorization code grant. Confidential clients may use it as well; doing so may guard against certain attacks that would be made possible if client credentials are compromised.

Before starting the authorization flow the application client must generate a code_verifier which meets the following requirements:

  • Generated using a reliably random (i.e., unguessable) method.

  • 43-128 characters long consisting of letters, numbers and the characters -._~.

  • Must be freshly generated for each request.

Second, a code_challenge is created by taking the URL safe base64 encoding, without padding, of a SHA256 digest of the code_verifier. The same constraints that apply to a code_verifier also apply to a code_challenge:

  • 43-128 characters long consisting of the characters a-z, A-Z, 0-9, -, ., _, ~.

  • May only be used once.

  • It is important to note that the = (equals) character is not allowed, and must be stripped off the code_challenge after the base64 encoding.

The authorization URL is then created as described above, but with the two following additional parameters:

  • code_challenge, as just described.

  • code_challenge_method, whose value MUST be S256.

An example of a complete authorization request URL would look similar to the following:

https://auth.globus.org/v2/oauth2/authorize?code_challenge=rennw4QyOe3rIlZq-qTh2gL34pYEC_5JXKSKRhc5lVc&code_challenge_method=S256&state=_default&redirect_uri=https%3A%2F%2Fauth.globus.org%2Fv2%2Fweb%2Fauth-code&response_type=code&client_id=asdf&scope=openid+profile+email&access_type=online

Just as with the normal flow, the user is then prompted to authenticate and consent, and is sent back to the redirect_uri. For the final step, the access token request, the application client must include the code_verifier parameter created above.

These additions allows Globus Auth to verify that the request originated from a particular instance of the application client, so that an attacker is unable to steal a token even if they manage to compromise the authorization code.

1.6. Skinning

Globus Auth supports skinning, so that when a user comes in from your app the look of Globus Auth matches that of your application. Setting this up is a manual process, please contact us for more details!

2. Developing a Service

A Globus Auth service is a system that provides access to resources owned by users, and wants to provides access to those resources to applications used by end-users, typically via a HTTP API. Services can also expand their functionality by in turn making use of other services.

Registering a Service is currently a manual process. Please contact us for more information!

3. Working With Sessions for Higher Assurance

Globus Auth supports a concept of Sessions which allows services to determine (and restrict access based on) which identities the user has used to authenticate and when via the introspect endpoint.

It also allows apps and services to prompt users for authentication with a particular identity.

For a detailed description of Sessions, please see the Sessions Guide.

4. Adding an Identity Provider

Please contact us if you wish to add your identity provider to Globus Auth to allow your users to use their normal login for authenticating against apps and services.

5. Managing Projects

All apps and services that you register will be part of a project. You can add and remove admins to allow others to manage the project. All admins are co-equal, meaning that anyone you add will be able to add/remove/edit all of your apps and services.

When registering you are asked to provide a contact email. It will only be used to give you important notifications related to your project. If you expect your project to last many years, please make sure to keep the contact email current.

6. Authentication Policies

Globus Auth supports the ability to define an Authentication Policy that can be used to verify that the user has appropriate identities linked to their account and that the required identities have recent authentications.

To use the authentication policy feature, users can specify the session_required_policies query parameter when initiating an authentication flow. The value of this parameter should be a UUID that corresponds to the auth policy that should be used for the authentication.

6.1. Authentication Policy Fields

Auth policies include the following fields:

  • domain_constraints_include: A list of domains or shell-style globs (e.g. *.example.com) that are required to be present when selecting an identity for linking or login. Only identities with email domains that match one of these domains or globs will be considered. If this field is not provided, all domains will be considered.

  • domain_constraints_exclude: A list of domains or shell-style globs that should be excluded when selecting an identity for linking or login. Identities with email domains that match one of these domains or globs will not be considered. Domains in this list take precedence over domain_constraints_include. If an identity matches a domain in both the domain_constraints_include and domain_constraints_exclude fields, it will be excluded.

  • high_assurance: A boolean flag that indicates whether high assurance is required for the identity selection process. If this flag is set to true, the identity must not only match the domain constraints, but also must have been authenticated with the user’s current browser session within the authentication_assurance_timeout.

  • authentication_assurance_timeout: The maximum amount of time in seconds that a previous authentication can be considered recent for the purposes of high assurance.

6.2. Policy Enforcement

If the high_assurance flag is set to false, Globus Auth will require that an identity that matches the domain constraints is linked to the user’s primary identity. If the high_assurance flag is set to true, Globus Auth will require not only that a matching identity is linked, but also that it has been authenticated with the user’s current browser session within the authentication_assurance_timeout. If no linked identity meets the domain constraints, the user will be prompted to authenticate with an identity that matches the domain constraints. If no identity meets the domain constraints, the authentication flow will fail.

6.3. Limiting Identity Providers

When using domain constraints, the list of allowed identity providers for the user to authenticate with will be limited based on whether the identity domain matches one of the globs in the constraint parameter.

7. Libraries and Resources

7.1. Using the Globus Python SDK

Globus provides a Python SDK for interacting with its APIs, including Globus Auth and Transfer. Documentation can be found here.

7.2. OAuth2 Libraries

7.3. Sample Applications and Services Using Globus Auth

The Globus Sample Data Portal contains an example of both an application and a service. Beyond basic app/service functionality, it demonstrates the use of downstream-services (in this case Globus Transfer), client identities and other features.

The Native App Examples GitHub repository provides some working example scripts for how to build applications that use the Native App authentication flow.