Globus Auth Requirements Errors (GAREs)

Globus Auth Requirements Error (GARE) is a response format that conveys to a client any modifications to a user’s authorization that will be required in order to complete a particular request.

Response Format

The Globus Auth Requirements Error response format requires (and further, only even considers) two fields at the top level: code and authorization_parameters. code is a string that identifies the type of error (which may be used by the client to adopt handling based on the genre of additional authorization needed, e.g., "ConsentRequired").

Conceptually, these fields serve the following purpose:

  • code indicates the "why": Why didn’t the user’s state satisfy the requirements of the requested operation?

  • authorization_parameters indicates the "how": How must we modify the user’s state in order to proceed successfully?

In practice, only authorization_parameters should be necessary in order to modify the user’s state properly, but the code provides context that clients may use in order to facilitate good user and developer experiences.

Code

There are currently two supported values for the code field:

  • ConsentRequired indicates that the user must consent to additional scopes in order to authorize the resource server(s) to complete the requested action.

  • AuthorizationRequired indicates that this is a Globus Auth Requirements Error that is not more specifically described by any other code.

Other values may be returned in the code field at the responder’s discretion, but using a predefined value when appropriate ensures that your service will be well supported by downstream clients.

Authorization Parameters

authorization_parameters is an object that may contain one or more of the following fields:

  • session_message: <string>

  • session_required_identities: <array[string]>

  • session_required_policies: <array[string]>

  • session_required_single_domain: <array[string]>

  • session_required_mfa: <boolean>

  • required_scopes: <array[string]>

  • prompt: <string>

An intent of these fields is to allow straightforward conversion to the arguments accepted by the /v2/oauth2/authorize Globus Auth authorization API endpoint, allowing a client (whether your own, or one downstream of your service) to direct a user to modify their state such that a requested operation may be completed. Documentation of this API endpoint is available in the Globus Auth API Reference.

If no fields are included in the authorization_parameters object (i.e., authorization_parameters: {}), clients should interpret this to mean that any authentication is required.

Other fields

Additional fields are permitted in the Globus Auth Requirements Error response format but must not be necessary in order for a client to successfully handle a Globus Auth Requirements Error. If a response contains fields other than the canonical fields above, a client may safely ignore them.

Because of this, existing fields may be retained in responses for backward compatibility (so long as they don’t collide with the above key names), allowing clients to gradually migrate to the GARE format.

Additional fields may be introduced over time to accommodate evolving requirements.

Implementations

GARE support is provided in the Globus Python SDK via the gare subpackage. Helper functions (e.g., to_gare(…​)) are provided to identify and/or convert applicable service responses and GlobusAPIError exceptions to GAREs. Additional details are available in the Globus Python SDK docs.

GARE support is provided in the Globus JavaScript SDK via the errors namespace. See the Globus JavaScript SDK docs for additional details.