Class AuthorizationManager

Provides management of Globus authorization context for your application.

Handles the OAuth protcol flow (via PKCE)
Token lifecycle management
Common errors (e.g., ConsentRequired, authorization_requirements)

Once you configure your instance, you can determine the authenticated state using manager.authenticated.

To prompt a user to authenticate, call manager.login() on user interaction – this will initiate the OAuth protocol flow with your configured client and scopes, resulting in an initial redirect to Globus Auth.

Once the user authenticates with Globus Auth, they will be redirected to your application using the configured redirect URL. On this URL, you will need to call manager.handleCodeRedirect (using a manager instance configured in the same manner that initiated the manager.login() call) to complete the PKCE flow, exchanging the provided code for a valid token, or tokens.

All tokens managed by the AuthorizationManager instance can be found on manager.token.

Registering your Globus Application

The AuthorizationManager expects your Globus Application to be registered as an OAuth public client. In this Globus Web Application, this option is referenced as "Register a thick client or script that will be installed and run by users on their devices".

Example: Creating an AuthorizationManager instance.

import { authorization } from "globus/sdk";

const manager = authorization.create({
 // Your registered Globus Application client ID.
 client: '...',
 // The redirect URL for your application; Where you will call `manager.handleCodeRedirect()`
 redirect: 'https://example.com/callback',
 // Known scopes required by your application.
 scopes: 'urn:globus:auth:scope:transfer.api.globus.org:all',
});

Usage with Service Methods

Once you have an instance of an AuthorizationManager, it can be passed to any service method as ServiceMethodOptions.manager or SDKOptions.manager option. The service method will determine if a token is required to make the request and will use the AuthorizationManager to retrieve the token.

Example: Using the AuthorizationManager with a service method.

import { transfer } from "globus/sdk";
const manager = authorization.create({ ... });
const result = await (
 await globus.transfer.endpointSearch({
   query: { filter_fulltext: "Globus"},
   manager
 })
).json();

Constructors

constructor

new AuthorizationManager(
configuration: AuthorizationManagerConfiguration,
): AuthorizationManager
Parameters
- configuration: AuthorizationManagerConfiguration
Returns AuthorizationManager
- Defined in src/core/authorization/AuthorizationManager.ts:201

Properties

configuration

configuration: AuthorizationManagerConfiguration

events

events: {
    authenticated: Event<
        "authenticated",
        { isAuthenticated: boolean; token?: TokenResponse },
    >;
    revoke: Event<"revoke", unknown>;
} = ...

Type Declaration

authenticated: Event<"authenticated", { isAuthenticated: boolean; token?: TokenResponse }>
Emitted when the authenticated state changes. AuthorizationManager.events#authenticated
revoke: Event<"revoke", unknown>
Emitted when the user revokes their authentication. AuthorizationManager.events#revoke

storage

storage: Storage

The storage system used by the AuthorizationManager.

Implements

Storage

tokens

tokens: TokenManager

Accessors

authenticated

get authenticated(): boolean
The AuthorizationManager is considered authenticated if it has a valid Globus Auth token. It does not necessarily mean that it has a valid token for a specific resource server.

Returns boolean
- Defined in src/core/authorization/AuthorizationManager.ts:155
set authenticated(value: boolean): void
Set the authenticated state and emit the authenticated event.
Parameters
- value: boolean
Returns void
- Defined in src/core/authorization/AuthorizationManager.ts:162

storageKeyPrefix

get storageKeyPrefix(): string
Returns string
- Defined in src/core/authorization/AuthorizationManager.ts:246

user

get user(): JwtUserInfo | null
The user information decoded from the id_token (JWT) of the current Globus Auth token. This method can be used instead of auth.oauth2.userinfo to get the user information without an additional request.

IMPORTANT: The id_token can only be processed if the openid scope is requested during the authorization process.

Additionally, the profile and email scopes are required to get the full user information.

Returns JwtUserInfo | null
See
https://docs.globus.org/api/auth/reference/#oidc_userinfo_endpoint
- Defined in src/core/authorization/AuthorizationManager.ts:260

Methods

addTokenResponse

addTokenResponse(token: Token | TokenResponse): void
Add a Globus Auth token response to storage, if other_tokens are present they are also added. This method is mostly used internally by the AuthorizationManager, but can be used by downstream consumers to add tokens to storage if necessary.
Parameters
- token: Token | TokenResponse
Returns void
- Defined in src/core/authorization/AuthorizationManager.ts:573

getGlobusAuthToken

getGlobusAuthToken(): any
Retrieve the Globus Auth token managed by the instance.

Returns any
- Defined in src/core/authorization/AuthorizationManager.ts:319

handleAuthorizationRequirementsError

handleAuthorizationRequirementsError(
response: AuthorizationRequirementsError,
options?: { additionalParams?: { [key: string]: string } },
): Promise<void>
Process a well-formed Authorization Requirements error response from a Globus service and redirect the user to the Globus Auth login page with the necessary parameters.
Parameters
- response: AuthorizationRequirementsError
- Optionaloptions: { additionalParams?: { [key: string]: string } }
Returns Promise<void>
- Defined in src/core/authorization/AuthorizationManager.ts:537

handleCodeRedirect

handleCodeRedirect(
    options?: {
        additionalParams?: { [key: string]: string };
        includeConsentedScopes?: boolean;
        shouldReplace?: boolean;
    },
): Promise<any>
This method will attempt to complete the PKCE protocol flow.
Parameters
- options: {
      additionalParams?: { [key: string]: string };
      includeConsentedScopes?: boolean;
      shouldReplace?: boolean;
  } = ...
Returns Promise<any>
- Defined in src/core/authorization/AuthorizationManager.ts:445

handleConsentRequiredError

handleConsentRequiredError(
response: ConsentRequiredError,
options?: { additionalParams?: { [key: string]: string } },
): Promise<void>
Process a well-formed ConsentRequired error response from a Globus service and redirect the user to the Globus Auth login page with the necessary parameters.
Parameters
- response: ConsentRequiredError
- Optionaloptions: { additionalParams?: { [key: string]: string } }
Returns Promise<void>
- Defined in src/core/authorization/AuthorizationManager.ts:555

handleErrorResponse

handleErrorResponse(
    response: Record<string, unknown>,
    options?:
        | true
        | { additionalParams?: { [key: string]: string }; execute?: true },
): Promise<void>
Handle an error response from a Globus service in the context of this AuthorizationManager. This method will introspect the response and attempt to handle any errors that should result in some additional Globus Auth interaction.
Parameters
- response: Record<string, unknown>
  The error response from a Globus service.
- Optionaloptions: true | { additionalParams?: { [key: string]: string }; execute?: true }
  Options for handling the error response. If a boolean is provided, this will be treated as the options.execute value.
  - true
  - { additionalParams?: { [key: string]: string }; execute?: true }
    OptionaladditionalParams?: { [key: string]: string }
    Additional query parameters to be included with the transport generated URL.
    
    Optionalexecute?: true
    Whether to execute the handler immediately.
Returns Promise<void>
- Defined in src/core/authorization/AuthorizationManager.ts:476
handleErrorResponse(
    response: Record<string, unknown>,
    options?:
        | false
        | { additionalParams?: { [key: string]: string }; execute?: false },
): Promise<() => Promise<void>>
Handle an error response from a Globus service in the context of this AuthorizationManager. This method will introspect the response and attempt to handle any errors that should result in some additional Globus Auth interaction.
Parameters
- response: Record<string, unknown>
  The error response from a Globus service.
- Optionaloptions: false | { additionalParams?: { [key: string]: string }; execute?: false }
  Options for handling the error response. If a boolean is provided, this will be treated as the options.execute value.
  - false
  - { additionalParams?: { [key: string]: string }; execute?: false }
    OptionaladditionalParams?: { [key: string]: string }
    Additional query parameters to be included with the transport generated URL.
    
    Optionalexecute?: false
    Whether to execute the handler immediately.
Returns Promise<() => Promise<void>>
- Defined in src/core/authorization/AuthorizationManager.ts:480

hasGlobusAuthToken

hasGlobusAuthToken(): boolean
Whether or not the instance has a reference to a Globus Auth token.

Returns boolean
- Defined in src/core/authorization/AuthorizationManager.ts:312

login(options?: { additionalParams: {} }): Promise<unknown>
Initiate the login process by redirecting to the Globus Auth login page.

IMPORTANT: This method will reset the instance state before initiating the login process, including clearing all tokens from storage. If you need to maintain the current state, use the AuthorizationManager.prompt() method.
Parameters
- options: { additionalParams: {} } = ...
Returns Promise<unknown>
Example
```
Passing parameters to the transport.
const result = await manager.login({
  additionalParams: {
    redirect_uri: '/oauth/redirect-uri-runtime-override',
  },
});
```
- Defined in src/core/authorization/AuthorizationManager.ts:408

prompt

prompt(options?: Partial<TransportOptions>): Promise<unknown>
Prompt the user to authenticate with Globus Auth.
Parameters
- Optionaloptions: Partial<TransportOptions>
Returns Promise<unknown>
Example
```
Passing parameters to the transport.
const result = await manager.prompt({
  additionalParams: {
    redirect_uri: '/oauth/redirect-uri-runtime-override',
  },
});
```
- Defined in src/core/authorization/AuthorizationManager.ts:432

refreshToken

refreshToken(token: TokenWithRefresh): Promise<TokenResponse | null>
Use the refresh_token attribute of a token to obtain a new access token.
Parameters
- token: TokenWithRefresh
  The well-formed token with a refresh_token attribute.
Returns Promise<TokenResponse | null>
- Defined in src/core/authorization/AuthorizationManager.ts:287

refreshTokens

refreshTokens(): Promise<PromiseSettledResult<TokenResponse | null>[]>
Attempt to refresh all of the tokens managed by the instance. This method will only attempt to refresh tokens that have a refresh_token attribute.

Returns Promise<PromiseSettledResult<TokenResponse | null>[]>
- Defined in src/core/authorization/AuthorizationManager.ts:269

reset

reset(): void
Reset the authenticated state and clear all tokens from storage. This method does not emit the revoke event. If you need to emit the revoke event, use the AuthorizationManager.revoke method.

Returns void
- Defined in src/core/authorization/AuthorizationManager.ts:344

revoke

revoke(): Promise<void>
Call AuthroizationManager.reset, revoke all of the available tokns, and emit the revoke event.

Returns Promise<void>
Emits
AuthorizationManager.events#revoke

See
AuthorizationManager.reset
- Defined in src/core/authorization/AuthorizationManager.ts:583

Class AuthorizationManager

Registering your Globus Application

Example: Creating an AuthorizationManager instance.

Usage with Service Methods

Example: Using the AuthorizationManager with a service method.

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns AuthorizationManager

Properties

configuration

events

Type Declaration

authenticated: Event<"authenticated", { isAuthenticated: boolean; token?: TokenResponse }>

revoke: Event<"revoke", unknown>

storage

Implements

tokens

Accessors

authenticated

Returns boolean

Parameters

Returns void

storageKeyPrefix

Returns string

user

Returns JwtUserInfo | null

See

Methods

addTokenResponse

Parameters

Returns void

getGlobusAuthToken

Returns any

handleAuthorizationRequirementsError

Parameters

Returns Promise<void>

handleCodeRedirect

Parameters

Returns Promise<any>

handleConsentRequiredError

Parameters

Returns Promise<void>

handleErrorResponse

Parameters

OptionaladditionalParams?: { [key: string]: string }

Optionalexecute?: true

Returns Promise<void>

Parameters

OptionaladditionalParams?: { [key: string]: string }

Optionalexecute?: false

Returns Promise<() => Promise<void>>

hasGlobusAuthToken

Returns boolean

login

Parameters

Returns Promise<unknown>

Example

prompt

Parameters

Returns Promise<unknown>

Example

refreshToken

Parameters

Returns Promise<TokenResponse | null>

refreshTokens

Returns Promise<PromiseSettledResult<TokenResponse | null>[]>

reset

Returns void

revoke

Returns Promise<void>

Emits

See

Settings

On This Page

`Optional`additionalParams?: { [key: string]: string }

`Optional`execute?: true

`Optional`additionalParams?: { [key: string]: string }

`Optional`execute?: false