IG 7.1.2

Requests, Responses, and Contexts

Contexts provide contextual information about the handled request, such as information about the client making the request, the session, the authentication or authorization identity of the principal, and any other state information associated with the request. Contexts provide a means to access state information throughout the duration of the HTTP session between the client and protected application, including when this involves interaction with additional services.

Each filter can add to the contextual information by enriching the existing context (for example, by storing objects in sessions or attributes), or by providing a new context tailored for a specific purpose.

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

AttributesContext

Provides a map for request attributes. When IG processes a single request, it injects transient state information about the request into this context. Attributes stored when processing one request are not accessible when processing a subsequent request.

IG automatically provides access to the attributes field through the attributes bindings in expressions. For example, to access a username with an expression, use ${attributes.credentials.username} instead of ${contexts.attributes.attributes.credentials.username}

Use SessionContext to maintain state between successive requests from the same logical client.

Properties

The context is named attributes, and is accessible at ${attributes}. The context has the following property:

"attributes": map

Map of information conveyed between filters and handlers. Cannot be null.

AuthRedirectContext

Used by the FragmentFilter to indicate that a login redirect is pending.

Properties

"isImpendingIgRedirectNotified": boolean

Returns true if a downstream filter notifies IG that it will redirect a login attempt. Otherwise, false.

"notifyImpendingIgRedirect"

IG sets this context to true when a filter triggers a redirect which will be followed by a subsequent request to the original URI.

For example, a request to example.com/profile triggers a login redirect to example.com/login. After authentication, the request is expected to be redirected to the original URI, example.com/profile.

CapturedUserPasswordContext

Provides the decrypted AM password of the current user. When the CapturedUserPasswordFilter processes a request, it injects the decrypted password from AM into this context.

Properties

The context is named capturedPassword, and is accessible at ${contexts.capturedPassword}. The context has the following properties:

"raw": byte[]

The decrypted password as bytes.

"value": string

The decrypted password as a UTF-8 string.

ClientContext

Information about the client sending a request. When IG receives a request, it injects information about the client sending the request into this context.

Properties

The context is named client, and is accessible at ${contexts.client}. The context has the following properties:

"certificates": array

List of X.509 certificates presented by the client. If the client does not present any certificates, IG returns an empty list. Never null.

"isExternal": boolean

True if the client connection is external.

"isSecure": boolean

True if the client connection is secure.

"localAddress": string

The IP address of the interface that received the request.

"localPort": number

The port of the interface that received the request.

"remoteAddress": string

The IP address of the client (or the last proxy) that sent the request.

"remotePort": number

The source port of the client (or the last proxy) that sent the request.

"remoteUser": string

The login of the user making the request, or null if unknown. This is likely to be null unless you have deployed IG with a non-default deployment descriptor that secures the IG web application.

"userAgent": string

The value of the User-Agent HTTP header in the request if any, otherwise null.

Contexts

The root object for request context information.

Contexts is a map of available contexts, which implement the Context interface. The contexts map’s keys are strings and the values are context objects. A context holds type-safe information useful for processing requests and responses. The contexts map is populated dynamically when creating bindings for evaluation of expressions and scripts.

All context objects use their version of the following properties:

"context-Name": string

Name of the context.

"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.

Properties

The contexts object can provide access to the following contexts for each request:

The contexts object can provide access to the following contexts when related filters are used:

CdSsoContext

Provides the cross-domain SSO properties for the CDSSO token, the user ID of the session, and the full claims set. When the CrossDomainSingleSignOnFilter processes a request, it injects the information in this context.

Properties

The context is named cdsso, and is accessible at ${contexts.cdsso}. The context has the following properties:

"claimsSet": JwtClaimsSet object, required

Full claims set for the identity of the authenticated user. Cannot be null.

"cookieInfo": object

Configuration data for the CDSSO authentication cookie, with the following attributes:

  • name: Cookie name (string)

  • domain: Cookie domain (optional string)

  • path: Cookie path (string)

No attribute can be null.

redirectEndpoint": string

Redirect endpoint URI configured for communication with AM. Cannot be null.

"sessionUid": string

Universal session ID. Cannot be null.

"token": string

Value of the CDSSO token. Cannot be null.

CdSsoFailureContext

Contains the error details for any error that occurred during cross-domain SSO authentication. When the CrossDomainSingleSignOnFilter processes a request, should an error occur that prevents authentication, the error details are captured in this context.

Properties

The context is named cdssoFailure, and is accessible at ${contexts.cdssoFailure}. The context has the following properties:

"error": The error (string)

The error that occurred during authentication. Cannot be null.

"description": Error description (string)

A description of the error that occurred during authentication. Cannot be null.

"throwable": Throwable

Any Throwable associated with the error that occured during authentication. Can be null.

JwtBuilderContext

When the JwtBuilderFilter processes a request, it stores provided data in this context. This context returns the JWT as string for downstream use.

Properties

The context is named jwtBuilder, and is accessible at ${contexts.jwtBuilder}. The context has the following properties:

"value": string

The base64url encoded UTF-8 parts of the JWT, containing name-value pairs of data. Cannot be null.

JwtValidationContext

Provides the properties of a JWT after validation. When the JwtValidationFilter validates a JWT, or the IdTokenValidationFilter validates an id_token, it injects a copy of the JWT and its claims into this context.

Properties

The context is named jwtValidation, and is accessible at ${contexts.jwtValidation}. The context has the following properties:

"value": string

The value of the JWT. Cannot be null.

"claims": JWT claims set

A copy of the claims as a JwtClaimsSet.

"info": map

A copy of the claims as a map.

"jwt": JWT

A copy of the JWT.

JwtValidationErrorContext

Provides the properties of a JWT after validation fails. When the JwtValidationFilter fails to validate a JWT, or the IdTokenValidationFilter fails to validate an id_token, it injects the JWT and a list of violations into this context.

Properties

The context is named jwtValidationError, and is accessible at ${contexts.jwtValidationError}. The context has the following properties:

"jwt": string

The value of the JWT. Cannot be null.

"violations": list

An unmodifiable list of violations.

OAuth2Context

Provides OAuth 2.0 access tokens. When the OAuth2ResourceServerFilter processes a request, it injects the access token into this context.

Properties

The context name is oauth2, and is accessible at ${contexts.oauth2}. The context has the following properties:

"accessToken": AccessTokenInfo

The AccessTokenInfo is built from the following properties:

"info": (map<string>, object)

Raw JSON as a map.

"token": string

Access token identifier issued from the authorization server.

"scopes": space separated string

Scopes associated to this token.

"expiresAt": long

Timestamp (in milliseconds since epoch) when the token expires.

PolicyDecisionContext

Provides attributes and advices returned by AM policy decisions. When the PolicyEnforcementFilter processes a request, it injects the attributes and advices into this context.

Properties

The context is named policyDecision, and is accessible at ${contexts.policyDecision}. The context has the following properties:

"attributes": unmodifiable map

The map of attributes provided in the policy decision. Can be empty, but not null.

"jsonAttributes": JsonValue

The map of attributes provided in the policy decision. Cannot be null.

"advices": map

The map of advices provided in the policy decision. Can be empty, but not null.

"jsonAdvices": JsonValue

The map of advices provided in the policy decision. Cannot be null.

Request

An HTTP request message.

Properties

"method": string

The method to be performed on the resource. Example: "GET".

"uri": object

The fully-qualified URI of the resource being accessed. Example: "http://www.example.com/resource.txt".

See also URI.

"version": string

Protocol version. Example: "HTTP/1.1".

"headers": object

Exposes message header fields as name-value pairs, where name is header name and value is an array of header values.

"cookies": object

Exposes incoming request cookies as name-value pairs, where name is cookie name and value is an array of string cookie values.

"form": object

Exposes query parameters and/or application/x-www-form-urlencoded entity as name-value pairs, where name is the field name and value is an array of string values.

"entity": object

The message entity body.

Methods are provided for accessing the entity as byte, string, or JSON content. For information, see Entity.

Response

An HTTP response message.

Properties

"cause": Exception object

The cause of an error if the status code is in the range 4xx-5xx. Possibly null.

"status": Status object

The response status.

For details, see Status.

"version": string

Protocol version. Example: "HTTP/1.1".

"headers": object

Exposes message header fields as name-value pairs, where name is header name and value is an array of header values.

"entity": object

The message entity body.

Methods are provided for accessing the entity as byte, string, or JSON content. For information, see Entity.

SessionContext

Provides access to information about stateful and stateless sessions.

To process a single request, consider using AttributesContext to transfer transient state between components and prevent IG from creating additional sessions.

IG automatically provides access to the session field through the session bindings in expressions. For example, to access a username with an expression, use ${session.username} instead of ${contexts.session.session.username}

Properties

The context is named session, and is accessible at ${contexts.session}. The context has the following properties:

"session": map

A map of attributes that are name-value pairs of the format Map<String, Object>.

Any object type can be stored in the session.

SessionInfoContext

Provides AM session information and properties. When the SessionInfoFilter processes a request, it injects info and properties from the AM session into this context.

Properties

The context is named amSession, and is accessible at ${contexts.amSession}. The context has the following properties:

"asJsonValue()": JsonValue

Raw JSON.

"latestAccessTime": instant

The timestamp of when the session was last used. Can be null if the DN is not resident on the SSO token, or if the time cannot be obtained from the session.

"maxIdleExpirationTime": instant

The timestamp of when the session would time out for inactivity. Can be null if the DN is not resident on the SSO token, or if the time cannot be obtained from the session.

"maxSessionExpirationTime": instant

The timestamp of when the session would time out regardless of activity. Can be null if the DN is not resident on the SSO token, or if the time cannot be obtained from the session.

"properties": map

The read-only map of properties bound to the session. Can be empty, but not null. The following properties are retrieved:

  • When sessionProperties in AmService is configured, listed session properties with a value.

  • When sessionProperties in AmService is not configured, all session properties with a value.

  • Properties with a value that are required by IG but not specified by sessionProperties in AmService. For example, when the session cache is enabled, session properties related to the cache are automatically retrieved.

Properties with a value are returned, properties with a null value are not returned

"realm": string

The realm as specified by AM, in a user-friendly slash (/) separated format. Can be null if the DN is not resident on the SSO token.

"sessionHandle": string

The handle to use for logging out of the session. Can be null if the handle is not available for the session.

"universalId": string

The DN that AM uses to uniquely identify the user. Can be null if it cannot be obtained from the SSO token.

"username": string

A user-friendly version of the username. Can be null if the DN is not resident on the SSO token, or empty if it cannot be obtained from the DN.

SsoTokenContext

Provides SSO tokens and their validation information. When the SingleSignOnFilter or CrossDomainSingleSignOnFilter processes a request, it injects the value of the SSO token and additional information in this context.

Properties

The context is named ssoToken, and is accessible at ${contexts.ssoToken}. The context has the following properties:

"info": map

Information associated with the SSO token, such as realm or uid. Cannot be null.

"loginEndpoint": url

URL for the login endpoint, evaluated from the configuration of SingleSignOnFilter.

"value": string

The value of the SSO token. Cannot be null.

Status

Represents an HTTP response status. For details, see RFC 7231: HTTP/1.1 Semantics and Content, Section 6.1. Overview of Status Codes.

Properties

"code": integer

Three-digit integer reflecting the HTTP status code.

"family": enum

Family Enum value representing the class of response that corresponds to the code:

Family.INFORMATIONAL

Status code reflects a provisional, informational response: 1xx.

Family.SUCCESSFUL

The server received, understood, accepted and processed the request successfully. Status code: 2xx.

Family.REDIRECTION

Status code indicates that the client must take additional action to complete the request: 3xx.

Family.CLIENT_ERROR

Status code reflects a client error: 4xx.

Family.SERVER_ERROR

Status code indicates a server-side error: 5xx.

Family.UNKNOWN

Status code does not belong to one of the known families: 600+.

"reasonPhrase": string

The human-readable reason-phrase corresponding to the status code.

"isClientError": boolean

True if Family.CLIENT_ERROR.

"isInformational": boolean

True if Family.INFORMATIONAL.

"isRedirection": boolean

True if Family.REDIRECTION.

"isServerError": boolean

True if Family.SERVER_ERROR.

"isSuccessful": boolean

True if Family.SUCCESSFUL.

StsContext

Provides the result of a token transformation. When the TokenTransformationFilter processes a request, it injects the result into this context.

Properties

The context is named sts, and is accessible at ${contexts.sts}. The context has the following properties:

"issuedToken": string

The result of the token transformation.

TransactionIdContext

The transaction ID of a request. When IG receives a request, it injects the transaction ID into this context.

Properties

The context is named transactionId, and is accessible at ${contexts.transactionId}. The context has the following properties:

"transactionId": TransactionId

The ID of the transaction.

URI

Represents a Uniform Resource Identifier (URI) reference.

Properties

"scheme": string

The scheme component of the URI, or null if the scheme is undefined.

"authority": string

The decoded authority component of the URI, or null if the authority is undefined.

Use "rawAuthority" to access the raw (encoded) component.

"userInfo": string

The decoded user-information component of the URI, or null if the user information is undefined.

Use "rawUserInfo" to access the raw (encoded) component.

"host": string

The host component of the URI, or null if the host is undefined.

"port": number

The port component of the URI, or null if the port is undefined.

"path": string

The decoded path component of the URI, or null if the path is undefined.

Use "rawPath" to access the raw (encoded) component.

"query": string

The decoded query component of the URI, or null if the query is undefined.

The query key and value is decoded. However, because a query value can be encoded more than once in a redirect chain, even though it is decoded it can contain unsafe ASCII characters.

Use "rawQuery" to access the raw (encoded) component.

"fragment": string

The decoded fragment component of the URI, or null if the fragment is undefined.

Use "rawFragment" to access the raw (encoded) component.

UriRouterContext

Provides routing information associated with a request. When IG routes a request, it injects information about the routing into this context.

Properties

The context is named router, and is accessible at ${contexts.router}. The context has the following properties:

"baseUri": string

The portion of the request URI which has been routed so far.

"matchedUri": string

The portion of the request URI that matched the URI template.

"originalUri": URI

The original target URI for the request, as received by the web container.

The value of this field is read-only.

"remainingUri": string

The portion of the request URI that is remaining to be matched.

"uriTemplateVariables": map

An unmodifiable map, where the keys and values are strings. The map contains the parsed URI template variables keyed on the URI template variable name.

UserProfileContext

When the UserProfileFilter processes a request, it injects the user profile information into this context. This context provides raw JSON representation, and convenience accessors that map commonly used LDAP field names to a context names.

Properties

The context is named userProfile, and is accessible at ${contexts.userProfile}. The context has the following properties:

"username": string

User-friendly version of the username. This field is always fetched. If the underlying data store doesn’t include username, this field is null.

Example of use: ${contexts.userProfile.username}

"realm": string

Realm as specified by AM, in a user-friendly slash (/) separated format. Can be null.

Example of use: ${contexts.userProfile.realm}

"distinguishedName": string

Distinguished name of the user. Can be null.

Example of use: ${contexts.userProfile.distinguishedName}

"commonName": string

Common name of the user. Can be null.

Example of use: ${contexts.userProfile.commonName}

"rawInfo": (map<string>, object)

Unmodifiable map of the user profile information.

This context contains the object structure of the AM user profile. Any individual field can be retrieved from the map. Depending on the requested fields, the context can be empty or values can be null.

Examples of use: ${contexts.userProfile.rawInfo}, ${contexts.userProfile.rawInfo.username}, ${contexts.userProfile.rawInfo.employeeNumber[0]}.

"asJsonValue()": JsonValue

Raw JSON of the user profile information.

Example of use: ${contexts.userProfile.asJsonValue()}

Copyright © 2010-2023 ForgeRock, all rights reserved.