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:
Cannot be null.
AuthRedirectContext
Used by the following filters to indicate that a login redirect is pending:
For a single request there must be at most one instance of AuthRedirectContext in the context hierarchy. Confirm for the presence of an AuthRedirectContext before adding a new instance or adding query parameters to an existing instance.
Properties
"isImpendingIgRedirectNotified": boolean-
Returns
trueif an IG redirect attempt is pending. Otherwise, returnsfalse.
"notifyImpendingIgRedirectAndUpdateUri": URI-
Notifies that an IG redirection has been attempted, and returns an updated URI as follows:
-
If no query parameters are added to the context, return the original URI.
-
If query parameters are added to the context, apply them to the URI and return an updated URI.
-
If the added query parameters have the same name as existing query parameters, replace the existing parameters and return an updated URI.
For example, a request to
example.com/profiletriggers a login redirect toexample.com/login. After authentication, the request is expected to be redirected to the original URI,example.com/profile. -
"addQueryParameter": java.lang.String-
Adds a query parameter to the context, for use by
notifyImpendingIgRedirectAndUpdateUri.
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": java.lang.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": java.util.List <java.security.cert.Certificate>-
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": java.lang.String-
The IP address of the interface that received the request.
"localPort": integer-
The port of the interface that received the request.
"remoteAddress": java.lang.String-
The IP address of the client (or the last proxy) that sent the request.
"remotePort": integer-
The source port of the client (or the last proxy) that sent the request.
"remoteUser": java.lang.String-
The login of the user making the request, or
nullif unknown. This is likely to benullunless you have deployed IG with a non-default deployment descriptor that secures the IG web application. "userAgent": java.lang.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": org.forgerock.json.jose.jwt.JwtClaimsSet-
Full JwtClaimsSet for the identity of the authenticated user. Cannot be null.
Access claims as follows:
-
Claims with a getter by using the property name. For example, access
getSubjectwithcontexts.cdsso.claimsSet.subject. -
All other claims by using the
getClaimmethod. For example, accesssubnamewithcontexts.cdsso.claimsSet.getClaim('subname').
-
"cookieInfo": org.forgerock.openig.http.CookieBuilder-
Configuration data for the CDSSO authentication cookie, with the following attributes:
-
name: Cookie name (string) -
domain: (Optional) Cookie domain (string) -
path: Cookie path (string)
No attribute can be null.
-
"redirectEndpoint": java.lang.String-
Redirect endpoint URI configured for communication with AM. Cannot be null.
"sessionUid": java.lang.String-
Universal session ID. Cannot be null.
"token": java.lang.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": java.lang.String-
The error that occurred during authentication. Cannot be null.
"description": java.lang.String-
A description of the error that occurred during authentication. Cannot be null.
"throwable": java.lang.Throwable-
Any
Throwableassociated 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, JsonValue, or map for downstream use.
Properties
The context is named jwtBuilder, and is accessible at ${contexts.jwtBuilder},
with the following properties:
"value": java.lang.String-
The base64url encoded UTF-8 parts of the JWT, containing name-value pairs of data. Cannot be null.
"claims": java.util.Map-
Map with the format
Map<String,Object>, where:-
Key: Claim name
-
Value: Claim value
-
"claimsAsJsonValue": org.forgerock.json.JsonValue-
Claims as a JSon value.
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": java.lang.String-
The value of the JWT. Cannot be null.
"claims": org.forgerock.json.jose.jwt.JwtClaimsSet-
A copy of the claims as a JwtClaimsSet.
"info": java.util.Map-
A map in the format
Map<String,Object>, where:-
Key: Claim name
-
Value: Claim value
-
"jwt": org.forgerock.json.jose.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": java.lang.String-
The value of the JWT. Cannot be null.
"violations": java.util.List<Violation>-
A 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": org.forgerock.http.oauth2.AccessTokenInfo-
The AccessTokenInfo is built from the following properties:
"info": java.util.Map-
A map with the format
Map<String,Object>, where-
Key: Claim name
-
Value: Claim value in raw JSON
-
"token": java.lang.String-
Access token identifier issued from the authorization server.
"scopes": java.util.Set-
A set scopes associated to this token, with the format
Set<String>. "expiresAt": java.lang.Long-
Timestamp of when the token expires, in milliseconds since epoch.
OAuth2TokenExchangeContext
When the OAuth2TokenExchangeFilter succesfully issues a token, it injects the issued token and its scopes into this context.
Properties
The context name is OAuth2TokenExchangeContext, and is accessible at
${contexts.oauth2TokenExchange}.
The context has the following properties:
"issuedToken": java.lang.String-
The token issued by the authorization server.
"issuedTokenType": java.lang.String-
The token type URN.
"scopes": java.util.Set<java.lang.String>-
One or more scopes associated with the issued token, for example,
"scope1", "scope2", "scope3". "rawInfo": org.forgerock.json.JsonValue-
The raw token info as issued by the authorization server.
OAuth2FailureContext
When an OAuth 2.0 authorization operation fails, the error and error description provided by the authorization service are injected into this context for use downstream.
For example, when the
OAuth2TokenExchangeFilter fails
to exchange a token, it injects the error and description into this context.
The context is passed into calls to the failureHandler in the
OAuth2TokenExchangeFilter.
This context supports OAuth 2.0 error messages in the format given by RFC 6749.
Properties
The context is named OAuth2Failure, and is accessible at
${contexts.oauth2failure}. The context has the following properties:
"error": java.lang.String-
The error field name.
"description": java.lang.String-
Error description field name.
"exception": org.forgerock.openig.filter.oauth2.client.OAuth2ErrorException-
The OAuth 2.0 exception associated with the token exchange error.
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": java.util.Map-
A map with the format
Map<String, List<String>>, where:-
Key: Attribute name.
-
Value: A One or more attribute values provided in the policy decision. Can be empty, but not null.
-
"jsonAttributes": java.util.Map-
A map with the format
Map<String, List<String>>, where:-
Key: Attribute name.
-
Value: One or more attribute values provided in the policy decision. Can be empty, but not null.
-
"advices": java.util.Map-
A map with the format
Map<String, List<String>>, where:-
Key: Advice name.
-
Value: One or more advice values provided in the policy decision. Can be empty, but not null.
-
"jsonAdvices": java.util.Map-
A map with the format
Map<String, List<String>>, where:-
Key: Advice name
-
Value: One or more advice values provided in the policy decision. Can be empty, but not null.
-
"actions": java.util.Map-
A map with the format
Map<String, Boolean>where:-
Key: Action name.
-
Value:
truewhen an action is allowed for the specified resource,falseotherwise. Cannot be null.
-
"jsonActions": json.JsonValue-
A map with the format
Map<String, Boolean>, where:-
Key: Action name.
-
Value:
truewhen an action is allowed for the specified resource,falseotherwise. Cannot be null.
-
"resource": java.lang.String-
The resource value used in the policy request. Can be empty, but not null.
Request
An HTTP request message. Access the content of the request by using expressions.
Properties
"method": java.lang.String-
The HTTP method; for example,
GET. "uri": java.net.URI-
The fully-qualified URI of the resource being accessed; for example,
http://www.example.com/resource.txt. "version": java.lang.String-
The protocol version used for the request; for example,
HTTP/2. "headers": org.forgerock.http.protocol.Headers-
One or more headers in the request, with the format
header_name: [ header_value, … ]. The following example accesses the first value of the request headerUserId:pass:[${request.headers['UserId'][0]} "cookies": org.forgerock.http.protocol.RequestCookies-
Incoming request cookies, with the format
cookie_name: [ cookie_value, … ]. The following example accesses the first value of the request cookiemy-jwt:pass:[${request.cookies['my-jwt'][0].value} "entity": Entity-
The message body. The following example accesses the subject token from the request entity:
pass:[#{request.entity.form['subject_token'][0]}] "queryParams": Form-
Returns a copy of the query parameters decoded as a form. Modifications to the returned form are not reflected in the request.
Response
An HTTP response message. Access the content of the response by using expressions.
Properties
"cause": java.lang.Exception-
The cause of an error if the status code is in the range 4xx-5xx. Possibly null.
"status": Status-
The response status.
"version": java.lang.String-
The protocol version used the response; for example,
HTTP/2. "headers": org.forgerock.http.protocol.Headers-
One or more headers in the response. The following example accesses the first value of the response header
Content-Type:pass:[${response.headers['Content-Type'][0]}] "trailers": org.forgerock.http.protocol.Headers-
One or more trailers in the response. The following example accesses the first value of the response trailer
Content-Length:pass:[${response.trailers['Content-Length'][0]}] "entity": Entity-
The message entity body. The following example accesses the user ID from the response:
pass:[#{toString(response.entity.json['userId'])}]
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": java.util.Map-
A map with the format
Map<String, Object>, where:-
Key: Session property name
-
Value: Session property value
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()": json.JsonValue-
Raw JSON.
"latestAccessTime": java.time.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": java.time.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": java.time.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": java.util.Map-
A read-only map with the format
Map<String, String>, where-
Key: Name of a property bound to the session
-
Value: Value of the property
The following properties are retrieved:
-
When
sessionPropertiesin AmService is configured, listed session properties with a value. -
When
sessionPropertiesin AmService is not configured, all session properties with a value. -
Properties with a value that are required by IG but not specified by
sessionPropertiesin 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
Can be empty, but not null.
-
"realm": java.lang.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": java.lang.String-
The handle to use for logging out of the session. Can be null if the handle is not available for the session.
"universalId": java.lang.String-
The DN that AM uses to uniquely identify the user. Can be null if it cannot be obtained from the SSO token.
"username": java.lang.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": java.util.Map-
A map with the format
Map<String, Object>, where-
Key: Property bound to the SSO token, such as
realmoruid -
Value: Value of the property
Information associated with the SSO token, such as
realmoruid. Cannot be null. -
"loginEndpoint": java.lang.String-
A string representing the URL of the login endpoint, evaluated from the configuration of SingleSignOnFilter.
"value": java.lang.String-
The value of the SSO token. Cannot be null.
Status
An HTTP response status.
Properties
"code": integer-
Three-digit integer reflecting the HTTP status code.
"family": enumeration-
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": java.lang.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": org.forgerock.services.TransactionId-
The ID of the transaction.
URI
Represents a Uniform Resource Identifier (URI) reference.
Properties
"scheme": string-
The scheme component of the URI, or
nullif the scheme is undefined. "authority": string-
The decoded authority component of the URI, or
nullif the authority is undefined.Use "rawAuthority" to access the raw (encoded) component.
"userInfo": string-
The decoded user-information component of the URI, or
nullif the user information is undefined.Use "rawUserInfo" to access the raw (encoded) component.
"host": string-
The host component of the URI, or
nullif the host is undefined. "port": number-
The port component of the URI, or
nullif the port is undefined. "path": string-
The decoded path component of the URI, or
nullif the path is undefined.Use "rawPath" to access the raw (encoded) component.
"query": string-
The decoded query component of the URI, or
nullif 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
nullif 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": java.lang.String-
The portion of the request URI which has been routed so far.
"matchedUri": java.lang.String-
The portion of the request URI that matched the URI template.
"originalUri": URI-
The original target URI for the request, as received by IG. The value of this field is read-only.
"remainingUri": java.lang.String-
The portion of the request URI that is remaining to be matched.
"uriTemplateVariables": java.util.Map-
A map with the format
Map<String, String>, where:-
Key: Name of a URI template variable
-
Value: Value of a URI template variable
-
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": java.lang.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": java.lang.String-
Realm as specified by AM, in a user-friendly slash (/) separated format. Can be null.
Example of use:
${contexts.userProfile.realm} "distinguishedName": java.lang.String-
Distinguished name of the user. Can be null.
Example of use:
${contexts.userProfile.distinguishedName} "commonName": java.lang.String-
Common name of the user. Can be null.
Example of use:
${contexts.userProfile.commonName} "rawInfo": java.util.Map-
An unmodifiable map in the format
Map<String, Object>, where:-
Key: Name of a field in an AM user profile
-
Value: Value of a field in an AM user profile
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()": json.JsonValue-
User profile information structured as JSON.
Example of use:
${contexts.userProfile.asJsonValue()}