IG 2023.2

Miscellaneous configuration objects

The following objects can be defined in the configuration:

AmService

Holds information about the configuration of an instance of AM. The AmService is available to IG filters that communicate with that instance.

When IG uses an AmService, IG is positioned as the client of the service. By default, IG is subscribed to Websocket notifications from AM, and the WebSocket connection can be secured by ClientTlsOptions.

Usage

{
  "name": string,
   "type": "AmService",
   "config": {
     "agent": object,
     "secretsProvider": SecretsProvider reference,
     "notifications": object,
     "realm": configuration expression<string>,
     "amHandler": Handler reference,
     "sessionCache": object,
     "sessionIdleRefresh": object,
     "sessionProperties": [ configuration expression<string>, ... ],
     "ssoTokenHeader": configuration expression<string>,
     "url": configuration expression<url>,
     "version": configuration expression<string>
   }
}

Properties

"agent": object, required

The credentials of the IG agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user’s profile, making policy evaluations, and connecting to the AM notification endpoint.

"username": configuration expression<string>, required

Agent name.

"passwordSecretId": configuration expression<secret-id>, required

The secret ID of the agent password.

This secret ID must point to a GenericSecret.

"password": configuration expression<string>, required
This property is deprecated and is not considered secure. Use passwordSecretId instead. For more information, refer to the Deprecated section of the Release Notes.

The agent password.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the agent password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default secrets object.

"realm": configuration expression<string>, optional

The AM realm in which the IG agent is created.

Default: / (top level realm).

"amHandler": Handler reference, optional

The Handler to use for communicating with AM. In production, use a ClientHandler that is capable of making an HTTPS connection to AM.

AmService does not use amHandler to subscribe to WebSocket notifications from AM. To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap, and refer to it from the amHandler object and the notifications subproperty tls .

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

"amHandler": {
  "type": "Chain",
  "config": {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

See also Handlers and ClientHandler.

"notifications": object, optional

Configure a WebSocket notification service, to subscribe to Websocket notifications from AM.

To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap, and refer to it from the amHandler object and the notifications subproperty tls. Alternatively, use proxyOptions to share a proxy configuration between the amHandler and the notification service.

For information, see WebSocket Notifications.

{
  "notifications": {
    "enabled": configuration expression<boolean>,
    "initialConnectionAttempts": configuration expression<number>,
    "reconnectDelay": configuration expression<duration>,
    "tls": ClientTlsOptions reference,
    "proxyOptions": ProxyOptions reference,
  }
}
enabled: configuration expression<boolean>, optional

A flag to enable WebSocket notifications. Set to false to disable WebSocket notifications.

Default: true

"initialConnectionAttempts": configuration expression<number>, optional

The maximum number of times IG attempts to open a WebSocket connection before failing to deploy a route. For no limit, set this property to -1.

If the WebSocket connection fails after it has been opened and the route is deployed, IG attempts to reconnect to it an unlimited number of times.

Default: 5

reconnectDelay: configuration expression<duration>, optional

The time between attempts to re-establish a lost WebSocket connection.

When a WebSocket connection is lost, IG waits for this delay and then attempts to re-establish the connection. If subsequent attempts fail, IG waits and tries again an unlimited number of times.

Default: 5 seconds

heartbeatInterval: configuration expression<duration>, optional

The interval at which the AmService issues a heartbeat on WebSocket connections. When activity on the connection is low, the heartbeat prevents middleware or policies situated between IG and AM from closing the connection for timeout.

Set to zero or unlimited to disable heartbeats.

Default: 1 minute

tls: ClientTlsOptions reference, optional

Use of a TlsOptions reference is deprecated; use ClientTlsOptions instead. For more information, refer to the Deprecated section of the Release Notes.

Configure options for WebSocket connections to TLS-protected endpoints. Define a ClientTlsOptions object inline or in the heap.

Default: Connections to TLS-protected endpoints are not configured.

"proxyOptions": ProxyOptions reference>, optional

A proxy server to which requests can be submitted. Use this property to relay requests to other parts of the network. For example, use it to submit requests from an internal network to the internet.

Provide the name of a ProxyOptions object defined in the heap, or an inline configuration.

Default: A heap object named ProxyOptions.

"url": configuration expression<url>, required

The URL of the AM service. When AM is running locally, this value could be https://am.example.com/openam. When AM is running in the ForgeRock Identity Cloud, this value could be https://myTenant.forgeblocks.com/am.

"sessionCache": object, optional

In AM, if the realm includes a customized session property safelist, include AMCtxId in the list of properties. The customized session property safelist overrides the global session property safelist.

Enable and configure caching of session information from AM, based on Caffeine. For more information, see the GitHub entry, Caffeine.

When sessionCache is enabled, IG can reuse session token information without repeatedly asking AM to verify the token. Each instance of AmService has an independent cache content. The cache is not shared with other AmService instances, either in the same or different routes, and is not distributed among clustered IG instances.

When sessionCache is disabled, IG must ask AM to verify the token for each request.

IG evicts session info entries from the cache for the following reasons:

  • AM cache timeout, based the whichever of the following events occur first:

    • maxSessionExpirationTime from SessionInfo

    • maxSessionTimeout from the AmService configuration

      When IG evicts session info entries from the cache, the next time the token is presented, IG must ask AM to verify the token.

  • If Websocket notifications are enabled, AM session revocation, for example, when a user logs out of AM.

    When Websocket notifications are enabled, IG evicts a cached token almost as soon as it is revoked on AM, and in this way stays synchronized with AM. Subsequent requests to IG that present the revoked token are rejected.

    When Websocket notifications are disabled, the token remains in the cache after it is revoked on AM. Subsequent requests to IG that present the revoked token are considered as valid, and can cause incorrect authentication and authorization decisions until its natural eviction from the cache.

{
  "sessionCache": {
    "enabled": configuration expression<boolean>,
    "executor": Executor service reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
    "onNotificationDisconnection": configuration expression<enumeration>
  }
}
enabled: configuration expression<boolean>, optional

Enable caching.

Default: false

executor: Executor service reference, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the cache.

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound.

maximumTimeToCache: configuration expression<duration>, optional

The maximum duration for which to cache session info. Consider setting this duration to be less than the idle timeout of AM.

If maximumTimeToCache is longer than maxSessionExpirationTime from SessionInfo, maxSessionExpirationTime is used.

Default:

  • When sessionIdleRefresh is set, idle timeout of AM minus 30 seconds.

  • When sessionIdleRefresh is not set, maxSessionExpirationTime, from SessionInfo.

onNotificationDisconnection: configuration expression<enumeration>, optional

The strategy to manage the cache when the WebSocket notification service is disconnected, and IG receives no notifications for AM events. If the cache is not cleared it can become outdated, and IG can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

  • NEVER_CLEAR

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Continue to use the existing cache.

      • Query AM for incoming requests that are not found in the cache, and update the cache with these requests.

  • CLEAR_ON_DISCONNECT

    • When the notification service is disconnected:

      • Clear the cache.

      • Deny access to all requests, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

  • CLEAR_ON_RECONNECT

    • When the notification service is disconnected:

      • Continue to use the existing cache.

      • Deny access for requests that are not cached, but do not update the cache with these requests.

    • When the notification service is reconnected:

      • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

      • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

"sessionIdleRefresh": object, optional

(From AM 6.5.3.) Enable and configure periodic refresh of idle sessions. When this property is enabled, IG requests session refresh:

  • The first time IG gets an SSO token from AM, irrespective of the age of the token

  • When sessionIdleRefresh.interval has elapsed

Use this property when AM is using CTS-based sessions. AM does not monitor idle time for client-side sessions, and so refresh requests are ignored.

When the SingleSignOnFilter is used for authentication with AM, AM can view a session as idle even though a user continues to interact with IG. The user session eventually times out and the user must re-authenticate.

When the SingleSignOnFilter filter is used with the PolicyEnforcementFilter, the session is refreshed each time IG requests a policy decision from AM. The session is less likely to become idle, and this property less required.

{
  "sessionIdleRefresh": {
    "enabled": configuration expression<boolean>,
    "interval": configuration expression<duration>
  }
}
enabled: configuration expression<boolean>, optional

Enable refresh of idle sessions.

Default: false

interval: configuration expression<duration>, optional

Duration to wait after a session becomes idle before requesting a session refresh.

Consider setting the refresh interval in line with the latest access time update frequency of AM. For example, if IG requests a refresh every 60 seconds, but the update frequency of AM is 5 minutes, AM ignores most of the IG requests.

Each session refresh must be reflected in the AM core token service. Setting the interval to a duration lower than one minute can adversely impact AM performance.

Default: 5 minutes

"sessionProperties": array of configuration expression<strings>, optional

The list of user session properties to retrieve from AM by the SessionInfoFilter.

Default: All available session properties are retrieved from AM.

"ssoTokenHeader": configuration expression<string>, optional

The header name or cookie name where this AM server expects to find SSO tokens.

If a value for ssoTokenHeader is provided, IG uses that value. Otherwise, IG queries the AM /serverinfo/* endpoint for the header or cookie name.

Default: Empty. IG queries AM for the cookie name.

"version": configuration expression<string>, optional

The version number of the AM server. IG uses the AM version to establish endpoints for its interaction with AM.

The AM version is derived as follows, in order of precedence:

  • Discovered value: AmService discovers the AM version. If version is configured with a different value, AmService ignores the value of version and issues a warning.

  • Value in version: AmService cannot discover the AM version, and version is configured.

  • Default value of AM 6: AmService cannot discover the AM version, and version is not configured.

If you use a feature that is supported only in a higher AM version than discovered or specifed, a message can be logged or an error thrown. For example, if sessionIdleRefresh is enabled but the AM version is below the required AM 6.5.3, an error like the following is logged:

sessionIdleRefresh is only supported with AM version 6.5.3 and above,
the configured AM version is 6

Default: AM 6.

ClientRegistration

A ClientRegistration holds information about registration with an OAuth 2.0 authorization server or OpenID Provider.

The configuration includes the client credentials that are used to authenticate to the identity provider. The client credentials can be included directly in the configuration, or retrieved in some other way using an expression, described in Expressions.

Usage

{
  "name": string,
  "type": "ClientRegistration",
  "config": {
    "clientId": configuration expression<string>,
    "issuer": Issuer reference,
    "scopes": [ configuration expression<string>, ...],
    "registrationHandler": Handler reference,
    "authenticatedRegistrationHandler": Handler reference,
    "clientSecret": configuration expression<string>, //deprecated
    "clientSecretId": configuration expression<secret-id>, //deprecated
    "jwtExpirationTimeout": duration, //deprecated
    "keystore": reference, //deprecated
    "privateKeyJwtAlias": string, //deprecated
    "privateKeyJwtPassword": string, //deprecated
    "privateKeyJwtSecretId": configuration expression<secret-id>, //deprecated
    "secretsProvider": SecretsProvider reference, //deprecated
    "tokenEndpointAuthMethod": enumeration, //deprecated
    "tokenEndpointAuthSigningAlg": string //deprecated
  }
}

Properties

"name": string, required
The use of the name property to identify a client that is registering with the authorization server is deprecated; use clientId instead. For more information, refer to the Deprecated section of the Release Notes.
"clientId": configuration expression<string>, required

The client_id obtained when registering with the authorization server. See also Expressions.

"issuer": Issuer reference, required

The provider configuration to use for this client registration. Provide either the name of a Issuer object defined in the heap, or an inline Issuer configuration object. See also Issuer.

"scopes": array of configuration expression<strings>, optional

Array of scope strings to present to the user for approval, and include in tokens so that protected resources can make decisions about access.

Default: Empty

"registrationHandler": Handler reference, optional

HTTP client handler to invoke during client registration, to access endpoints that do not require client authentication. Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.

Default: ClientHandler.

"authenticatedRegistrationHandler": Handler reference, optional

HTTP client handler to invoke during client registration, to access endpoints that require client authentication. Configure this property as a Chain, using one of the following filters for client authentication:

{
  "name": "AuthenticatedRegistrationHandler",
  "type": "Chain",
  "config": {
    "handler": "ForgeRockClientHandler",
    "filters": [
      {
        "type": "ClientSecretBasicAuthenticationFilter",
        "config": {
          "clientId": "service-client",
          "clientSecretId": "client.secret.id",
          "secretsProvider" : "SystemAndEnvSecretStore-1",
        }
      }
    ]
  }
}

Default: registrationHandler with no authentication filter.

"clientSecret": _configuration expression<string>, required if tokenEndpointAuthMethod is client_secret_basic or client_secret_post
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The secret required to authenticate the client to the authorization server.

"clientSecretId": _configuration expression<secret-id>, required if tokenEndpointAuthMethod is client_secret_basic or client_secret_post
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the client secret required to authenticate the client to the authorization server.

This secret ID must point to a GenericSecret.

"jwtExpirationTimeout": duration, optional
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

When private_key_jwt is used for authentication, this property specifies the duration for which the JWT is valid.

Default: 1 minute

"keystore": reference, required if private_key_jwt is used
The use of this property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The Java keystore containing the private key that is used to sign the JWT.

Provide the name of a keystore object defined in the heap, or an inline keystore configuration object.

"privateKeyJwtAlias": string, required if private_key_jwt is used
The use of this property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

Name of the private key contained in the keystore.

"privateKeyJwtPassword": string, required if private_key_jwt is used
The use of this property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

Password to access the private key contained in the keystore.

"privateKeyJwtSecretId": configuration expression<secret-id>, required when private_key_jwt is used for client authentication
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the key that is used to sign the JWT.

This secret ID must point to a CryptoKey.

"secretsProvider": SecretsProvider reference, optional
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The SecretsProvider object to query for the client’s GenericSecret. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"tokenEndpointAuthMethod": enumeration, optional
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The authentication method with which a client authenticates to the authorization server or OpenID provider at the token endpoint. For information about client authentication methods, see OpenID Client Authentication. The following client authentication methods are allowed:

  • client_secret_basic: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by using the HTTP Basic authentication scheme, as in the following example:

    POST /oauth2/token HTTP/1.1
    Host: as.example.com
    Authorization: Basic ....
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
    code=...
  • client_secret_post: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by including the client credentials in the request body, as in the following example:

    POST /oauth2/token HTTP/1.1
    Host: as.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&;
    client_id=...&
    client_secret=...&
    code=...
  • private_key_jwt: Clients send a signed JSON Web Token (JWT) to the authorization server. IG builds and signs the JWT, and prepares the request as in the following example:

    POST /token HTTP/1.1
    Host: as.example.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code&
    code=...&
    client_id=<clientregistration_id>&
    client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
    client_assertion=PHNhbWxwOl ... ZT

    If the authorization server doesn’t support private_key_jwt, a dynamic registration falls back on the method returned by the authorization server, for example, client_secret_basic or client_secret_post.

    If tokenEndpointAuthSigningAlg is not configured, the RS256 signing algorithm is used for private_key_jwt.

Consider these points for identity providers:

  • Some providers accept more than one authentication method.

  • If a provider strictly enforces how the client must authenticate, align the authentication method with the provider.

  • If a provider doesn’t support the authentication method, the provider sends an HTTP 400 Bad Request response with an invalid_client error message, according to RFC 6749 The OAuth 2.0 Authorization Framework, section 5.2 .

  • If the authentication method is invalid, the provider sends an IllegalArgumentException.

Default: client_secret_basic

"tokenEndpointAuthSigningAlg": string, optional
This property is deprecated; use authenticatedRegistrationHandler instead. For more information, refer to the Deprecated section of the Release Notes.

The JSON Web Algorithm (JWA) used to sign the JWT that is used to authenticate the client at the token endpoint. The property is used when private_key_jwt is used for authentication.

Use one of the following algorithms:

  • RS256: RSA using SHA-256

  • ES256: ECDSA with SHA-256 and NIST standard P-256 elliptic curve

  • ES384: ECDSA with SHA-384 and NIST standard P-384 elliptic curve

  • ES512: ECDSA with SHA-512 and NIST standard P-521 elliptic curve

Default: RS256

ClientTlsOptions

Configures connections to the TLS-protected endpoint of servers, when IG is client-side.

When IG is client-side, IG sends requests to a proxied application, or requests services from a third-party application. IG is acting as a client of the application, and the application is acting as a server.

Use ClientTlsOptions in ClientHandler, ReverseProxyHandler, and AmService.

Usage

{
  "name": string,
  "type": "ClientTlsOptions",
  "config": {
    "keyManager": [ Key manager reference, ...],
    "trustManager": [ Trust manager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": object,
    "hostnameVerifier": configuration expression<enumeration>
  }
}

Properties

"keyManager": array of key manager references, optional

One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:

Key managers are used to prove the identity of the local peer during TLS handshake, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this IG’s identity to the remote peer (client-side). This is the usual TLS configuration setting (without mTLS).

  • When ClientTlsOptions is used in a ClientHandler or ReverseProxyHandler configuration (client-side), the key managers to which ClientTlsOptions refers are used to prove this IG’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.

Default: None

"trustManager": array of trust manager references, optional

One or more of the following objects to manage IG’s public key certificates:

Trust managers verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), ServerTlsOptions refers to trust managers that verify the remote peer’s identity (client-side). This configuration is used in mTLS scenarios.

  • When ClientTlsOptions is used in a ClientHandler or a ReverseProxyHandler configuration (client-side), ClientTlsOptions refers to trust managers that verify the remote peer’s identity (server-side). This is the usual TLS configuration setting (without mTLS).

If trustManager is not configured, IG uses the default Java truststore to verify the remote peer’s identity. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

Default: None

"sslCipherSuites": array of configuration expression<strings>, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For information about the available cipher suite names, see the documentation for the Java virtual machine (JVM) where you run IG. For Oracle Java, refer to the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": configuration expression<string>, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).

Default: TLS

"sslEnabledProtocols": array of configuration expression<strings>, optional

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

For information about the available protocol names, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of Additional JSSE Standard Names.

Follow these protocol recommendations:

  • Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.

  • If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.

  • Do use deprecated versions SSL 3 or SSL 2.

Default: TLS 1.3, TLS 1.2

"alpn": object, optional

A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.

{
  "alpn": {
    "enabled": configuration expression<boolean>
  }
}
enabled: configuration expression<boolean>, optional
  • true: Enable ALPN. Required for HTTP/2 connections over TLS

  • false: Disable ALPN.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

The method to handle hostname verification for outgoing SSL connections.

For backward compatibility, when a ClientHandler or ReverseProxyHandler includes the deprecated "hostnameVerifier": "ALLOW_ALL" configuration, it takes precedence over this property. A deprecation warning is written to the logs.

Use one of the following values:

  • ALLOW_ALL: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.

    If the SSL endpoint uses a raw IP address rather than a fully-qualified hostname, you must configure this property as ALLOW_ALL.

    To prevent the compromise of TLS connections, use ALLOW_ALL in development mode only. In production, use STRICT.

    The ALLOW_ALL setting allows a certificate issued for one company to be accepted as a valid certificate for another company.
  • STRICT: Match the hostname either as the value of the the first CN, or any of the subject-alt names.

    A wildcard can occur in the CN, and in any of the subject-alt names. Wildcards match one domain level, so *.example.com matches www.example.com but not some.host.example.com.

Default: STRICT

Example

For an example that uses ClientTlsOptions, refer to Configure IG For HTTPS (client-side).

Delegate

Delegates all method calls to a referenced handler, filter, or any object type.

Use a Delegate to decorate referenced objects differently when they are used multiple times in a configuration.

Usage

{
  "filter or handler": {
  "type": "Delegate",
  [decorator reference, ...],
    "config": {
      "delegate": object
    }
  }
}

Example

For an example of how to delegate tasks to ForgeRockClientHandler, and capture IG’s interaction with AM, refer to Decorating IG’s Interactions With AM.

JwtSession

Configures settings for stateless sessions.

Session information is serialized as a secure JWT, that is encrypted and signed, and optionally compressed. The resulting JWT string is placed in a cookie, which contains session attributes as JSON, and a marker for the session timeout.

Use JwtSession to configure stateless sessions as follows:

  • Configure a JwtSession object named Session in the heap of config.json.

    Stateless sessions are created when a request traverses any route or subroute in the configuration. No routes can create stateful sessions.

  • Configure a JwtSession object in the session property of a Route object.

    When a request enters the route, IG builds a new session object for the route. Any child routes inherit the session. The session information is saved/persisted when the response exits the route. For more information, refer to Route.

  • Configure a JwtSession object in the session property of multiple sibling routes in the configuration, using an identical cookie name and cryptographic properties. Sibling routes are in the same configuration, with no ascending hierarchy to each other.

    When a JwtSession object is declared in a route, the session content is available only within that route. With this configuration, sibling routes can read/write in the same session.

Consider the following points when you configure JwtSession:

  • Only JSON-compatible types can be serialized into a JWT and included in a session cookie. Compatible types include primitive JSON structures, lists, arrays, and maps. For more information, refer to http://json.org.

  • The maximum size of a JWT cookie is 4 KB. Because encryption adds overhead, limit the size of any JSON that you store in a cookie. To reduce the JWT cookie size:

    • Use the default true value for the JwtSession property useCompression, to compress the session JWT before it is placed in a cookie.

    • Consider storing large data outside of the session.

  • If an empty session is serialized, the supporting cookie is marked as expired and is effectively discarded.

    To prevent IG from cleaning up empty session cookies, consider adding some information to the session context by using an AssignmentFilter. For an example, refer to Adding info to a session.

  • When HTTP clients perform multiple requests in a session that modify the content, the session information can become inconsistent.

For information about IG sessions, refer to Sessions.

Usage

{
  "name": string,
  "type": "JwtSession",
  "config": {
    "authenticatedEncryptionSecretId": configuration expression<secret-id>,
    "encryptionMethod": configuration expression<string>,
    "cookie": object,
    "sessionTimeout": configuration expression<duration>,
    "persistentCookie": configuration expression<boolean>,
    "secretsProvider": SecretsProvider reference,
    "skewAllowance": configuration expression<duration>,
    "useCompression": configuration expression<boolean>,
    "encryptionSecretId": configuration expression<secret-id>, //deprecated
    "signatureSecretId": configuration expression<secret-id>, //deprecated
    "keystore": Keystore reference, //deprecated
    "alias": string, //deprecated
    "password": configuration expression, //deprecated
    "sharedSecret": string, //deprecated
    "cookieName": string,  //deprecated
    "cookieDomain": string  //deprecated
  }
}

Properties

"authenticatedEncryptionSecretId": configuration expression<secret-id>, optional

The secret ID of the encryption key used to perform authenticated encryption on a JWT. Authenticated encryption encrypts data and then signs it with HMAC, in a single step.

This secret ID must point to a CryptoKey.

Authenticated encryption is achieved with a symmetric encryption key. Therefore, the secret must refer to a symmetric key.

For more information, refer to RFC 5116.

Default: IG generates a default symmetric key for authenticated encryption. Consequently, IG instances cannot share the JWT session.

"encryptionMethod": configuration expression<string>, optional

The algorithm to use for authenticated encryption. For information about allowed encryption algorithms, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.

Default: A256GCM

"cookie": object, optional

The configuration of the cookie used to store the encrypted JWT.

Default: The cookie is treated as a host-based cookie.

{
  "name": configuration expression<string>,
  "domain": configuration expression<string>,
  "httpOnly": configuration expression<boolean>,
  "path": configuration expression<string>,
  "sameSite": configuration expression<enumeration>,
  "secure": configuration expression<boolean>
}
"name" configuration expression<string>, optional

Name of the JWT cookie stored on the user agent. For security, change the default name of cookies.

Default: openig-jwt-session

"domain" configuration expression<string>, optional

Domain from which the JWT cookie can be accessed. When the domain is specified, a JWT cookie can be accessed from different hosts in that domain.

Set a domain only if the user agent is able to re-emit cookies on that domain on its next hop. For example, to re-emit a cookie on the domain .example.com, the user agent must be able to access that domain on its next hop.

Default: The fully qualified hostname of the user agent’s next hop.

"httpOnly": configuration expression<boolean>, optional

Flag to mitigate the risk of client-side scripts accessing protected cookies.

Default: true

"path": configuration expression<string>, optional

Path protected by this session.

Set a path only if the user agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path /home/cdsso, the user agent must be able to access that path on its next hop.

Default: The path of the request that got the Set-Cookie in its response.

"sameSite": configuration expression<enumeration>, optional

Options to manage the circumstances in which a cookie is sent to the server. Use one of the following values to reduce the risk of CSRF attacks:

  • STRICT: Send the cookie only if the request was initiated from the cookie domain. Not case-sensitive.

    Use this value to reduce the risk of cross-site request forgery (CSRF) attacks.

  • LAX: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain. Not case-sensitive.

    Use this value to reduce the risk of cross-site request forgery (CSRF) attacks.

  • NONE: Send the cookie whenever a request is made to the cookie domain. Not case-sensitive.

    With this setting, consider setting secure to true to prevent browsers from rejecting the cookie. For more information, refer to SameSite cookies.

Default: LAX

"secure": configuration expression<boolean>, optional

Flag to limit the scope of the cookie to secure channels.

Set this flag only if the user agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the secure flag, the user agent must be connected to its next hop by HTTPS.

Default: false

"sessionTimeout": configuration expression<duration>, optional

The duration for which a JWT session is valid. If the supporting cookie is persistent, this property also defines the expiry of the cookie.

The value must be above zero. The maximum value is 3650 days (approximately 10 years). If you set a longer duration, IG truncates the duration to 3650 days.

Default: 30 minutes

"persistentCookie": configuration expression<boolean>,optional

Whether or not the supporting cookie is persistent:

  • true: the supporting cookie is a persistent cookie. Persistent cookies are re-emitted by the user agent until their expiration date or until they are deleted.

  • false: the supporting cookie is a session cookie. IG does not specify an expiry date for session cookies. The user agent is responsible for deleting them when it considers that the session is finished (for example, when the browser is closed).

Default: false

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the JWT session signing or encryption keys. For more information, refer to SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"skewAllowance": configuration expression<duration>, optional

The duration to add to the validity period of a JWT to allow for clock skew between different servers. To support a zero-trust policy, the skew allowance is by default zero.

A skewAllowance of 2 minutes affects the validity period as follows:

  • A JWT with an iat of 12:00 is valid from 11:58 on the IG clock.

  • A JWT with an exp 13:00 is expired after 13:02 on the IG clock.

Default: zero

"useCompression": configuration expression boolean, optional

A flag to compress the session JWT before it is placed in a cookie. When a session stores large items, such as tokens, use the default value true to reduce the size of the cookie.

Default: true

"encryptionSecretId": configuration expression<secret-id>, optional
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the encryption key used to encrypt the JWT.

This secret ID must point to a CryptoKey.

"signatureSecretId": configuration expression<secret-id>, optional
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The secret ID of the JWT signature required to sign and verify the JWTs. HMAC-SHA-256 is used to sign JWTs.

This secret ID must point to a GenericSecret.

The value of this attribute must be:

  • Base64-encoded.

  • At least 32 bytes (32 characters)/256 bits long after base64 decoding. If the provided key is too short, an error message is created.

Default: Random data is generated as the key, and the IG instance can verify only the sessions it has created.

"keystore": KeyStore reference, optional
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The keystore holding the key pair with the private key used to encrypt the JWT.

Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline.

Default: When no keystore is specified, IG generates a unique key pair, and stores the key pair in memory. With JWTs encrypted using a unique key pair generated at runtime, IG cannot decrypt the JWTs after a restart, nor can it decrypt such JWTs encrypted by another IG server.

"alias": string, required when keystore is used
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

Alias for the private key.

"password": configuration expression, required when keystore is used
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

The password to read the private key from the keystore.

"sharedSecret": string, optional
The use of this property is deprecated; use authenticatedEncryptionSecretId and encryptionMethod instead. For more information, refer to the Deprecated section of the Release Notes.

Specifies the key used to sign and verify the JWTs.

This attribute is expected to be base-64 encoded. The minimum key size after base-64 decoding is 32 bytes/256 bits (HMAC-SHA-256 is used to sign JWTs). If the provided key is too short, an error message is created.

If this attribute is not specified, random data is generated as the key, and the IG instance can verify only the sessions it has created.

"cookieName": string, optional
The use of this property is deprecated; use cookie instead. For more information, refer to the Deprecated section of the Release Notes.

The name of the JWT cookie stored on the user-agent.

Default: openig-jwt-session

"cookieDomain" string, optional
The use of this property is deprecated; use cookie instead. For more information, refer to the Deprecated section of the Release Notes.

The name of the domain from which the JWT cookie can be accessed.

When the domain is specified, a JWT cookie can be accessed from different hosts in that domain.

Default: The domain is not specified. The JWT cookie can be accessed only from the host where the cookie was created.

Example

For information about configuring a JwtSession with authenticated encryption, see Encrypt JWT sessions.

For information about managing multiple instances of IG in the same deployment, refer to the Installation guide.

More information

For information about IG sessions, refer to Sessions.

KeyManager (deprecated)

This object is deprecated; use SecretsKeyManager instead. For more information, refer to the Deprecated section of the Release Notes.

The configuration of a Java Secure Socket Extension KeyManager to manage private keys for IG. The configuration references the keystore that holds the keys.

When IG acts as a server, it uses a KeyManager to prove its identity to the client. When IG acts as a client, it uses a KeyManager to prove its identity to the server.

Usage

{
  "name": string,
  "type": "KeyManager",
  "config": {
    "keystore": KeyStore reference,
    "passwordSecretId": configuration expression<secret-id>,
    "alg": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "password": string //deprecated
  }
}

Properties

"keystore": KeyStore reference, required

The KeyStore (deprecated) object that references the store for key certificates. When keystore is used in a KeyManager, it queries for private keys; when keystore is used in a TrustManager, it queries for certificates.

Provide either the name of the keystore object defined in the heap, or an inline keystore configuration object.

"passwordSecretId": configuration expression<secret-id>, required

The secret ID of the password required to read private keys from the keystore.

This secret ID must point to a GenericSecret.

"alg": configuration expression<string>, optional

The certificate algorithm to use.

Default: the default for the platform, such as SunX509.

See also Expressions.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for the keystore password. For more information, refer to SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"password": string, required
The use of this property is deprecated; use passwordSecretId instead. For more information, refer to the Deprecated section of the Release Notes.

The password to read private keys from the keystore.

Example

The following example configures a KeyManager that depends on a KeyStore (deprecated) configuration. The KeyManager and KeyStore passwords are provided by Java system properties or environment variables, and retrieved by the SystemAndEnvSecretStore. By default, the password values must be base64-encoded.

{
  "name": "MyKeyManager",
  "type": "KeyManager",
  "config": {
    "keystore": {
      "type": "KeyStore",
      "config": {
        "url": "file://${env['HOME']}/keystore.p12",
        "passwordSecretId": "keymanager.keystore.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore"
      }
    },
    "passwordSecretId": "keymanager.secret.id",
    "secretsProvider": "SystemAndEnvSecretStore"
  }
}

KeyStore (deprecated)

This object is deprecated; use KeyStoreSecretStore instead. For more information, refer to the Deprecated section of the Release Notes.

The configuration for a Java KeyStore, which stores cryptographic private keys and public key certificates.

Legacy keystore types such as JKS and JCEKS are supported but are not secure. Consider using the PKCS#12 keystore type.

Usage

{
  "name": name,
  "type": "KeyStore",
  "config": {
    "url": configuration expression<url>,
    "passwordSecretId": configuration expression<secret-id>,
    "type": configuration expression<string>,
    "secretsProvider": SecretsProvider reference,
    "password": string //deprecated
  }
}

Properties

"url": configuration expression<url>, required

URL to the keystore file.

See also Expressions.

"passwordSecretId": configuration expression<secret-id>, optional

The secret ID of the password required to read private keys from the KeyStore.

This secret ID must point to a GenericSecret.

If the KeyStore is used as a truststore to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field.

Default: No password is set.

See also Expressions.

"type": configuration expression<string>, optional

The secret store type.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for the keystore password. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, refer to Default secrets object.

"password": string, optional
The use of this property is deprecated; use passwordSecretId instead. For more information, refer to the Deprecated section of the Release Notes.

The password to read private keys from the keystore.

If the keystore is used as a truststore to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field.

Default: No password is set.

Example

The following example configures a KeyStore that references the Java KeyStore file $HOME/keystore.p12. The KeyStore password is provided by a Java system property or environment variable, and retrieved by the SystemAndEnvSecretStore. By default, the password value must be base64-encoded.

{
  "name": "MyKeyStore",
  "type": "KeyStore",
  "config": {
    "url": "file://${env['HOME']}/keystore.p12",
    "passwordSecretId": "keystore.secret.id",
    "secretsProvider": "SystemAndEnvSecretStore"
  }
}

Issuer

Describes an OAuth 2.0 Authorization Server or an OpenID Provider that IG can use as a OAuth 2.0 client or OpenID Connect relying party.

An Issuer is generally referenced from a ClientRegistration, described in ClientRegistration.

Usage

{
  "name": string,
  "type": "Issuer",
  "config": {
    "wellKnownEndpoint": configuration expression<url>,
    "authorizeEndpoint": configuration expression<url>,
    "registrationEndpoint": configuration expression<url>,
    "tokenEndpoint": configuration expression<url>,
    "userInfoEndpoint": configuration expression<url>,
    "issuerHandler": Handler reference,
    "issuerRepository": Issuer repository reference,
    "supportedDomains": [ pattern, ... ]
  }
}

Properties

If the provider has a well-known configuration URL as defined for OpenID Connect 1.0 Discovery that returns JSON with at least authorization and token endpoint URLs, then you can specify that URL in the provider configuration. Otherwise, you must specify at least the provider authorization and token endpoint URLs, and optionally the registration endpoint and user info endpoint URLs.

The provider configuration object properties are as follows:

"name": string, required

A name for the provider configuration.

"wellKnownEndpoint": configuration expression<url>, required unless authorizeEndpoint and tokenEndpoint are specified

The URL to the well-known configuration resource as described in OpenID Connect 1.0 Discovery.

"authorizeEndpoint": configuration expression<url>, required unless obtained through wellKnownEndpoint

The URL to the provider’s OAuth 2.0 authorization endpoint.

"registrationEndpoint": configuration expression<url>, optional

The URL to the provider’s OpenID Connect dynamic registration endpoint.

"tokenEndpoint": configuration expression<url>, required unless obtained through wellKnownEndpoint

The URL to the provider’s OAuth 2.0 token endpoint.

"userInfoEndpoint": configuration expression<url>, optional

The URL to the provider’s OpenID Connect UserInfo endpoint.

Default: no UserInfo is obtained from the provider.

"issuerHandler": Handler reference, optional

Invoke this HTTP client handler to communicate with the authorization server.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.

Default: IG uses the default ClientHandler.

See also Handlers, ClientHandler.

"issuerRepository": Issuer repository reference, optional

A repository of OAuth 2.0 issuers, built from discovered issuers and the IG configuration.

Provide the name of an IssuerRepository object defined in the heap.

Default: Look up an issuer repository named IssuerRepository in the heap. If none is explicitly defined, then a default one named IssuerRepository is created in the current route.

See also IssuerRepository.

"supportedDomains": array of patterns, optional

One or more domain patterns to match domain names that are handled by this issuer, used as a shortcut for OpenID Connect discovery before performing OpenID Connect dynamic registration.

In summary when the OpenID Provider is not known in advance, it might be possible to discover the OpenID Provider Issuer based on information provided by the user, such as an email address. The OpenID Connect discovery specification explains how to use WebFinger to discover the issuer. IG can discover the issuer in this way. As a shortcut IG can also use supported domains lists to find issuers already described in the IG configuration.

To use this shortcut, IG extracts the domain from the user input, and looks for an issuer whose supported domains list contains a match.

Supported domains patterns match host names with optional port numbers. Do not specify a URI scheme such as HTTP. IG adds the scheme. For instance, *.example.com matches any host in the example.com domain. You can specify the port number as well as in host.example.com:8443. Patterns must be valid regular expression patterns according to the rules for the Java Pattern class.

Examples

The following example shows an AM issuer configuration for AM. AM exposes a well-known endpoint for the provider configuration, but this example demonstrates use of the other fields:

{
    "name": "openam",
    "type": "Issuer",
    "config": {
        "authorizeEndpoint":
          "https://am.example.com:8443/openam/oauth2/authorize",
        "registration_endpoint":
          "https://am.example.com:8443/openam/oauth2/connect/register",
        "tokenEndpoint":
          "https://am.example.com:8443/openam/oauth2/access_token",
        "userInfoEndpoint":
          "https://am.example.com:8443/openam/oauth2/userinfo",
        "supportedDomains": [ "mail.example.*", "docs.example.com:8443" ]
    }
}

The following example shows an issuer configuration for Google:

{
    "name": "google",
    "type": "Issuer",
    "config": {
        "wellKnownEndpoint":
          "https://accounts.google.com/.well-known/openid-configuration",
        "supportedDomains": [ "gmail.*", "googlemail.com:8052" ]
    }
}

IssuerRepository

Stores OAuth 2 issuers that are discovered or built from the configuration.

It is not normally necessary to change this object. Change it only for the following tasks:

  • To isolate different repositories in the same route.

  • To view the interactions of the well-known endpoint, for example, if the issuerHandler is delegating to another handler.

Usage

{
   "name": string,
   "type": "IssuerRepository",
   "config": {
     "issuerHandler": Handler reference
   }
}

Properties

"issuerHandler": Handler reference, optional

The default handler to fetch OAuth2 issuer configurations from the well-known endpoint.

Provide the name of a Handler object defined in the heap, or an inline Handler configuration object.

Default: ForgeRockClientHandler

JdbcDataSource

Manages connections to a JDBC data source.

To configure the connection pool, add a JdbcDataSource object named AuditService in the route heap.

Usage

{
  "name": string,
  "type": "JdbcDataSource",
  "config": {
    "dataSourceClassName": configuration expression<string>,
    "driverClassName": configuration expression<string>,
    "executor": ScheduledExectutorService reference,
    "jdbcUrl": configuration expression<url>,
    "passwordSecretId": configuration expression<secret-id>,
    "poolName": configuration expression<string>,
    "properties": object,
    "secretsProvider": SecretsProvider reference,
    "username": configuration expression<string>
  }
}

Properties

"dataSourceClassName": configuration expression<string>, optional

The data source class name to use to connect to the database.

Depending on the underlying data source, use either jdbcUrl, or dataSourceClassName with url. See the Properties.

"driverClassName": configuration expression<string>, optional

Class name of the JDBC connection driver. The following examples can be used:

  • MySQL Connector/J: com.mysql.jdbc.Driver

  • H2: org.h2.Driver

This property is optional, but required for older JDBC drivers.

"executor": ScheduledExecutorService reference, optional

A ScheduledExecutorService for maintenance tasks.

"jdbcUrl": configuration expression<url>, optional

The JDBC URL to use to connect to the database.

Depending on the underlying data source, use either jdbcUrl, or dataSourceClassName with url. See the Properties.

"passwordSecretId": configuration expression<secret-id>, required if the database is password-protected

The secret ID of the password to access the database.

This secret ID must point to a GenericSecret.

"poolName": configuration expression<string>, optional

The connection pool name. Use to identify a pool easily for maintenance and monitoring.

"properties": object, optional

Server properties specific to the type of data source being used. The values of the object are evaluated as configuration expression<strings>.

For information about available options, see the data source documentation.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

Default: The route’s default secret service. For more information, see Default secrets object.

"username": configuration expression<string>, optional

The username to access the database.

Example

The following example configures a JdbcDataSource with a dataSourceClassName and url:

"config": {
  "username": "testUser",
  "dataSourceClassName": "org.h2.jdbcx.JdbcDataSource",
  "properties": {
    "url": "jdbc:h2://localhost:3306/auth"
  },
  "passwordSecretId": "database.password",
  "secretsProvider": "MySecretsProvider"
}

The following example configures a JdbcDataSource with jdbcUrl alone:

"config": {
  "username": "testUser",
  "jdbcUrl": "jdbc:h2://localhost:3306/auth",
  "passwordSecretId": "database.password",
  "secretsProvider": "MySecretsProvider"
}

The following example configures a JdbcDataSource with jdbcUrl and driverName. Use this format for older drivers, where jdbcUrl does not provide enough information:

"config": {
  "username": "testUser",
  "jdbcUrl": "jdbc:h2://localhost:3306/auth",
  "driverName": "org.h2.Driver",
  "passwordSecretId": "database.password",
  "secretsProvider": "MySecretsProvider"
}

ProxyOptions

A proxy to which a ClientHandler or ReverseProxyHandler can submit requests, and an AmService can submit Websocket notifications.

Use this object to configure a proxy for AM notifications, and use it in a ClientHandler or ReverseProxyHandler, and again in an AmService notifications block.

Usage

Use one of the following ProxyOption types with the proxyOptions option of ClientHandler, ReverseProxyHandler, and AmService:

  • No proxy.

    {
      "name": string,
      "type": "NoProxyOptions"
    }
  • System defined proxy options.

    {
      "name": string,
      "type": "SystemProxyOptions"
    }
  • Custom proxy

    {
      "name": string,
      "type": "CustomProxyOptions",
      "config": {
        "uri": configuration expression<url>,
        "username": configuration expression<string>,
        "passwordSecretId": configuration expression<secret-id>,
        "secretsProvider": SecretsProvider reference
      }
    }

Default: NoProxyOptions

Properties

"uri": configuration expression<url>, required

URI of a server to use as a proxy for outgoing requests.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object.

"username": configuration expression<string>, required if the proxy requires authentication

Username to access the proxy server.

"passwordSecretId": configuration expression<secret-id>, required if the proxy requires authentication

The secret ID of the password to access the proxy server.

This secret ID must point to a GenericSecret.

"secretsProvider": _ SecretsProvider <reference>, optional_

The SecretsProvider to query for the proxy’s password. For more information, refer to SecretsProvider.

Example

In the following example, the handler passes outgoing requests to the proxy server, which requires authentication:

"handler": {
  "type": "ClientHandler" or "ReverseProxyHandler",
  "config": {
     "proxyOptions": {
       "type": "CustomProxyOptions",
       "config": {
          "uri": "http://proxy.example.com:3128",
          "username": "proxyuser",
          "passwordSecretId": "myproxy.secret.id",
          "secretsProvider": "SystemAndEnvSecretStore"
       }
    }
  }
}

In the following example, the AmService notification service passes Websocket notifications to the proxy server, which requires authentication:

"type": "AmService",
   "config": {
     ...
     "notifications": {
       "proxyOptions": {
         "type": "CustomProxyOptions",
         "config": {
           "uri": "http://proxy.example.com:3128",
           "username": "proxyuser",
           "passwordSecretId": "myproxy.secret.id",
           "secretsProvider": "SystemAndEnvSecretStore"
         }
      }
    }
  }
}

ScheduledExecutorService

An executor service to schedule tasks for execution after a delay or for repeated execution with a fixed interval of time in between each execution. You can configure the number of threads in the executor service and how the executor service is stopped.

The ScheduledExecutorService is shared by all downstream components that use an executor service.

Usage

{
  "name": string,
  "type": "ScheduledExecutorService",
  "config": {
    "corePoolSize": configuration expression<number>,
    "gracefulStop": configuration expression<boolean>,
    "gracePeriod": configuration expression<duration>
  }
}

Properties

"corePoolSize": configuration expression<number>, optional

The minimum number of threads to keep in the pool. If this property is an expression, the expression is evaluated as soon as the configuration is read.

The value must be an integer greater than zero.

Default: 1

"gracefulStop": configuration expression<boolean>, optional

Defines how the executor service stops.

If true, the executor service does the following:

  • Blocks the submission of new jobs.

  • If a grace period is defined, waits for up to that maximum time for submitted and running jobs to finish.

  • Removes submitted jobs without running them.

  • Attempts to end running jobs.

    If false, the executor service does the following:

  • Blocks the submission of new jobs.

  • If a grace period is defined, ignores it.

  • Removes submitted jobs without running them.

  • Attempts to end running jobs.

Default: true

"gracePeriod": configuration expression<duration>, optional

The maximum time that the executor service waits for running jobs to finish before it stops. If this property is an expression, the expression is evaluated as soon as the configuration is read.

If all jobs finish before the grace period, the executor service stops without waiting any longer. If jobs are still running after the grace period, the executor service removes the scheduled tasks, and notifies the running tasks for interruption.

When gracefulStop is false, the grace period is ignored.

Default: 10 seconds

Example

The following example creates a thread pool to execute tasks. When the executor service is instructed to stop, it blocks the submission of new jobs, and waits for up to 10 seconds for submitted and running jobs to complete before it stops. If any jobs are still submitted or running after 10 seconds, the executor service stops anyway and prints a message.

{
    "name": "ExecutorService",
    "comment": "Default service for executing tasks in the background.",
    "type": "ScheduledExecutorService",
    "config": {
        "corePoolSize": 5,
        "gracefulStop": true,
        "gracePeriod": "10 seconds"
    }
}

ServerTlsOptions

When IG is server-side, applications send requests to IG or request services from IG. IG is acting as a server of the application, and the application is acting as a client.

ServerTlsOptions configures the TLS-protected endpoint when IG is server-side. Use ServerTlsOptions in admin.json.

Usage

{
  "type": "ServerTlsOptions",
  "config": {
    "keyManager": [ Key manager reference, ...], // Use "keyManager" or
    "sni": object,                              // "sni", but not both
    "trustManager": [ Trust manager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": object,
    "clientAuth": configuration expression<enumeration>,
  }
}

Properties

Either sni or keyManager must be configured. When both are configured, sni takes precedence and a warning is logged. When neither is configured, an exception is thrown and a warning is logged.

"keyManager": array of key manager references, required if sni is not configured

One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:

Key managers are used to prove the identity of the local peer during TLS handshake, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this IG’s identity to the remote peer (client-side). This is the usual TLS configuration setting (without mTLS).

  • When ClientTlsOptions is used in a ClientHandler or ReverseProxyHandler configuration (client-side), the key managers to which ClientTlsOptions refers are used to prove this IG’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.

Default: None

"trustManager": array of trust manager references, optional

One or more of the following objects to manage IG’s public key certificates:

Trust managers verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), ServerTlsOptions refers to trust managers that verify the remote peer’s identity (client-side). This configuration is used in mTLS scenarios.

  • When ClientTlsOptions is used in a ClientHandler or a ReverseProxyHandler configuration (client-side), ClientTlsOptions refers to trust managers that verify the remote peer’s identity (server-side). This is the usual TLS configuration setting (without mTLS).

If trustManager is not configured, IG uses the default Java truststore to verify the remote peer’s identity. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

Default: None

"sni": object, required if keyManager is not configured

Server Name Indication (SNI) is an extension of the TLS handshake, to serve different secret key and certificate pairs to the TLS connections on different server names. Use this property to host multiple domains on the same machine. For more information, refer to Server Name Indication.

During a TLS handshake, vert.x accesses secret key and certificate pairs synchronously; they are loaded in memory at IG startup, and must be present. You must restart IG to update a secret key and certificate pair.

For an example that uses this property, refer to Serve different certificates for TLS connections to different server names.

{
  "sni": {
    "serverNames": map,
    "defaultSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference
  }
}
serverNames: map, required

A map of one or more data pairs with the format Map<String, String>, where:

  • The key is the name of server provided during TLS handshake, or a configuration expression that evaluates to the name

  • The value is a string representing the secret ID of the servers' secret key/certificate pair. Alternatively, it can be a configuration expression that evaluates to that string.

    The following format is required:

    {
      "serverNames": {
        "configuration expression<string>": "configuration expression<string>",
        ...
      }
    }

    In the following example, the keys and values in the map are strings:

    "serverNames": {
      "app1.example.com": "my.app1.secretId",
      "app2.example.com": "my.app2.secretId",
      "*.test.com": "my.wildcard.test.secretId"
    }

    In the following example, the keys and values in the map are configuration expressions:

    "serverNames": {
      "${server.name.available.at.config.time}" : "${secret.id.available.at.config.time}"
    }

    Note the following points:

    • One server cannot be mapped to multiple certificates.

      IG cannot provide multiple certificates for the same server name, as is allowed by Java’s key managers.

    • Multiple servers can be mapped to one certificate.

      Map server names individually. In the following configuration, both server names use the same certificate:

      "serverNames": {
        "cat.com" : "my.secret.id",
        "dog.org" : "my.secret.id"
      }

      Use the * wildcard in the server name to map groups of server names. In the following configuration, app1.example.com and app2.example.com use the same certificate:

      "serverNames": {
        "*.example.com": "my.wildcard.secret.id"
      }
"defaultSecretId": configuration expression<secret-id>, required

The secret ID representing the certificate to use when an unmapped server name is provided during TLS handshake.

This secret ID must point to a CryptoKey.

For information about how IG manages secrets, refer to Secrets.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for each secret ID. For more information, refer to SecretsProvider.

"sslCipherSuites": array of configuration expression<strings>, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For information about the available cipher suite names, see the documentation for the Java virtual machine (JVM) where you run IG. For Oracle Java, refer to the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": configuration expression<string>, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).

Default: TLS

"sslEnabledProtocols": array of configuration expression<strings>, optional

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

For information about the available protocol names, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of Additional JSSE Standard Names.

Follow these protocol recommendations:

  • Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.

  • If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.

  • Do use deprecated versions SSL 3 or SSL 2.

Default: TLS 1.3, TLS 1.2

"alpn": object, optional

A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.

{
  "alpn": {
    "enabled": configuration expression<boolean>
  }
}
enabled: configuration expression<boolean>, optional
  • true: Enable ALPN. Required for HTTP/2 connections over TLS

  • false: Disable ALPN.

Default: true

"clientAuth": configuration expression<enumeration>, optional

The authentication expected from the client. Use one of the following values:

  • REQUIRED: Require the client to present authentication. If it is not presented, then decline the connection.

  • REQUEST: Request the client to present authentication. If it is not presented, then accept the connection anyway.

  • NONE: Accept the connection without requesting or requiring the client to present authentication.

Default: NONE

TemporaryStorage

Allocates temporary buffers for caching streamed content during request processing. Initially uses memory; when the memory limit is exceeded, switches to a temporary file.

Usage

{
  "name": string,
  "type": "TemporaryStorage",
  "config": {
    "initialLength": configuration expression<number>,
    "memoryLimit": configuration expression<number>,
    "fileLimit": configuration expression<number>,
    "directory": configuration expression<string>
  }
}

Properties

"initialLength": configuration expression<number>, optional

Initial size of the memory buffer.

Default: 8 192 bytes (8 KB). Maximum: The value of "memoryLimit".

"memoryLimit": configuration expression<number>, optional

Maximum size of the memory buffer. When the memory buffer is full, the content is transferred to a temporary file.

Default: 65 536 bytes (64 KB). Maximum: 2 147 483 647 bytes (2 GB).

"fileLimit": configuration expression<number>, optional

Maximum size of the temporary file. If the file is bigger than this value, IG responds with an OverflowException.

Default: 1 073 741 824 bytes (1 GB). Maximum: 2 147 483 647 bytes (2 GB).

"directory": configuration expression<string>, optional

The directory where temporary files are created.

Default: $HOME/.openig/tmp (on Windows,appdata\OpenIG\OpenIG\tmp)

TlsOptions (deprecated)

This object is deprecated; use ClientTlsOptions instead. For more information, refer to the Deprecated section of the Release Notes.

Configures connections to the TLS-protected endpoint of servers, when IG is client-side.

Usage

{
  "name": string,
  "type": "TlsOptions",
  "config": {
    "keyManager": [ Key manager reference, ...],
    "trustManager": [ Trust manager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
  }
}

Properties

"keyManager": array of key manager references references, optional

One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:

Key managers are used to prove the identity of the local peer during TLS handshake, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this IG’s identity to the remote peer (client-side). This is the usual TLS configuration setting (without mTLS).

  • When ClientTlsOptions is used in a ClientHandler or ReverseProxyHandler configuration (client-side), the key managers to which ClientTlsOptions refers are used to prove this IG’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.

Default: None

"trustManager": array of trust manager references, optional

One or more of the following objects to manage IG’s public key certificates:

Trust managers verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), ServerTlsOptions refers to trust managers that verify the remote peer’s identity (client-side). This configuration is used in mTLS scenarios.

  • When ClientTlsOptions is used in a ClientHandler or a ReverseProxyHandler configuration (client-side), ClientTlsOptions refers to trust managers that verify the remote peer’s identity (server-side). This is the usual TLS configuration setting (without mTLS).

If trustManager is not configured, IG uses the default Java truststore to verify the remote peer’s identity. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

Default: None

"sslCipherSuites": array of configuration expression<strings>, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For information about the available cipher suite names, see the documentation for the Java virtual machine (JVM) where you run IG. For Oracle Java, refer to the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": configuration expression<string>, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).

Default: TLS

"sslEnabledProtocols": array of configuration expression<strings>, optional

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

For information about the available protocol names, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of Additional JSSE Standard Names.

Follow these protocol recommendations:

  • Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.

  • If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.

  • Do use deprecated versions SSL 3 or SSL 2.

Default: TLS 1.3, TLS 1.2

TrustManager (deprecated)

This object is deprecated; use SecretsTrustManager instead. For more information, refer to the Deprecated section of the Release Notes.

The configuration of a Java Secure Socket Extension TrustManager to manage trust material (typically X.509 public key certificates) for IG. The configuration references the keystore that holds the trust material.

When IG acts as a client, it uses a trust manager to verify that the server is trusted. When IG acts as a server, it uses a trust manager to verify that the client is trusted.

Usage

{
    "name": string,
    "type": "TrustManager",
    "config": {
      "keystore": KeyStore reference,
      "alg": configuration expression<string>
    }
}

Properties

"keystore": KeyStore reference, required

The KeyStore (deprecated) object that references the store for key certificates. When keystore is used in a KeyManager, it queries for private keys; when keystore is used in a TrustManager, it queries for certificates.

Provide either the name of the keystore object defined in the heap, or an inline keystore configuration object.

"alg": configuration expression<string>, optional

The certificate algorithm to use.

Default: the default for the platform, such as SunX509.

Example

The following example configures a trust manager that depends on a KeyStore configuration. This configuration uses the default certificate algorithm:

{
  "name": "MyTrustManager",
  "type": "TrustManager",
  "config": {
    "keystore": {
      "type": "KeyStore",
      "config": {
        "url": "file://${env['HOME']}/keystore.p12",
        "passwordSecretId": "${system['keypass']}",
        "secretsProvider": "SystemAndEnvSecretStore"
      }
    }
  }
}

TrustAllManager

Blindly trusts all server certificates presented the servers for protected applications. It can be used instead of a TrustManager in test environments to trust server certificates that were not signed by a well-known CA, such as self-signed certificates.

The TrustAllManager is not safe for production use. Use a properly configured TrustManager instead.

Usage

{
    "name": string,
    "type": "TrustAllManager"
}

Example

The following example configures a client handler that blindly trusts server certificates when IG connects to servers over HTTPS:

{
    "name": "BlindTrustClientHandler",
    "type": "ReverseProxyHandler",
    "config": {
        "trustManager": {
            "type": "TrustAllManager"
        }
    }
}

UmaService

The UmaService includes a list of resource patterns and associated actions that define the scopes for permissions to matching resources. When creating a share using the REST API described below, you specify a path matching a pattern in a resource of the UmaService.

Usage

{
    "name": string,
    "type": "UmaService",
    "config": {
        "protectionApiHandler": Handler reference,
        "amService": AmService reference,                    // Use either "amService"
        "wellKnownEndpoint": configuration expression<url>,  // or "wellKnownEndpoint", but not both.
        "resources": [ object, ... ]
    }
}

Properties

"protectionApiHandler": Handler reference, required

The handler to use when interacting with the UMA authorization server to manage resource sets, such as a ClientHandler capable of making an HTTPS connection to the server.

For more information, refer to Handlers.

"amService": AmService reference, required if wellKnownEndpoint is not configured

The AmService heap object to use for the URI to the well-known endpoint for this UMA authorization server. The endpoint is extrapolated from the url property of the AmService, and takes the realm into account.

If the UMA authorization server is AM, use this property to define the endpoint.

If amService is configured, it takes precedence over wellKnownEndpoint.

For more information, refer to Using the well-known UMA endpoint in AM’s User-Managed Access (UMA) 2.0 guide .

See also AmService.

"wellKnownEndpoint": configuration expression<url>, required if amService is not configured

The URI to the well-known endpoint for this UMA authorization server.

If the UMA authorization server is not AM, use this property to define the endpoint.

If amService is configured, it takes precedence over wellKnownEndpoint.

Examples:

  • In this example, the UMA configuration is in the default realm of AM:

    https://am.example.com:8088/openam/uma/.well-known/uma2-configuration
  • In this example, the UMA configuration is in a European customer realm:

    https://am.example.com:8088/openam/uma/realms/root/realms/customer/realms/europe/.well-known/uma2-configuration

For more information, refer to Using the well-known UMA endpoint in AM’s User-Managed Access (UMA) 2.0 guide.

"resources": array of objects, required

Resource objects matching the resources the resource owner wants to share.

Each resource object has the following form:

{
    "pattern": resource pattern,
    "actions": [
        {
            "scopes": [ scope string, ... ],
            "condition": runtime expression<boolean>
        },
        {
            ...
        }
    ]
}

Each resource pattern can represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways:

  1. When registering a resource set, IG uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used.

  2. When responding to an initial request for a resource, IG derives the scopes for the ticket based on the scopes that apply according to the request.

  3. When verifying the RPT, IG checks that all required scopes are encoded in the RPT.

A description of each field follows:

"pattern": pattern, required

A pattern matching resources to be shared by the resource owner, such as .* to match any resource path, and /photos/.* to match paths starting with /photos/.

See also Patterns.

"actions": array of objects, optional

A set of scopes to authorize when the corresponding condition evaluates to true.

"actions": [
  {
    "scopes": [ "#read" ],
    "condition": "${request.method == 'GET'}"
  },
  {
    "scopes": [ "#create" ],
    "condition": "${request.method == 'POST'}"
  }
]
"scopes": array of configuration expression<strings>, optional

One or more scopes that are authorized when the corresponding condition evaluates to true.

For example, the scope #read grants read-access to a resource.

"condition": runtime expression<boolean>, required

When the condition evaluates to true, the corresponding scope is authorized.

For example, the condition ${request.method == 'GET'} is true when reading a resource.

REST API for shares

The REST API for UMA shares is exposed at a registered endpoint. IG logs the paths to registered endpoints when the log level is INFO or finer. Look for messages such as the following in the log:

UMA Share endpoint available at
 '/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share'

To access the endpoint over HTTP or HTTPS, prefix the path with the IG scheme, host, and port to obtain a full URL, such as http://localhost:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share.

The UMA REST API supports create (POST only), read, delete, and query (_queryFilter=true only). For an introduction to common REST APIs, see About ForgeRock Common REST.

In the present implementation, IG does not have a mechanism for persisting shares. When IG stops, the shares are discarded.

For information about API descriptors for the UMA share endpoint, see Understanding IG APIs with API descriptors. For information about Common REST, see About ForgeRock Common REST.

A share object has the following form:

{
    "path": pattern,
    "pat": UMA protection API token (PAT) string,
    "id": unique identifier string,
    "resource_id": unique identifier string,
    "user_access_policy_uri": URI string
}
"path": pattern, required

A pattern matching the path to protected resources, such as /photos/.*.

This pattern must match a pattern defined in the UmaService for this API.

See also Patterns.

"pat": PAT string, required

A PAT granted by the UMA authorization server given consent by the resource owner.

In the present implementation, IG has access only to the PAT, not to any refresh tokens.

"id": unique identifier string, read-only

This uniquely identifies the share. This value is set by the service when the share is created, and can be used when reading or deleting a share.

"resource_id": unique identifier string, read-only

This uniquely identifies the UMA resource set registered with the authorization server. This value is obtained by the service when the resource set is registered, and can be used when setting access policy permissions.

"user_access_policy_uri": URI string, read-only

This URI indicates the location on the UMA authorization server where the resource owner can set or modify access policies. This value is obtained by the service when the resource set is registered.

Copyright © 2010-2023 ForgeRock, all rights reserved.