Globus Auth User Guide

OAuth 2.0 has become the industry standard for authorization on the web, and for good reason. It provides a secure way for applications to access resources on behalf of users without ever seeing their credentials. Globus Auth implements the OAuth 2.0 specification with some enhancements for handling multiple identities for a user, and service to service call chains. Globus Auth allows users to grant specific, limited permissions to applications. Users maintain control over what each application can do on their behalf, and they can revoke those permissions at any time.

Globus Auth provides a complete OAuth 2.0 service with:

While OAuth 2.0 handles authorization (what you’re allowed to do), OpenID Connect (OIDC) adds a standardized layer for authentication (who you are). This distinction is important: just because an application knows what permissions you’ve granted doesn’t necessarily mean it knows your identity or how you authenticated.

Globus Auth implements OIDC 1.0 to provide rich identity information:

Globus Auth integrates with a diverse ecosystem of identity providers to meet researchers where they are:

InCommon/eduGAIN - This is the primary federation for academic and research institutions. Through CILogon, which translates between SAML (the protocol many institutional enterprise IdPs use) and OIDC (the standard that Globus Auth uses), thousands of institutions worldwide can authenticate their users with Globus Auth. If your institution is part of InCommon or the global eduGAIN federation, your users can log in with their campus credentials.

Direct Institutional IdPs - 50+ research facilities have established direct integration with Globus Auth instead of participating in InCommon. These organizations provide OIDC authentication interfaces rather than SAML, which is required by InCommon.

Identity Providers of Last Resort- Recognizing that not everyone has access to an institutional identity, Globus Auth also supports a few widely-used identity providers:

This multi-provider approach ensures that virtually anyone who needs to participate in scientific collaboration can authenticate in a way that makes sense for them.

Globus Auth enables institutions to integrate their own identity providers with specific resources they deploy. These providers use the OpenID Connect (OIDC) protocol, but are not permitted for logging into Globus services themselves.

For example, consider a department that wishes to secure access to a specialized resource. The department may operate an identity provider linked to its own authentication system—such as LDAP—and manage an OIDC server for handling user authentication. By registering this OIDC server with Globus Auth, the department ensures that users must authenticate with its identity provider to access departmental resources.

In practice, a user first signs in to Globus using one of the more than 2,000 supported identity providers. However, when the user tries to access a department-specific resource, they are prompted to authenticate again—this time using the department’s designated identity provider. This approach allows institutions to retain control over access to their own resources, while Globus continues to manage service-level authentication separately.

Application registration establishes your application’s identity in the Globus Auth ecosystem. This is more than just administrative bookkeeping—it’s how Globus Auth knows which authentication flows your application is allowed to use and what security controls should apply. Additionally, the application’s identity can be granted permissions within the Globus ecosystem, for cases where the application can act as itself.

When you register, you’ll configure:

In some cases, the registration process also involves declaring your redirect URIs—the URLs where Globus Auth should send users after they’ve completed authentication. This is a crucial security control: by pre-registering these URIs, you prevent attackers from intercepting authentication responses by tricking the system into sending tokens to malicious sites.

App Registration: https://docs.globus.org/api/auth/developer-guide/#register-app

Not all applications are created equal from a security perspective. A web application running on a server you control can keep secrets secure in ways that a browser-based application or mobile app simply cannot. OAuth 2.0 recognizes these differences and provides different authentication flows optimized for each scenario.

The table show two scenarios for each type of application: a) where the application has to act as itself (application authentication), and (b) where the application acts on behalf of the user (user authentication)

The moment when a user authenticates is critical, and the application obtains the user token from Globus Auth and uses it to access the API. Understanding the user authentication flow helps you design better user experiences and handle edge cases gracefully. The complete user authentication flow unfolds like a carefully choreographed dance between your application, the user’s browser, and Globus Auth, shown in Figure 1.

Figure 1. A person logs into a web application that requires a token for "MY_API." The person selects her home institution for authentication and grants her consent for the application to use MY_API on her behalf. The web application receives the person’s identity information and an access token for MY_API.

This flow might seem elaborate, but each step serves a purpose. The indirection through Globus Auth ensures that your application never handles user credentials directly. The consent step gives users control over their data. The session and policy checks ensure that security requirements are consistently enforced.

Token Management: https://docs.globus.org/api/auth/developer-guide/#obtaining-authorization

While much of OAuth focuses on accessing resources on behalf of users, applications sometimes need to act as themselves. Consider a background job that processes data overnight, an administrative tool that manages application-level resources, or a service that aggregates information from multiple users' data.

For these scenarios, applications with private storage (confidential clients) can use the OAuth client credentials grant. This is conceptually simpler than user authentication because there’s no user involvement—the application authenticates directly with Globus Auth using its client ID and secret. The identity of the application in the Globus ecosystem is clientid@clients.auth.globus.org .

When obtaining application tokens:

This distinction between acting on behalf of users and acting as yourself is fundamental to building secure multi-tenant applications. Application tokens are perfect for operations that are conceptually owned by the application itself, while user tokens should be used for any operation that involves user-specific data or permissions.

Client Credentials: https://docs.globus.org/api/auth/reference/#client_credentials_grant

Before your API can use Globus Auth, you need to introduce it to the system through registration. This is similar to getting a business license—it establishes your API’s identity in the ecosystem and allows you to configure how it will interact with users and other services. You’ll use the Globus web application (www.globus.org) to perform this registration.

During registration, you’ll obtain:

The authentication policies you can configure include:

The power of registering these policies with Globus Auth is that the system both facilitates users meeting these from the client application, and enforces them automatically. You don’t need to write code to check whether a user authenticated recently enough or used MFA—Globus Auth handles that before the request even reaches your API.

When a request arrives at your API, it will include an access token in the HTTP header. This token is a compact, cryptographically signed package of information, but you shouldn’t blindly trust it. Token validation is where you ensure that the request is legitimate.

The validation process follows a clear pattern:

The claims you’ll check include:

Globus Auth does more than just return these claims—it also validates the token against any authentication policies you registered. If your policy requires MFA and the user’s session didn’t include MFA, Globus Auth will indicate this in the introspection response, allowing you to deny access appropriately.

Since an API is likely to receive multiple calls with the same access token, it is a good practice to cache the introspection result for a short period of time (1-5 minutes). But don’t hold on to a result too long or the API may miss state changes, such as a logout or a consent revocation.

Token Introspection Reference:
https://docs.globus.org/api/auth/reference/#token-introspect

With a valid token in hand, you now need to make authorization decisions based on who the user is and how they authenticated. The token provides rich context beyond just a user ID.

The key information you can extract includes:

This contextual information enables sophisticated authorization logic. For example, you might allow users from any institution to read data, but restrict job submission to users who have authenticated with MFA from specific facilities within the last 30 minutes. All of this information is readily available in the token without requiring additional database lookups or API calls.

Modern APIs rarely work in isolation. Your API might need to store results in a cloud storage service, send notifications through a messaging API, or submit jobs to a compute cluster. Each of these dependent services has its own security requirements, and naively passing your user’s token around creates security problems.

This is where dependent tokens shine. When you registered your API, you declared which other services you need to access. When your API receives a valid token, it can request dependent tokens specifically for those services.

The flow works like this:

This pattern might seem complex, but it solves a critical problem in distributed systems: how to maintain the chain of authorization as requests flow through multiple services. The alternative—having your API use its own credentials to access dependent services—would lose the user context entirely and couldn’t enforce user-specific permissions.

In an ideal world, each person would have exactly one digital identity that worked everywhere. Reality is far messier, especially in research where a single scientist might have credentials at their home university, one or more national laboratories, their funding agency, and various other institutions. Traditionally, systems force users to pick one identity and stick with it, which inevitably causes problems when they need to access resources associated with a different identity.

Identity linking solves this by allowing users to explicitly connect their various identities into a cohesive set. Think of it as a credential wallet where all your different ID cards are kept together, and you can present whichever one is appropriate for the situation.

How identity linking works in practice:

Consider a common scenario: A researcher at the University of Chicago collaborates with colleagues at a national laboratory. The data they’re working with lives at the lab and is protected by access controls that only recognize lab identities. Traditionally, the researcher would need to obtain a separate account at the lab, log in separately, and somehow manage permissions across two disconnected systems. With identity linking, the researcher links their university identity with their lab identity. When they authenticate with their university credentials, applications can see that they also have a lab identity and grant appropriate access to lab resources.

This becomes even more powerful when you consider that the researcher might publish data on a repository that knows them by their ORCID, submit compute jobs to a facility that knows them by their ACCESS ID, and collaborate through a portal that knows them by their GitHub account. Rather than maintaining separate workflows for each context, identity linking creates a unified experience.

Use case example: A data transfer service might show that source data at the lab requires authentication with a lab identity, while the destination repository accepts university credentials. The service can intelligently guide the user: "You’re authenticated with your University of Chicago ID, but this data source requires your lab identity. Click here to authenticate with your lab credentials, and we’ll link them together for future use."

Identity Management: https://docs.globus.org/api/auth/reference/#get_identities_resource

Globus provides built-in solutions for some of the most common policy requirements. This enables application developers to configure the policy requirement in Globus and ask Globus to enforce it, rather than writing enforcement code themselves. Applications may configure identity preferences, informing Globus which identities the application prefers Globus to return to the application. Applications may also configure authentication policies, adding requirements for the authentication such as MFA and allowed/prohibited identity domains.

Identity Preferences:

If a required domain is configured, authentication will only succeed if the person has an identity in the required domain. Individuals without accounts in that domain will be unable to login to the application.

Authentication Policies:

Policy Configuration: https://docs.globus.org/api/auth/developer-guide/#authentication-policies

To support cases where applications or APIs need to make customized policy decisions, Globus provides the context (details) of the authentication session. The token introspection result includes the following attributes for each authentication in the session. (Sessions may include multiple authentication events.)

Enable enforcement of custom policies:

Figure 2. Example authentication context showing a multi-factor authentication with University of Chicago and a later authentication (without MFA information) with Argonne LCF.

Session Info Reference: https://docs.globus.org/api/auth/sessions/

Globus currently has a feature in its preview environment that allows assertions from other systems to be embedded in Globus tokens. An application or API may be configured to require an attribute from a specific service, either via a scope request or client registration. When a login flow is performed, Globus will complete the authentication and then guide the person to the other service’s login interface. Globus will embed the resulting assertions or tokens into the identity data returned to the application or API.

Examples:

Figure 3. After logging in using Globus and the Argonne Identity Provider, Globus obtains additional attributes from the ALCF OIDC Server and embeds them in the end user’s token so they may be used for policy enforcement by the ALCF Facility API.

OAuth and OIDC define several token types, each serving a different purpose:

Access Tokens - These are the workhorses of the OAuth system. An access token is a credential that proves a user (or application) has been authorized to access specific resources. They’re typically short-lived—often expiring after an hour or less—which limits the damage if one is compromised. Access tokens should be treated like cash: whoever possesses one can use it, so protect them carefully. Unlike some OAuth implementations that use opaque tokens (random strings with no inherent meaning), Globus Auth uses JWTs for access tokens, which means they contain information that can be inspected by APIs without needing to call back to Globus Auth for every validation.

Refresh Tokens - Scientific workflows often run for extended periods—hours, days, or even weeks. Access tokens expire relatively quickly for security reasons, but requiring users to re-authenticate every hour would be disruptive. Refresh tokens solve this problem. A refresh token is a long-lived credential that can be used to obtain new access tokens without requiring user interaction. Think of an access token as a day pass to a facility, while a refresh token is a membership that lets you get new day passes whenever you need them. Refresh tokens are more powerful than access tokens, so they require more protection. They should be stored securely and never exposed in browser-based applications.

ID Tokens - This is where OpenID Connect extends OAuth 2.0. While access tokens prove authorization, ID tokens prove identity. An ID token is a signed assertion from Globus Auth about who the user is, when they authenticated, and how they authenticated. Applications use ID tokens to establish user sessions, not to access APIs. The distinction matters: you wouldn’t present an ID token to an API (it wouldn’t accept it), and you wouldn’t use an access token to determine a user’s identity (it’s not designed for that purpose, even though it contains identity information).

Tokens have a natural lifecycle that your application needs to manage:

Obtaining tokens - This happens through the various grant flows we’ve discussed: authorization code for user authentication, client credentials for application authentication, refresh token for renewing expired tokens, and dependent token grant for API-to-API calls. Each grant flow returns a specific set of tokens appropriate for the use case.

Using tokens - Access tokens are included in API requests, typically in the Authorization header as "Bearer". The word "Bearer" signifies that whoever possesses the token is authorized to use it—there’s no additional proof of identity required. This is why tokens must be kept confidential.

Refreshing tokens - When an access token expires, you don’t need to interrupt the user and ask them to log in again. Instead, you use the refresh token to request a new access token. This is a simple API call to Globus Auth that exchanges the refresh token for a new access token (and usually a new refresh token as well, though some implementations reuse the refresh token). This process is transparent to the user—they continue working uninterrupted while your application handles the token refresh in the background.

Revoking tokens - When a user logs out, or when your application no longer needs access, tokens should be explicitly revoked. This is more than just deleting them from your local storage—you should call Globus Auth’s token revocation endpoint to invalidate them server-side. This ensures that even if an access token was somehow copied or leaked, it can’t be used after logout. Token revocation also provides a way to respond to security incidents: if you discover that tokens might have been compromised, you can revoke them immediately without waiting for them to naturally expire.

The lifecycle management becomes particularly important in long-running applications. A data transfer job might run for hours, periodically needing to refresh its access token to maintain access to source and destination storage. A compute job might run for days, requiring careful token management to ensure it can write results when it finally completes. Proper lifecycle management—obtaining tokens only when needed, refreshing them before they expire, and revoking them when done—is the mark of a well-designed application.

Token Reference: https://docs.globus.org/api/auth/reference/#tokens