Globus Auth Requirements Errors (GAREs)

‘Globus Auth Requirements Error’ is a response format that conveys to a client any modifications to a session (i.e., “boosting”) that will be required to complete a particular request.

The globus_sdk.gare module provides a number of tools to make it easier to identify and handle these errors when they occur.

GARE

The GARE class provides a model for working with Globus Auth Requirements Error responses.

Services in the Globus ecosystem may need to communicate authorization requirements to their consumers. For example, a service may need to instruct clients to have the user consent to an additional scope, "foo". In such a case, GARE can provide serialization into the well-known Globus Auth Requirements Error format:

from globus_sdk.gare import GARE

error_doc = GARE(
    code="ConsentRequired",
    authorization_parameters=GlobusAuthorizationParameters(
        required_scopes=["foo"],
        session_message="Missing required 'foo' consent",
    ),
)

# Render a strict dictionary
error.to_dict()

If non-canonical fields are needed, the extra argument can be used to supply a dictionary of additional fields to include. Non-canonical fields present in the provided dictionary when calling from_dict() are stored similarly. You can include these fields in the rendered output dictionary by specifying include_extra=True when calling to_dict().

from globus_sdk.gare import GARE

error = GARE(
    code="ConsentRequired",
    authorization_parameters=GlobusAuthorizationParameters(
        required_scopes=["foo"],
        session_message="Missing required 'foo' consent",
    ),
    extra={
        "message": "Missing required 'foo' consent",
        "request_id": "WmMV97A1w",
        "required_scopes": ["foo"],
        "resource": "/transfer",
    },
)

# Render a dictionary with extra fields
error.to_dict(include_extra=True)

These fields are stored by both the GARE and GlobusAuthenticationParameters classes in an extra attribute.

Note

Non-canonical fields in a Globus Auth Requirements Error are primarily intended to make it easier for services to provide backward-compatibile error responses to clients that have not adopted the Globus Auth Requirements Error format. Avoid using non-canonical fields for any data that should be generically understood by a consumer of the error response.

GlobusApp Integration

In order to standardize a common GARE-handling approach, the SDK’s GlobusApp contains a built-in GARE redrive mechanism (disabled by default).

When enabled (setting the config flag auto_redrive_gares to True), any client created with a GlobusApp will receive an additional request-transport retry handler. This handler will intercept the first occurrence of a 403 response which parses as a GARE and “redrive it”, by:

  1. Initiating a fresh login request with the defined LoginFlowManager

  2. Caching new tokens for subsequent requests

  3. Re-attempting the original request with the new tokens

This allows for very simple error-handling, particularly in scripts, wherein the executing user or client is automatically prompted to remediate manually-required steps (e.g., consent, MFA) without any additional code.

from globus_sdk import UserApp, GlobusAppConfig, TransferClient

config = GlobusAppConfig(auto_redrive_gares=True)
with UserApp("my-gare-demo", "<client-id>", config=config) as app:
    tc = TransferClient(app=app)

    # If the transfer service were to return a 403 GARE, the script runner would be
    # prompted to log in with any explicit specifications, e.g., MFA, consents.
    # Once they complete the login flow (by providing the newly minted auth code),
    # the original request is attempted once more.
    task = tc.submit_transfer(your_transfer_data)

Parsing Responses

If you are writing a client to a Globus API, the gare subpackage provides utilities to detect legacy Globus Auth requirements error response formats and normalize them.

To detect if a GlobusAPIError, ErrorSubdocument, or JSON response dictionary represents an error that can be converted to a Globus Auth Requirements Error, you can use, e.g.,:

from globus_sdk import gare

error_dict = {
    "code": "ConsentRequired",
    "message": "Missing required foo consent",
}
# The dict is not a Globus Auth Requirements Error, so `False` is returned.
gare.is_auth_requirements_error(error_dict)

# The dict is not a Globus Auth Requirements Error and cannot be converted.
gare.to_auth_requirements_error(error_dict)  # None

error_dict = {
    "code": "ConsentRequired",
    "message": "Missing required foo consent",
    "required_scopes": ["urn:globus:auth:scope:transfer.api.globus.org:all[*foo]"],
}
gare.is_auth_requirements_error(error_dict)  # True
gare.to_auth_requirements_error(error_dict)  # GARE

Note

If a GlobusAPIError represents multiple errors that were returned in an array, to_auth_requirements_error() only returns the first error in that array that can be converted to the Globus Auth Requirements Error response format. In this case (and in general) it’s preferable to use to_auth_requirements_errors() (which also accepts a list of GlobusAPIErrors, ErrorSubdocuments, and JSON response dictionaries):

gare.to_auth_requirements_error(other_error)  # GARE
gare.to_auth_requirements_errors([other_error])  # [GARE, ...]

Notes

GARE enforces types strictly when parsing a Globus Auth Requirements Error response dictionary, and will raise a globus_sdk.ValidationError if a supported field is supplied with a value of the wrong type.

GARE does not attempt to mimic or itself enforce any logic specific to the Globus Auth service with regard to what represents a valid combination of fields (e.g., session_required_mfa requires either session_required_identities or session_required_single_domain in order to be properly handled).

Reference

class globus_sdk.gare.GARE(code, authorization_parameters, *, extra=None)[source]

Represents a Globus Auth Requirements Error.

A Globus Auth Requirements Error is a class of error that is returned by Globus services to indicate that additional authorization is required in order to complete a request and contains information that can be used to request the appropriate authorization.

Variables:

  • code (str) – The error code for this error.

  • authorization_parameters (GlobusAuthorizationParameters) – The authorization parameters for this error.

  • extra (dict) – A dictionary of additional fields that were provided. May be used for forward/backward compatibility.

classmethod from_dict(data)

Instantiate from a dictionary.

Parameters:

data (dict[str, Any]) – The dictionary to create the error from.

Return type:

Self

to_dict(include_extra=False)

Render to a dictionary.

Parameters:

include_extra (bool) – Whether to include stored extra (non-standard) fields in the returned dictionary.

Return type:

dict[str, Any]

class globus_sdk.gare.GlobusAuthorizationParameters(*, session_message=None, session_required_identities=None, session_required_policies=None, session_required_single_domain=None, session_required_mfa=None, required_scopes=None, prompt=None, extra=None)[source]

Data class containing authorization parameters that can be passed during an authentication flow to control how the user will authenticate.

When used with a GARE this represents the additional authorization parameters needed in order to complete a request that had insufficient authorization state.

Variables:

  • session_message (str, optional) – A message to be displayed to the user.

  • session_required_identities (list of str, optional) – A list of identities required for the session.

  • session_required_policies (list of str, optional) – A list of policies required for the session.

  • session_required_single_domain (list of str, optional) – A list of domains required for the session.

  • session_required_mfa (bool, optional) – Whether MFA is required for the session.

  • required_scopes (list of str, optional) – A list of scopes for which consent is required.

  • prompt (str, optional) – The OIDC ‘prompt’ parameter, for which Globus Auth currently supports the values ‘login’ and ‘none’.

  • extra (dict) – A dictionary of additional fields that were provided. May be used for forward/backward compatibility.

classmethod from_dict(data)

Instantiate from a dictionary.

Parameters:

data (dict[str, Any]) – The dictionary to create the error from.

Return type:

Self

to_dict(include_extra=False)

Render to a dictionary.

Parameters:

include_extra (bool) – Whether to include stored extra (non-standard) fields in the returned dictionary.

Return type:

dict[str, Any]

globus_sdk.gare.to_gare(error)[source]

Converts a GlobusAPIError, ErrorSubdocument, or dict into a GARE by attempting to match to GARE (preferred) or legacy variants.

Note

A GlobusAPIError may contain multiple errors, and in this case only a single GARE is returned for the first error that matches a known format.

If the provided error does not match a known format, None is returned.

Parameters:

error (GlobusAPIError | ErrorSubdocument | dict[str, Any]) – The error to convert.

Return type:

GARE | None

globus_sdk.gare.to_gares(errors)[source]

Converts a list of GlobusAPIErrors, ErrorSubdocuments, or dicts into a list of GAREs by attempting to match each error to GARE (preferred) or legacy variants.

Note

A GlobusAPIError may contain multiple errors, so the result list could be longer than the provided list.

If no errors match any known formats, an empty list is returned.

Parameters:

errors (list[GlobusAPIError | ErrorSubdocument | dict[str, Any]]) – The errors to convert.

Return type:

list[GARE]

globus_sdk.gare.is_gare(error)[source]

Return True if the provided error matches a known Globus Auth Requirements Error format.

Parameters:

error (GlobusAPIError | ErrorSubdocument | dict[str, Any]) – The error to check.

Return type:

bool

globus_sdk.gare.has_gares(errors)[source]

Return True if any of the provided errors match a known Globus Auth Requirements Error format.

Parameters:

errors (list[GlobusAPIError | ErrorSubdocument | dict[str, Any]]) – The errors to check.

Return type:

bool