Globus Auth Specification

1. Introduction

Globus Auth is a foundational identity and access management (IAM) platform service, used for brokering authentication and authorization interactions between end-users, identity providers, resource servers (services), and clients (including web, mobile, desktop, and command line applications, and other services).

The goal of Globus Auth is to enable an extensible, integrated ecosystem of services and clients for the research and education community. A typical research/education end-user has many identities, issued by different identity providers (e.g., universities, national laboratories, software-as-a-service (SaaS) web applications, commercial services). This end-user uses various application clients (e.g., web, mobile, desktop, command line). These clients leverage a variety of web/cloud services, from many providers, and these services even leverage each other. Globus Auth provides the security glue to allow end-users to easily access this ecosystem of clients and services. It also makes it possible for an extensible set of identity, client, and service providers to participate in this ecosystem and to leverage each other’s capabilities while providing end-users with a consistent user experience.

Globus Auth is compliant with the OAuth2 and OpenID Connect standards, but extends them to support use cases that are beyond the scope of those standards. Compliant OAuth2 and OpenID Connect clients should work with Globus Auth with little or no changes.

2. Overview (Relative to OAuth2 and OpenID Connect)

This specification assumes the reader has a solid understanding of the OAuth2 and OpenID Connect specifications, as it leverages them heavily. Throughout this specification, we use the terminology consistent with the OAuth2 and OpenID Connect specifications. In this section, we use OAuth2 and OpenID Connect terms in italics, to help clarify the relationship.

Specifications:

A protected resource (or simply resource throughout this specification) is something that can be addressed via a URL, and is accessible to authorized clients via HTTPS methods, for example via a REST API.

Globus Auth is an authorization server. It issues an access token to a client after successfully authenticating the resource owner and obtaining authorization for the client to access resources provided by a resource server. The resource owner is typically an end-user, who authenticates to a Globus Auth-managed Globus account using an identity issued by one of an extensible set of (federated) identity providers supported by Globus Auth. The resource owner authorizes (e.g., consents) that the client can request access to the resource server on the resource owner's behalf within a limited scope. The client might be an application (e.g., web, mobile, desktop, command line), or it may be another service, as described below.

When a client makes a request to a resource server, it presents the access token as part of the request (in the HTTP Authorization header), to demonstrate that it is authorized to make the request.

Globus Auth can act as the authorization server to an extensible set of resource servers. All Globus services, such as the Globus data management and groups services, are resource servers that use the Globus Auth authorization server. Third parties can also create their own resource servers that rely on the Globus Auth authorization server in exactly the same way as Globus services. This broad applicability is why we call Globus Auth a foundational service: it provides a platform for an extensible, integrated ecosystem of resource servers and their clients.

The OAuth2 specification states, "The interaction between the authorization server and resource server is beyond the scope of [the OAuth2] specification." [OAuth2 section 1.1] Globus Auth fills this gap by defining a REST API that allows a resource server, upon receiving a request with an access token from a client, to verify that the access token is valid and intended for use with this resource server, and to query for additional information related to that access token such as the client identity, the scope, the resource owner's identity, and other identities linked to that resource owner's identity, which the resource server can use to make authorization decisions for the request. Globus Auth leverages the OAuth 2.0 Token Introspection (RFC 7662) specification for this interaction.

Globus Auth also plays the role of an OAuth2 resource server, allowing clients to access Globus Auth-managed resources, such as identities, and access tokens. For example:

  • Clients (e.g., Globus or third-party web applications) acting on behalf of end-user resource owners, can be clients to the Globus Auth resource server, to access and manage the end-user’s Globus account-related information.

  • When a resource server receives a request from a client with an access token, that resource server assumes the role of a (different) client to the Globus Auth resource server, in order to validate the access token. In this situation, the resource server uses its own client id and client secret when making requests to the Globus Auth resource server.

  • An identity provider can act as a client to the Globus Auth resource server to provision and manage identities within the identity provider’s namespace. In this situation, the identity provider uses its own client id and client secret (established previously through a registration process with Globus Auth) when making requests to the Globus Auth resource server.

Globus Auth also allows a resource server, upon receipt of a request from a client on behalf of a resource owner, to assume the role of a client to any other resource server on behalf of that resource owner, subject to authorization. Globus Auth provides an API that allows a resource server to exchange an access token (the "request access token") from its upstream client, for new access tokens ("dependent access tokens") that it can use for requests to downstream resource servers within limited scopes.

3. Identities

A Globus Auth identity has a unique, case-insensitive username (e.g., "user@example.org"), issued by an identity provider (e.g., a University, Google), for which a user or client can prove possession via an authentication process (e.g., presenting a password to the identity provider). Globus Auth manages the use of identities (e.g., to login to clients and services), their properties (e.g., associated contact information), and relationships between identities (e.g., allowing login to an identity by using another linked, "federated" identity).

Globus Auth neither defines its own identity usernames nor verifies authentication (e.g., via passwords) with identities. Rather, it acts as an intermediary between external identity providers and clients and services that want to leverage identities issued by those providers. Legacy Globus usernames and passwords, issued prior to Globus Auth release, have been moved to a new "Globus ID" identity provider, which is completely independent of Globus Auth, and whose use is optional.

Globus Auth assigns each identity that it encounters an identifier (id): a UUID that is guaranteed to be unique among all Globus Auth identities, and that will never be reused. This identifier is what resource servers and clients should use as the canonical identifier for a Globus Auth identity. Associated with this identity id is an identity provider, a username given to the identity by the provider, and other provider-supplied information such as display name and contact email address.

The identity username is a (somewhat) human friendly string, such as an email address or InCommon eduPersonPrincipalName, which is guaranteed by Globus Auth to be unique at any point in time. However, because some (e.g., InCommon) identity providers reuse identity usernames (typically with a hiatus between uses), a given identity username may map to different identity ids over time. In such cases, Globus Auth uses a unique identifier provided by the identity provider (e.g., InCommon eduPersonTargetedID) to disambiguate, and ensure that at any given time there is a one-to-one mapping between an identity username and an identity id.

The following is an example of the information that might be associated with a Globus Auth identity:

  • username: rocky@wossamotta.edu

  • id: de305d54-75b4-431b-adb2-eb6b9e546014

  • identity_provider: wossamotta.edu

  • display_name: Rocket J. Squirrel

  • email: rocky@wossamotta.edu

If Globus Auth encounters an identity username that has been reused (i.e., same identity username, different provider supplied identifier), it will invalidate the old identity and create a new Globus Auth identity uniquely associated with that identity username. In rare exceptions, Globus will preserve the identity when it encounters reuse of an identity username. These exceptions are made only upon request from or in consultation with the identity provider. See the Identity Provider Data Change Log for a list of such occurrences.

3.1. Accounts

An identity can be used with Globus Auth to create a Globus account. A Globus account has a primary identity. An identity can be the primary identity of at most one Globus account. However, one identity may be linked to any number of other primary identities, and thus Globus accounts. Identity linking allows for authentication via one identity to imply login to a Globus account with a different primary identity (i.e., federated identity login).

Note
In the initial release of Globus Auth, an identity can be linked to only one primary identity, and thus Globus account. This restriction will be relaxed in a subsequent release.

The identity with id=id1 and username=rocky@wossamotta.edu is the primary identity for one account, and also listed as a linked identity for another, allowing that identity to be used to login to either account.

Primary identity:

Linked identity:

Primary identity:

A Globus account is not an identity itself. An account does not have its own name or identifier. Rather, a Globus account is identified by its primary identity. Similarly, profile information and other metadata is tied to identities, not to accounts. A Globus account is simply a set of identities comprising the primary identity and all identities linked to that primary identity.

Clients and services should grant access to resources on the basis of identities (specifically, identity ids) and their associated attributes (e.g., group memberships, organization affiliations), not accounts. Login to a Globus account, via its primary identity or one of its linked identities, implies login to the account’s primary identity and all identities linked to that account’s primary identity. In other words, login to a Globus account potentially grants access to all resources accessible via all identities linked to that Globus account’s primary identity.

Globus accounts are explicitly identified by their primary identity, and implicitly referred to by the OAuth2 access tokens issued by Globus Auth. An authorized client with an access token, or an authorized resource server that receives a client request using an access token, can request information from Globus Auth about the Globus account associated with the access token.

A Globus account can have up to 20 identities (primary and linked). This limit can be raised in the future if required.

3.2. Using Identities

Clients and resource servers should always use the Globus Auth-provided identity id when referring to an identity, for example in access control lists, and when referring to identities in a REST API. clients and resource servers can use the Globus Auth REST API to map any identity username to its (current) identity id, and request information about an identity id (e.g., identity username, display_name, provider, email) for human-friendly display of identity information.

For example, if a resource server wants to share resources with a user (via a client), it does so by using access control permissions based on one of the user’s identity ids. When a request is made to the resource server using an access token, the resource server authorizes the access by getting the set of identity ids (primary and linked) from the Globus account associated with the access token, and checking those identity ids against its access control permissions, to determine if any of those identity ids allows access.

Two Globus accounts, each with two identities, and two groups, each with different member identities from both accounts.

Primary identity:

Linked identity:

Primary identity:

Linked identity:

Group 1

Group 2

3.3. Effective Identity

Clients and resource servers should work with Globus accounts in terms of sets of identities, whenever possible. For example, when a resource server is determining the permissions associated with an access token, it should use the entire set of identities (primary and linked identity ids) of the account referred to by that access token.

However, it is often convenient for a client or resource server to be able to refer to the resource owner of the Globus account via a single identity, rather than the entire set. For example, a client may want to display an identity username for the logged in user, or a resource server may want to use a single identity when logging events associated with a request.

Certain clients and resources servers may even require an identity from a particular identity provider. For example, if an existing web application that uses a particular identity provider wants to integrate with Globus Auth, it would like to continue seeing its users in terms of that particular identity provider.

Globus Auth provides each client and resource server with an "effective identity". A client or resource server, during registration with Globus Auth, can request that users of that client or resource server must have an identity issued by a particular identity provider. When the client or resource server asks for the effective identity associated with the OAuth2 access token, it will be told the user’s identity from this identity provider, even if the user has a different primary identity. If the client or resource server does not specify an effective identity provider, Globus Auth will use the primary identity as the effective identity for that client or resource server.

3.4. Identity Usernames

Globus Auth usernames have the syntax user@provider. Note that the user portion of an identity username may be an email address. For example:

  1. identity username="user1@example.org" is user="user1" and provider="example.org"

  2. identity username="user1@example.org@provider.org" is user="user1@example.org" and provider="provider.org".

4. Identity Providers

Globus Auth supports an extensible set of identity providers, that employ a variety of identity naming and authentication approaches.

4.1. Registration with Globus Auth

Each identity provider supported by Globus Auth must register with Globus Auth in advance.

As described in the next section, each identity provider has one or more namespaces in which it can exclusively issue identity usernames, established at time of registration with Globus Auth.

Each identity provider must register a web browser based authentication protocol (e.g., OpenID Connect, SAML), and optionally a non-browser based protocol (e.g., LDAP, Kerberos, SAML ECP). If an identity provider registers only a browser based protocol, some Globus Auth OAuth2 grant types will not be possible with this identity provider (e.g., resource owner Password Credentials Grant), limiting the use of this provider’s identities to only browser-based applications.

When registering, an identity provider supplies various other information, such as display names and contact information.

4.2. Identity Provider Namespaces

Each identity provider has one or more namespaces in which it can exclusively issue identity usernames. A namespace is a domain name. For example, The University of Chicago’s identity provider is the only provider that can issue identity usernames with a provider domain of "@uchicago.edu" (e.g., johndoe@uchicago.edu). Note that subdomains are distinct namespaces from their parent domain. For example, @uchicago.edu and @ci.uchicago.edu are distinct namespaces, from potentially different providers.

Some identity providers use email addresses as their user names. For example, an identity provider restricted to issuing identities with names of "*@provider.org" may issue an identity with the name "johndoe@uchicago.edu@provider.org", but not "johndoe@uchicago.edu".

4.3. Identity and Account Provisioning

If a user authenticates to Globus Auth using an identity that’s never been used before with Globus Auth (i.e., it is neither a primary identity nor a linked identity), Globus Auth will automatically provision an appropriate Globus Auth identity on the fly. Globus Auth may prompt the user for missing identity information, such as a display name and email contact for this identity. Then, Globus Auth will prompt the user to choose between proceeding with the new identity as a primary identity or linking it to an existing primary identity.

4.4. Supported Identity Providers

4.4.1. Globus ID (Globus legacy usernames)

Prior to February 13, 2016, Globus required a Globus account to have a Globus username and password. This requirement no longer holds with Globus Auth. Rather, the old Globus usernames are now simply identities issued by the Globus ID identity provider, under the identity provider domain namespace of "@globusid.org". This identity provider has no special status with Globus Auth: it is just another identity provider. A Globus Auth account is not required to have a primary or linked identity from the Globus ID identity provider. The Globus ID identity provider remains available in order to smooth transition to this new Globus Auth model for previous users, and as an identity provider of convenience for Globus users going forward.

4.4.2. OpenID Connect

Globus Auth can act as a client to any standard OpenID Connect identity provider. The "sub" claim will uniquely map to a Globus Auth identity id. Globus Auth can be configured to get the identity username from the "sub" claim, the "preferred_username" claim, or any other non-standard claim (e.g., "eduPersonPrincipalName"). The Globus Auth identity username will be suffixed with namespace (e.g., DNS name) of the OpenID Connect server as the provider domain.

For example, if an OpenID Connect server running at "example.org" issues an ID token with a "sub" claim of "joeuser", and the Globus Auth identity username may be "joeuser@example.org".

4.4.3. Google

While Google uses OpenID Connect (with some extensions), it is handled as a special case by Globus Auth. The Google identity provider can issue identities for any email address, and by default, such identities will have a Globus Auth identity username of the email address (i.e., the value of the Google-issued OpenID Connect ID token "email" claim), with a "@accounts.google.com" provider domain. For example, "johndoe@uchicago.edu@accounts.google.com".

Globus Auth only accepts Google issued identities for email addresses that it has verified (i.e., Google-issued ID token has an "email_verified" claim with the value "true").

Globus Auth use the value of the Google-issued ID token "sub" claim, as a provider-specific unique identifier for the identity.

However, Google is also the exclusive issuer of identities for certain domains, such as @gmail.com and certain app domains registered by customers with Globus Auth. For these pre-defined domains, Globus Auth does not add "@accounts.google.com" to the identity username. For example, "joeuser@gmail.com".

4.4.4. SAML

Globus Auth uses the CILogon service as an intermediary with SAML identity providers.

4.4.5. Email Addresses

Globus Auth treats email addresses as a special type of identity, where the identity’s name is the email address (without an additional provider domain), and authentication of that name is done using the common email verification technique of sending an email to the address containing a secret that the user needs to copy-and-paste into an authentication/verification form.

Note that due to identity provider namespacing, as described above, Globus Auth will never allow an email address identity with a domain name issued by a registered identity provider. For example, if the University of Chicago identity provider owns the @uchicago.edu namespace, joeuser@uchicago.edu must be authenticated using the University of Chicago identity provider, and not simply via email address verification.

If a new identity provider is registered with an exclusive provider domain for which email address identities were previously issued, then Globus Auth will automatically change the provider of such identities to the new identity provider. For example, if a user has authenticated and linked the rocky@wossamotta.edu email address identity to their primary identity, and later an identity provider for @wossamotta.edu registers with Globus Auth, then Globus Auth will subsequently require authentication of rocky@wossamotta.edu via that identity provider, instead of email-based authentication.

5. Clients

To clients, Globus Auth is a standard OAuth2 authorization server, and OpenID Connect identity provider. After performing a normal OAuth2 interaction, a client can:

  1. Use the OpenID Connect ID token that was issued by Globus Auth to verify the identity of the user associated with the access token.

  2. Use the access token to request additional information related to the access token from Globus Auth via its REST API.

  3. Use the access token to request access to resources provided by various other resource servers, subject to authorized scopes.

5.1. Obtaining Authorization

The Globus Auth API includes the standard OAuth2 interfaces:

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

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

  • Section 4.3, resource owner Password Credentials Grant: For obtaining an access token for a non-browser-based client (e.g., command line, mobile, or desktop application), using a username and password.

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

5.2. Verifying Identity

When an end-user logs into an account, using either the primary identity or a linked identity, authorized clients will, by default, verify the user’s identity by using the account’s primary identity. Globus Auth will issue an OpenID Connect ID token based on the primary identity, and the identity specified in the /v2/token/introspect resource’s "sub" field will be the primary identity.

However, some clients require an effective identity; an identity that has been issued by a particular identity provider. A user may have an account with a linked identity from that provider, but with a primary identity not issued by that provider. Before issuing a token to such a client, Globus Auth will check the user’s account to ensure that it includes a linked identity that was issued by the identity provider required by the client. Then Globus Auth will use this as the effective identity specified in the OpenID Connect ID token.

A client that requires identities from a particular provider must register with Globus Auth, and specify the provider at time of registration.

Even if a client requires a particular identity, it can still use the Globus Auth API to discover the primary identity, and other linked identities, subject to authorization.

6. Resource Servers

Globus Auth can be used as an authorization server for third party resource servers, making it easy for resource servers to support sophisticated OAuth2 and OpenID Connect functionality, and to leverage other resource servers that use Globus Auth.

6.1. Registration with Globus Auth

Each resource server that wants to leverage Globus Auth as its authorization server must register with Globus Auth in advance.

During registration, Globus Auth will establish a client identifier and client secret for the resource server, which will be used to allow the resource server to authenticate to Globus Auth in order to validate and get information about an access token.

A resource server, during registration, can request that users of the resource server must have an identity issued by a particular identity provider, so that when the resource server asks for the effective identity associated with the OAuth2 access token, it will be told the user’s identity from this provider, even if the user has a different primary identity. This allows resource servers to adopt Globus Auth in a limited, and incremental fashion, by retaining existing identity support.

A resource server, during registration, defines a set of "scopes" (see OAuth2 access token Scope) for itself, each of which corresponds to a subset of that resource server’s functionality. Each scope for each resource server has a Globus Auth-issued URN that is unique across all scopes on all resource servers, and is never reused. clients request an access token that authorizes use of a specific set of scopes (and thus resource servers). While resource servers may choose to offer just a single scope that grants full access to the resource server, more limited scopes allow for resource servers to protect resources better by offering more limited rights.

A resource server, during registration, can define a set of scopes that it will use as a client to other resource servers. See the dependent access tokens section below for more details.

A resource server, during registration, establishes a resource server name, which is a DNS name that uniquely identifies this resource server. This resource server name is used as part of the scope URNs for this resource server.

6.2. Typical Resource Server Interactions

A resource server that leverages the Globus Auth authorization server will typically interact with clients and Globus Auth as follows:

  1. A client makes an HTTPS request to the resource server with an Authorization: Bearer header containing an access token ("request access token").

  2. The resource server calls the Globus Auth API (POST /v2/oauth2/token/introspect), authorized by the resource server’s client identifier and client secret, to validate the request access token, and obtain additional information related to that request access token (scopes, effective identity, identities set, etc.). If the request access token is not valid, or is not intended for use with this resource server, Globus Auth will return an error.

  3. The resource server verifies that the request from its client conforms to the scopes associated with the request access token.

  4. The resource server verifies the effective identity of the resource owner (typically an end-user), on whose behalf the client is acting. The resource server may use this identity as its local account identifier for this user.

  5. The resource server uses the set of identities associated with the account referred to by the request access token to determine what the request is allowed to do. For example, if the request is to access a resource that is shared with particular identities, the resource server should compare all of the account’s identities (primary and linked identity ids) with the resource access control permissions to determine if the request should be granted.

  6. The resource server may need to act as a client to other (dependent) resource servers, in order to fulfill the request. (See the dependent access tokens section below for more details.)

    1. The resource server uses the Globus Auth Dependent Token Grant API (POST /v2/oauth2/token) to get dependent access tokens for use with downstream resource servers, based on the request access token it received from the client.

    2. The resource server uses a dependent access token to make a request to a dependent resource server. For example, the resource server may call the Globus Groups API to find out what groups the identities of the account are members of, and call the Globus Transfer API to perform a file transfer.

  7. The resource server responds to its client with an appropriate response.

6.3. Dependent access tokens

The OAuth2 specification defines how to obtain and use access tokens for interactions between a client and a resource server, within a specified scope. However, what if a resource server (RS1) receives a request from a client (C1) using a request access token (AT1), and RS1 wants to act as a client (C2) to another resource server (RS2), in order to help fulfill the request? What access token should be used in the request from C2 to RS2? The OAuth2 specification is silent on such a scenario.

This scenario arises frequently within the Globus ecosystem of services that Globus Auth is designed to support. For example, a user of a web application client wants to submit a request to workflow management service to run a workflow. The workflow resource server, in turn, wants to submit a request to the Globus data sharing service to access data from a shared endpoint for use in the workflow. In order to service the request, the Globus data sharing resource server must, in turn, make a request to the Globus groups service to find out what groups the user is a member of, based on that user’s linked identities, in order to determine what shared endpoint permissions the user has. In this scenario we call the Globus groups service a dependent resource server to the Globus data sharing resource server, and the Globus data sharing resource server is a dependent resource server to the workflow service.

The Globus Auth authorization server provides an API for its resource servers, which allows a resource server to request new "dependent access tokens", based on the access token it received from its client. These dependent access tokens can be used to access dependent resource server scopes. Via the Dependent Token Grant API (POST /v2/oauth2/token), Globus Auth supports access token delegation for such service invocation chains.

6.4. Performance

A resource server may need to respond to hundreds or thousands of requests per second. As a resource server scales, unnecessary calls to Globus Auth can have a significant impact on response times degrading performance. To prevent this, resource servers can cache the responses for token introspection and dependent tokens.

The Globus Auth Dependent Token Grant is a much more costly request compared to token introspection. Resource server dependencies may also require additional resource servers, with each nested dependency doing an additional Dependent Token Grant. Failure to reuse these tokens can harm performance on both the resource server doing the grant and any downstream resource servers it uses. Therefore, tokens should always be saved for repeated use. The dependent_tokens_cache_id from the /v2/oauth2/token/introspect call can be used to ensure the dependent tokens have not changed since the last time the call was made.

Token introspection also adds overhead to a resource server’s response time, and can be cached to increase performance. Doing so does have security implications. Long cache times can make a resource server slow to respond to token revocation, while short cache times result in less performance gains. A 30 second cache timeout is a good starting point, which can be varied depending on the situation.

Resource Server developers may be interested in Globus Action Provider Tools, a general implementation of a Globus Resource Server which is tailored for use in Automate Flows.

7. References