IG 7.1.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.

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<uri string>,
     "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.

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

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 WebSocket notification service.

For information, see WebSocket Notifications.

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

Enable or disable 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

tls: ClientTlsOptions reference, optional

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

For more information, see ClientTlsOptions.

Default: Connections to TLS-protected endpoints not configured.

"url": configuration expression<uri string>, required

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

"sessionCache": object, optional

Supported in AM 5.5 when the user manually safelists the AMCtxId session property, and in AM 6 and later versions without additional configuration in AM.

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 string>, 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. Use this property when AM is using CTS-based sessions. AM does not monitor idle time for client-based sessions, and so refresh requests are ignored.

When the SingleSignOnFilter is used for authentication with AM, after a time, AM can view the session as idle even though the 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<string>, optional

Supported with AM 6 and later versions.

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 this property to establish the endpoints for its interaction with AM.

If you use a feature that is supported only in a higher AM version than specifed, a message can be logged or an error thrown. For example, if sessionIdleRefresh is enabled but version is lower than 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 5.0

Configure this property with the correct version number for your AM server.

Default: AM 5.0.

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": expression,
    "clientSecretId": configuration expression<secret-id>,
    "issuer": Issuer reference,
    "registrationHandler": Handler reference,
    "scopes": [ expression, ...],
    "secretsProvider": SecretsProvider reference,
    "tokenEndpointAuthMethod": enumeration,
    "tokenEndpointAuthSigningAlg": string,
    "privateKeyJwtSecretId": configuration expression<secret-id>,
    "claims": map or runtime expression<map>,
    "jwtExpirationTimeout": duration
  }
}

Properties

"name": string, required

A name for the client registration.

"clientId": expression, required

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

"clientSecretId": _configuration expression<secret-id>, required if tokenEndpointAuthMethod is client_secret_basic or client_secret_post

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

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

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

"scopes": array of expressions, optional

OAuth 2.0 scopes to use with this client registration. See also Expressions.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the client secret. For more information, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

"tokenEndpointAuthMethod": enumeration, optional

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

      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

      "privateKeyJwtSecretId": configuration expression<secret-id>, required when private_key_jwt is used for client authentication

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

      "claims": map or runtime expression<map>, optional

      When private_key_jwt is used for authentication, this property specifies the claims used in the authentication. If this property is a map, the structure must have the format Map<String, Object>.

      The JWT can contain the following claim value and other optional claims, where claims that are not understood are ignored:

      "aud": string or array of strings, optional

      The URI of the authorization server that is the intended audience of the token.

      Default: URL of the authorization server token endpoint

      In the following example, the claims include the value aud, which is the URI of the authorization server that is the audience of the token:

      "claims": {
  "aud": "https://myapp.authentication.example.com"
}

      If this property is an expression, its evaluation must yield an object of type Map<String, Object>. In the following example, overrideAudience is declared in the properties and then included in an expression in the claims declaration:

      {
  "properties": {
    "overrideAudience": {
      "aud": "https://myapp.authentication.example.com"
    }
  }
}
    "claims": "${overrideAudience}"
    "jwtExpirationTimeout": duration, optional

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

    Default: 1 minute

Example

The following example shows a client registration for AM. The client credentials are replaced with ****. In the actual configuration include the credentials and protect the configuration file, or obtain the credentials from the environment in a safe way:

{
    "name": "registration",
    "type": "ClientRegistration",
    "config": {
        "clientId": "****",
        "clientSecretId": "****",
        "issuer": {
            "type": "Issuer",
            "config": {
                "wellKnownEndpoint": "http://openam.example.com:8088/openam/oauth2/.well-known/openid-configuration"
            }
        },
        "secretsProvider": "mySystemAndEnvSecretStore",
        "scopes": [
          "openid",
          "profile",
          "email"
        ]
    }
}

More Information

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

Issuer, OAuth2ClientFilter

The OAuth 2.0 Authorization Framework

OAuth 2.0 Bearer Token Usage

OpenID Connect

ClientTlsOptions

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

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

Use ClientTlsOptions in ClientHandler, ReverseProxyHandler, and AmService.

Usage

{
  "name": string,
  "type": "ClientTlsOptions",
  "config": {
    "keyManager": KeyManager reference or [ KeyManager reference, ...],
    "trustManager": TrustManager reference or [ TrustManager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": configuration object
  }
}

Properties

"keyManager": KeyManager reference or array of KeyManager references, optional

One or more KeyManager 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 KeyManagers 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 KeyManagers 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.

Provide the name of one or more of the following objects defined in the heap, or configure one or more of the following objects inline:

Default: keyManager is not configured.

"sslCipherSuites": array of configuration expression<string>, 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). For Oracle Java, see 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<string>, 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, see the documentation for the Java Virtual Machine (JVM). For Oracle Java, see the list of Additional JSSE Standard Names.

Default: Allow any protocol supported by the JVM.

"trustManager": TrustManager reference or array of TrustManager references, optional

One or more TrustManager objects to manage IG’s public key certificates. Trust managers are used to verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the TrustManagers to which ServerTlsOptions refers are used to 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), the TrustManager to which ClientTlsOptions refers are used to 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.

Provide the name of one or more of the following TrustManager objects defined in the heap, or configure one or more of the following TrustManager objects inline: TrustManager, SecretsTrustManager, TrustAllManager

Default: trustManager is not configured.

"alpn": configuration object, optional

Supported only for IG in standalone mode.

Defines how to use 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

Example

{
  "tls": {
    "type": "ClientTlsOptions",
    "config": {
      "sslContextAlgorithm": "TLSv1.2",
      "keyManager": {
        "type": "KeyManager",
        "config": {
          "keystore": {
            "type": "KeyStore",
            "config": {
              "url": "file://${env['HOME']}/keystore.jks",
              "passwordSecretId": "keymanager.keystore.secret.id",
              "secretsProvider": "SystemAndEnvSecretStore"
            }
          },
          "passwordSecretId": "keymanager.secret.id",
          "secretsProvider": "SystemAndEnvSecretStore"
        }
      },
      "trustManager": {
        "type": "TrustManager",
        "config": {
          "keystore": {
            "type": "KeyStore",
            "config": {
              "url": "file://${env['HOME']}/truststore.jks",
              "passwordSecretId": "trustmanager.keystore.secret.id",
              "secretsProvider": "SystemAndEnvSecretStore"
            }
          }
        }
      }
    }
  }
}

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 reference] }
  }
}

Example

For an example of how to delegate tasks to ForgeRockClientHandler, and capture IG’s interaction with AM, see 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 the resulting JWT string is placed in a cookie. The cookie contains the 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, see 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, see 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. 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, see 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, see Sessions.

Usage

{
  "name": string,
  "type": "JwtSession",
  "config": {
    "authenticatedEncryptionSecretId": configuration expression<secret-id>,
    "encryptionMethod": configuration expression<string>,
    "cookie": object,
    "sessionTimeout": duration,
    "persistentCookie": boolean,
    "secretsProvider": SecretsProvider reference,
    "skewAllowance": configuration expression<duration>
  }
}

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.

Authenticated encryption is achieved with a symmetric encryption key. Therefore, the secret must refer to a symmetric key. For more information, see 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, see RFC 7518, section-5.1.

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.

{
  "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 the cookie is sent to the server. The following values are listed in order of strictness, with most strict first:

  • 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. With this setting, consider setting secure to true to prevent browsers from rejecting the cookie. For more information, see 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": 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": 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, see SecretsProvider.

Default: The route’s default secret service. For more information, see 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

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, see the Installation Guide.

More Information

For information about IG sessions, see Sessions.

org.forgerock.openig.jwt.JwtSessionManager

KeyManager

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

Properties

"keystore": KeyStore reference, required

The KeyStore 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.

In web container mode, when ClientHandler or ReverseProxyHandler use keystore, the keystore can be different to that used by the web container.

See also KeyStore.

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

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

"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, see SecretsProvider.

Default: The route’s default secret service. For more information, see Default Secrets Object.

Example

The following example configures a KeyManager that depends on a KeyStore 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.jks",
        "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

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

Usage

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

Properties

"url": configuration expression<uri string>, 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.

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, see Default Secrets Object.

Example

The following example configures a KeyStore that references the Java KeyStore file $HOME/keystore.jks. 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.jks",
    "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 generally referenced from a ClientRegistration, described in ClientRegistration.

Usage

{
  "name": string,
  "type": "Issuer",
  "config": {
    "wellKnownEndpoint": URL string,
    "authorizeEndpoint": URI expression,
    "registrationEndpoint": URI expression,
    "tokenEndpoint": URI expression,
    "userInfoEndpoint": URI expression,
    "issuerHandler": Handler reference,
    "issuerRepository": Issuer repository reference,
    "supportedDomains": [ domain 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": URL string, required unless authorizeEndpoint and tokenEndpoint are specified

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

"authorizeEndpoint": expression, required unless obtained through wellKnownEndpoint

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

See also Expressions.

"registrationEndpoint": expression, optional

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

See also Expressions.

"tokenEndpoint": expression, required unless obtained through wellKnownEndpoint

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

See also Expressions.

"userInfoEndpoint": expression, optional

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

Default: no UserInfo is obtained from the provider.

See also Expressions.

"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

List of patterns matching domain names 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://openam.example.com:8443/openam/oauth2/authorize",
        "registration_endpoint":
          "https://openam.example.com:8443/openam/oauth2/connect/register",
        "tokenEndpoint":
          "https://openam.example.com:8443/openam/oauth2/access_token",
        "userInfoEndpoint":
          "https://openam.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": object,
    "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

The service to schedule the execution of maintenance tasks.

Default: ScheduledExecutorService.

"jdbcUrl": configuration expression<string>, 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.

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

"username": configuration expression<string>, optional

The username to access the database.

Example

For an example that uses JdbcDataSource, see 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

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<integer>,
    "gracefulStop":  configuration expression<boolean>,
    "gracePeriod":  configuration expression<duration>
  }
}

Properties

"corePoolSize": configuration expression<integer>, 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

ServerTlsOptions

Configures the TLS-protected endpoint when IG is server-side, that is when applications send requests to IG, or request services from IG.

Use ServerTlsOptions in admin.json, when IG is running in standalone mode.

Usage

{
  "type": "ServerTlsOptions",
  "config": {
    "keyManager": KeyManager reference or [ KeyManager reference, ...],
    "trustManager": TrustManager reference or [ TrustManager reference, ...],
    "sslCipherSuites": [ configuration expression<string>, ...],
    "sslContextAlgorithm": configuration expression<string>,
    "sslEnabledProtocols": [ configuration expression<string>, ...],
    "alpn": configuration object,
    "clientAuth": configuration expression<enumeration>
  }
}

Properties

"keyManager": _KeyManager reference or array of KeyManager references, optional

One or more KeyManager 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 KeyManagers 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 KeyManagers 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.

Provide the name of one or more of the following objects defined in the heap, or configure one or more of the following objects inline:

Default: keyManager is not configured.

"sslCipherSuites": array of configuration expression<string>, 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). For Oracle Java, see 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<string>, 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, see the documentation for the Java Virtual Machine (JVM). For Oracle Java, see the list of Additional JSSE Standard Names.

Default: Allow any protocol supported by the JVM.

"trustManager": TrustManager reference or array of TrustManager references, optional

One or more TrustManager objects to manage IG’s public key certificates. Trust managers are used to verify the identity of a peer by using certificates, as follows:

  • When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the TrustManagers to which ServerTlsOptions refers are used to 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), the TrustManager to which ClientTlsOptions refers are used to 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.

Provide the name of one or more of the following TrustManager objects defined in the heap, or configure one or more of the following TrustManager objects inline: TrustManager, SecretsTrustManager, TrustAllManager

Default: trustManager is not configured.

"alpn": configuration object, optional

Supported only for IG in standalone mode.

Defines how to use 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

For an example that uses ServerTlsOptions, see Set Up IG for HTTPS (Server-Side) in Standalone Mode.

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

TrustManager

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 TrustManager to verify that the server is trusted. When IG acts as a server, it uses a TrustManager to verify that the client is trusted.

Usage

{
    "name": string,
    "type": "TrustManager",
    "config": {
      "keystore": KeyStore reference,
      "alg": string
    }
}

Properties

"keystore": KeyStore reference, required

The KeyStore 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.

In web container mode, when ClientHandler or ReverseProxyHandler use keystore, the keystore can be different to that used by the web container.

See also KeyStore.

"alg": 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.jks",
        "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.

UMA 2.0 is supported with AM 5.5 and later versions. UMA 1.0 is supported with AM 5.1 and later versions.

Usage

{
    "name": string,
    "type": "UmaService",
    "config": {
        "protectionApiHandler": Handler reference,
        "amService": AmService reference,   // Use either "amService"
        "wellKnownEndpoint": URI string,    // or "wellKnownEndpoint", but not both.
        "resources": [ resource, ... ]
    }
}

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, see 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, see Using the Well-Known UMA Endpoint in AM’s User-Managed Access (UMA) 2.0 Guide .

See also AmService.

"wellKnownEndpoint": URI string, 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.

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

https://openam.example.com:8088/openam/uma/.well-known/uma2-configuration

In this example, the UMA configuration is in a European customer realm:

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

For more information, see Using the Well-Known UMA Endpoint in AM’s User-Managed Access (UMA) 2.0 Guide.

"resources": array of resources, 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 be seen to 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": resource 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 action objects, optional

A set of actions on matching resources that the resource owner can authorize.

When granting permission, the resource owner specifies the action scope. Conditions specify what the scopes mean in concrete terms. A given scope matches a requesting party operation when the corresponding condition evaluates to true.

"scopes": array of scope strings, optional

Scope strings to identify permissions.

For example, #read (read access on a resource).

"condition": runtime expression<boolean>, required

A boolean expression representing the meaning of a scope.

For example, ${request.method == 'GET'} (true when reading a resource).

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

More Information

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

org.forgerock.openig.uma.UmaSharingService

Copyright © 2010-2023 ForgeRock, all rights reserved.