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

An IG agent profile. 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.

{
  "AmService": {
     "username": configuration expression<string>,
     "passwordSecretId": configuration expression<secret-id>,
     "password": configuration expression<string> //deprecated
   }
}

"username": configuration expression<string>, required

Name of the AM agent profile.

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

The secret ID of the AM 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

More information

org.forgerock.openig.tools.am.AmService

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

Example

See Use AM as a single OpenID Connect provider.

More information

org.forgerock.openig.filter.oauth2.client.ClientRegistration

Issuer, AuthorizationCodeOAuth2ClientFilter

The OAuth 2.0 Authorization Framework

The OAuth 2.0 Authorization Framework: Bearer Token Usage

OpenID Connect

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:

SecretsTrustManager
TrustAllManager
TrustManager (deprecated)

When the TrustManager object is configured, only certificates accessible through that TrustManager are trusted. Default and system certificates are no longer trusted.

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: No trustManager is set, and IG uses the default and system certificates

"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, refer to 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.

More information

org.forgerock.openig.decoration.DelegateHeaplet

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 one or more JWT session cookies. The cookies contain 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 JWT session cookies. Compatible types include primitive JSON structures, lists, arrays, and maps. For more information, refer to http://json.org.
The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, IG automatically splits it into multiple cookies.
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.

The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, IG automatically splits it into multiple cookies.

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.

Compression can undermine the security of encryption. Evaluate this threat according to your use case before you enable compression.

Default: false

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

org.forgerock.openig.session.jwt.JwtSessionManager

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.

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

More information

org.forgerock.openig.security.KeyManagerHeaplet

JSSE Reference guide , KeyStore, TrustManager

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.

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

More information

org.forgerock.openig.security.KeyStoreHeaplet

JSSE Reference guide

KeyManager

TrustManager

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 usually referenced from a 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>,
    "endSessionEndpoint": configuration expression<url>,
    "revocationEndpoint": 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.
"endSessionEndpoint": configuration expression<url>, optional: The URL to the Authorization Server’s end_session_endpoint. In OpenID Connect, when a request accesses this endpoint, IG kills the user session in AM.

Consider the following example endpoint: https://am.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/endSession

For more information, refer to OpenID Connect Session Management.

Default: No endpoint
"revocationEndpoint": configuration expression<url>, optional: The URL to the Authorization Server’s revocation_endpoint. When a request accesses this endpoint, IG revokes access tokens or refresh tokens associated to the current user session in AM.

Consider the following example endpoint: https://am.example.com:8443/openam/oauth2/realms/root/realms/alpha/token/revoke

Default: No endpoint
"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" ]
    }
}

More information

org.forgerock.openig.filter.oauth2.client.Issuer

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

More information

org.forgerock.openig.filter.oauth2.client.IssuerRepository

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.

Default: ScheduledExecutorService.

"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, refer to 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, refer to Default secrets object.

"username": configuration expression<string>, optional

The username to access the database.

Example

For an example that uses JdbcDataSource, refer to Log In With Credentials From a Database and Recording Access Audit Events in a Database.

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

More information

org.forgerock.openig.sql.JdbcDataSourceHeaplet

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

More information

org.forgerock.openig.thread.ScheduledExecutorServiceHeaplet

ScriptableResourceUriProvider

Use a script to return a resource URL to include in policy decision requests to AM. The result of the script must be a string that represents a resource URL. The PolicyEnforcementFilter uses the returned resource URL as a key to identify cached policy decisions.

To increase performance, use ScriptableResourceUriProvider in conjunction with AM policies to maximize the the cache hit ratio.

When a request matches a cached policy decision, IG can reuse the decision without asking AM for a new decision. When caching is disabled, IG must ask AM to make a decision for each request.

Usage

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": configuration expression<string>,
    "file": configuration expression<string>, // Use either "file"
    "source": [ string, ... ],                // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

Properties

For information about properties, refer to Scripts.

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:

SecretsTrustManager
TrustAllManager
TrustManager (deprecated)

When the TrustManager object is configured, only certificates accessible through that TrustManager are trusted. Default and system certificates are no longer trusted.

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

Default: No trustManager is set, and IG uses the default and system certificates

"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, refer to 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

Example

See the following examples that use ServerTlsOptions:

RequestResourceUriProvider

Return a resource URL to include in policy decision requests to AM. The PolicyEnforcementFilter uses the returned resource URL as a key to identify cached policy decisions.

To increase performance, use RequestResourceUriProvider in conjunction with AM policies to maximize the the cache hit ratio.

When a request matches a cached policy decision, IG can reuse the decision without asking AM for a new decision. When caching is disabled, IG must ask AM to make a decision for each request.

Usage

"resourceUriProvider": {
  "type": "RequestResourceUriProvider",
  "config": {
    "useOriginalUri": configuration expression<boolean>,
    "includeQueryParams": configuration expression<boolean>
  }
}

Properties

useOriginalUri: configuration expression<boolean>, optional: When 'true`, use the value of UriRouterContext.originalUri as the resource URL when requesting policy decisions from AM.

When false, use the current Request.uri value. Consider that the value might have been modified by the baseURI of the route or by any other filter executed before the PolicyEnforcementFilter.

Default: false
includeQueryParams: configuration expression<boolean>, optional: When true, include query parameters in the resource URL when requesting a policy decision from AM.

When false, strip all query parameters from the resource URL when requesting a policy decision from AM. To strip some but not all query parameters, use ScriptableResourceUriProvider.

Default: true

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)

More information

org.forgerock.openig.io.TemporaryStorageHeaplet

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:

SecretsTrustManager
TrustAllManager
TrustManager (deprecated)

When the TrustManager object is configured, only certificates accessible through that TrustManager are trusted. Default and system certificates are no longer trusted.

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

Default: No trustManager is set, and IG uses the default and system certificates

"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, refer to 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"
      }
    }
  }
}

More information

org.forgerock.openig.security.TrustManagerHeaplet

JSSE reference guide , KeyManager, KeyStore

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

More information

org.forgerock.openig.security.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 UMA discovery in AM’s User-Managed Access (UMA) 2.0 guide.

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, refer to 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, refer to Understanding IG APIs with API descriptors. For information about Common REST, refer to 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.

More information

User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization

org.forgerock.openig.uma.UmaSharingService

IG 2023.9

Miscellaneous configuration objects

AmService

Usage

Properties

More information

ClientRegistration

Usage

Properties

Example

More information

ClientTlsOptions

Usage

Properties

Example

Delegate

Usage

Example

More information

JwtSession

Usage

Properties

Example

More information

KeyManager (deprecated)

Usage

Properties

Example

More information

KeyStore (deprecated)

Usage

Properties

Example

More information

Issuer

Usage

Properties

Examples

More information

IssuerRepository

Usage

Properties

More information

JdbcDataSource

Usage

Properties

Example

More information

ProxyOptions

Usage

Properties

Example

ScheduledExecutorService

Usage

Properties

Example

More information

ScriptableResourceUriProvider

Usage

Properties

ServerTlsOptions

Usage

Properties

Example

RequestResourceUriProvider

Usage

Properties

TemporaryStorage

Usage

Properties

More information

TlsOptions (deprecated)

Usage

Properties

TrustManager (deprecated)

Usage

Properties

Example

More information

TrustAllManager