PingGateway 2024.11

Contexts

The root object for request context information.

Contexts is a map of available contexts that implement the Context interface. The contexts map is populated dynamically when creating bindings to evaluate expressions and scripts.

If a context type appears multiple times in the chain of contexts, only the last value of the context is exposed in the contexts map. For example, if a route contains two JwtBuilderFilters each providing data in the JwtBuilderContext, only data from the last processed JwtBuilderFilter is contained in ${contexts.jwtBuilder}. Data from the first processed JwtBuilderFilter can be accessed by scripts and extensions through the Context API. The following example script accesses data from the first processed JwtBuilderFilter:

Context second = context.get("jwtBuilder")
     .map(Context::getParent)
     .flatMap(ctx -> ctx.get("jwtBuilder"))
     .orElse(null);

The map keys are strings and the values are context objects. All context objects use their version of the following properties:

"context-Name": string

Context name.

"context-ID": string

Read-only string uniquely identifying the context object.

"context-rootContext": boolean

True if the context object is a RootContext (has no parent).

"context-Parent": Context object

Parent of this context object.

Contexts provide contextual information to downstream filters and handlers about a handled request. The context can include information about the client making the request, the session, the authentication or authorization identity of the user, and any other state information associated with the request.

Contexts provide a way to access state information throughout the duration of the HTTP session between the client and protected application. Interaction with additional services can also be captured in the context.

Filters can enrich existing contexts (store objects in sessions or attributes) or provide new contexts tailored for a purpose. The list of available contexts is dynamic and depends on which filters have been executed when a context is queried. For example, a context can be queried by a script, at startup, or at runtime.

Unlike session information, which spans multiple request/response exchanges, contexts last only for the duration of the request/response exchange and are then lost.

Summary of contexts

Type Accessible at Populated by Contains

AttributesContext

contexts.attributes.attributes and attributes

PingGateway core, when a request enters PingGateway

Map of request attributes for use by filters at different positions in the chain

AuthRedirectContext

${contexts.AuthRedirectContext}

FragmentFilter and DataPreservationFilter

Indication to the FragmentFilter and DataPreservationFilter that a login redirect is pending

CapturedUserPasswordContext

${contexts.capturedPassword}

CapturedUserPasswordFilter

Decrypted AM password of the current user

CdSsoContext

${contexts.cdsso}

CrossDomainSingleSignOnFilter

CDSSO token properties, session user ID, full claims set

CdSsoFailureContext

${contexts.cdssoFailure}

CrossDomainSingleSignOnFilter

Information about errors occurring during CDSSO authentication

ClientContext

${contexts.client}

PingGateway core, when a request enters PingGateway

Information about the client sending the request and the client certificate when using mTLS

FileAttributesContext

${contexts.fileAttributes}

FileAttributesFilter

Map of keys and values extracted with a FileAttributesFilter

IdentityRequestJwtContext

${contexts.IdentityRequestJwtContext}

IdentityAssertionHandler

Information and claims for an identity request JWT issued by PingOne Advanced Identity Cloud to PingGateway

IdpSelectionLoginContext

${contexts.idpSelectionLogin}

AuthorizationCodeOAuth2ClientFilter when loginHandler is specified.

The original target URI for a request received by PingGateway

JwtBuilderContext

${contexts.jwtBuilder}

JwtBuilderFilter

Built JWT as string, JsonValue, or map

JwtValidationContext

${contexts.jwtValidation}

JwtValidationFilter and IdTokenValidationFilter

Properties of a JWT after validation

JwtValidationErrorContext

${contexts.jwtValidationError}

JwtValidationFilter and IdTokenValidationFilter

Properties of a JWT after validation fails

OAuth2Context

${contexts.oauth2}

OAuth2ResourceServerFilter

Properties of an OAuth 2.0 access token after validation

OAuth2FailureContext

${contexts.oauth2Failure}

AuthorizationCodeOAuth2ClientFilter and OAuth2TokenExchangeFilter

OAuth 2.0 authorization operation error and error description

OAuth2TokenExchangeContext

${contexts.oauth2TokenExchange}

OAuth2TokenExchangeFilter

Issued token and its scopes

PingOneProtectDeviceProfileContext

${contexts.pingOneProtectProfile}

PingOneProtectEvaluationFilter

Internal-use-only device profile data to support PingOne Protect risk evaluation

PingOneProtectEvaluationContext

${contexts.pingOneProtect}

PingOneProtectEvaluationFilter

A PingOne Protect risk evaluation result for an incoming request

PolicyDecisionContext

${contexts.policyDecision}

PolicyEnforcementFilter

Attributes and advices returned by AM policy decisions

SessionContext

${contexts.session}

PingGateway core, when a request enters PingGateway

Information about stateful and stateless sessions

SessionInfoContext

${contexts.amSession}

SessionInfoFilter

AM session information and properties

SqlAttributesContext

${contexts.sqlAttributes}

SqlAttributesFilter

Map of keys and values extracted with an SqlAttributesFilter

SsoTokenContext

${contexts.ssoToken}

SingleSignOnFilter and CrossDomainSingleSignOnFilter

SSO tokens and their validation information

StsContext

${contexts.sts}

TokenTransformationFilter

Result of a token transformation

TransactionIdContext

${contexts.transactionId}

PingGateway core, when a request enters PingGateway

ForgeRock transaction ID of a request

UriRouterContext

${contexts.router}

PingGateway core, when a request traverses a route

Routing information associated with a request

UserProfileContext

${contexts.userProfile}

UserProfileFilter

User profile information

PingGateway uses these contexts: