--- title: Miscellaneous configuration objects description: The following objects can be defined in the configuration: component: pinggateway version: 2023.11 page_id: pinggateway:reference:MiscellaneousConfigurationObjects canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/MiscellaneousConfigurationObjects.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2023-10-25T18:01:40Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/MiscellaneousConfigurationObjects.html section_ids: AmService: AmService AmService-usage: Usage AmService-properties: Properties AmService-moreinfo: More information ClientRegistration: ClientRegistration ClientRegistration-usage: Usage ClientRegistration-properties: Properties ClientRegistration-example: Example ClientRegistration-moreinfo: More information ClientTlsOptions: ClientTlsOptions ClientTlsOptions-usage: Usage ClientTlsOptions-properties: Properties ClientTlsOptions-example: Example Delegate: Delegate Delegate-usage: Usage Delegate-example: Example Delegate-moreinfo: More information JwtSession: JwtSession JwtSession-usage: Usage JwtSession-properteis: Properties JwtSession-example: Example JwtSession-moreinfo: More information KeyManager: KeyManager (deprecated) KeyManager-usage: Usage KeyManager-properties: Properties KeyManager-example: Example KeyManager-moreinfo: More information KeyStore: KeyStore (deprecated) KeyStore-usage: Usage KeyStore-properties: Properties KeyStore-example: Example KeyStore-moreinfo: More information Issuer: Issuer Issuer-usage: Usage Issuer-properties: Properties Issuer-examples: Examples Issuer-moreinfo: More information IssuerRepository: IssuerRepository IssuerRepository-usage: Usage IssuerRepository-properties: Properties IssuerRepository-moreinfo: More information JdbcDataSource: JdbcDataSource JdbcDataSource-usage: Usage JdbcDataSource-properties: Properties JdbcDataSource-example: Example JdbcDataSource-moreinfo: More information ProxyOptions: ProxyOptions ProxyOptions-usage: Usage ProxyOptions-properties: Properties ProxyOptions-example: Example ScheduledExecutorService: ScheduledExecutorService ScheduledExecutorService-usage: Usage ScheduledExecutorService-properties: Properties ScheduledExecutorService-example: Example ScheduledExecutorService-moreinfo: More information ScriptableResourceUriProvider: ScriptableResourceUriProvider usage: Usage properties: Properties ServerTlsOptions: ServerTlsOptions ServerTlsOptions-usage: Usage ServerTlsOptions-properties: Properties ServerTlsOptions-example: Example RequestResourceUriProvider: RequestResourceUriProvider usage_2: Usage properties_2: Properties ScriptableIdentityAssertionPluginTechPreview: ScriptableIdentityAssertionPluginTechPreview ScriptableIdentityAssertionPluginTechPreview-usage: Usage ScriptableIdentityAssertionPluginTechPreview-properties: Properties ScriptableIdentityAssertionPluginTechPreview-example: Example ScriptableIdentityAssertionPluginTechPreview-moreinfo: More information TemporaryStorage: TemporaryStorage TemporaryStorage-usage: Usage TemporaryStorage-properties: Properties TemporaryStorage-moreinfo: More information TlsOptions: TlsOptions (deprecated) TlsOptions-usage: Usage TlsOptions-properties: Properties TrustAllManager: TrustAllManager TrustAllManager-usage: Usage TrustAllManager-example: Example TrustAllManager-moreinfo: More information UmaService: UmaService UmaService-usage: Usage UmaService-properties: Properties UmaService-restapi: REST API for shares UmaService-moreinfo: More information --- # 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 ```json { "name": string, "type": "AmService", "config": { "agent": object, "secretsProvider": SecretsProvider reference, "notifications": object, "realm": configuration expression, "amHandler": Handler reference, "sessionCache": object, "sessionIdleRefresh": object, "sessionProperties": [ configuration expression, ... ], "ssoTokenHeader": configuration expression, "url": configuration expression, "version": configuration expression } } ``` ### Properties * `"agent"`: *[object](preface.html#definition-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. ```json { "AmService": { "username": configuration expression, "passwordSecretId": configuration expression, "password": configuration expression //deprecated } } ``` * `"username"`: *configuration expression<[string](preface.html#definition-string)>, required* Name of the AM agent profile. * `"passwordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required* The secret ID of the AM agent password. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). * `"password"`: *configuration expression<[string](preface.html#definition-string)>, required* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated and is not considered secure. Use `passwordSecretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The agent password. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider object to query for the agent password. For more information, see [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, see [Default secrets object](secrets.html#default-secrets-object). * `"realm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The AM realm in which the IG agent is created. Default: `/` (top level realm). * `"amHandler"`: *Handler [reference](preface.html#definition-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: ```json "amHandler": { "type": "Chain", "config": { "handler": "MySecureClientHandler", "filters": [ "TransactionIdOutboundFilter" ] } } ``` Default: `ForgeRockClientHandler` See also [Handlers](Handlers.html) and [ClientHandler](Handlers.html#ClientHandler). * `"notifications"`: *[object](preface.html#definition-object), optional* Configure a WebSocket notification service to subscribe to Websocket notifications from AM. To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap, and refer to it from the `amHandler` object and the `notifications` subproperty `tls`. Alternatively, use `proxyOptions` to share a proxy configuration between the `amHandler` and the notification service. For information, refer to [WebSocket notifications](../maintenance-guide/tuning.html#amservice-websocket). ```json { "notifications": { "enabled": configuration expression, "initialConnectionAttempts": configuration expression, "reconnectDelay": configuration expression, "renewalDelay": configuration expression, "heartbeatInterval": configuration expression, "connectionTimeout": configuration expression, "idleTimeout": configuration expression, "tls": ClientTlsOptions reference, "proxyOptions": ProxyOptions reference, "vertx": object } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag to enable WebSocket notifications. Set to `false` to disable WebSocket notifications. Default: `true` * `initialConnectionAttempts`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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` - `renewalDelay`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The time before automatically renewing a WebSocket connection between IG and AM. IG renews connections transparently. ForgeRock Identity Cloud closes WebSocket connections every 60 minutes. This property is set by default to prevent connection closure by automatically renewing connections every 50 minutes. Set to `0` or `unlimited` to never automatically renew connections. Default: `50 minutes` - `heartbeatInterval`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The interval at which the AmService issues a heartbeat on WebSocket connections. When activity on the connection is low, the heartbeat prevents middleware or policies situated between IG and AM from closing the connection for timeout. Set to zero or unlimited to disable heartbeats. Default: `1 minute` - `connectionTimeout`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The time IG waits to establish a Websocket connection to AM before it considers the attempt as failed. Default: `60 seconds` - `idleTimeout`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The time that a WebSocket connection to AM can be inactive before IG closes it. Default: `unlimited` - `tls`: *ClientTlsOptions [reference](preface.html#definition-reference), optional* | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Use of a TlsOptions reference is deprecated; use ClientTlsOptions instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | Configure options for WebSocket connections to TLS-protected endpoints. Define a [ClientTlsOptions](#ClientTlsOptions) object inline or in the heap. Default: Connections to TLS-protected endpoints are not configured. - `proxyOptions`: *ProxyOptions [reference](preface.html#definition-reference)>, optional* A proxy server to which requests can be submitted. Use this property to relay requests to other parts of the network. For example, use it to submit requests from an internal network to the internet. Provide the name of a [ProxyOptions](ProxyOptions.html) object defined in the heap or an inline configuration. Default: A heap object named `ProxyOptions`. - `vertx`: *[object](preface.html#definition-object), optional* Vert.x-specific configuration for WebSocket connections to AM. Vert.x values are evaluated as configuration expressions. Use the Vert.x options described in [VertxOptions](https://vertx.io/docs/4.5.17/apidocs/io/vertx/core/VertxOptions.html). * `"url"`: *configuration expression<[url](preface.html#definition-url)>, required* The URL of the AM service. When AM is running locally, this value could be `https://am.example.com/openam`. When AM is running in the ForgeRock Identity Cloud, this value could be `https://myTenant.forgeblocks.com/am`. * `"sessionCache"`: *[object](preface.html#definition-object), optional* In AM, if the realm includes a customized session property safelist, include `AMCtxId` in the list of properties. The customized session property safelist overrides the global session property safelist. Enable and configure caching of session information from AM, based on *Caffeine*. For more information, see the GitHub entry, [Caffeine](https://github.com/ben-manes/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. ```json { "sessionCache": { "enabled": configuration expression, "executor": Executor service reference, "maximumSize": configuration expression, "maximumTimeToCache": configuration expression, "onNotificationDisconnection": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Enable caching. Default: `false` * `executor`: *Executor service [reference](preface.html#definition-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](preface.html#definition-number)>, optional* The maximum number of entries the cache can contain. Default: Unlimited/unbound. * `maximumTimeToCache`: *configuration expression<[duration](preface.html#definition-duration)>, optional* The maximum duration for which to cache session info. Consider setting this duration to be less than the idle timeout of AM. If `maximumTimeToCache` is longer than `maxSessionExpirationTime` from SessionInfo, `maxSessionExpirationTime` is used. Default: * When `sessionIdleRefresh` is set, idle timeout of AM minus 30 seconds. * When `sessionIdleRefresh` is not set, `maxSessionExpirationTime`, from SessionInfo. * `onNotificationDisconnection`: *configuration expression<[enumeration](preface.html#definition-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](preface.html#definition-object), optional* *(From AM 6.5.3.)* Enable and configure periodic refresh of idle sessions. When this property is enabled, IG requests session refresh: * The first time IG gets an SSO token from AM, irrespective of the age of the token * When `sessionIdleRefresh.interval` has elapsed Use this property when AM is using CTS-based sessions. AM does not monitor idle time for client-side sessions, and so refresh requests are ignored. When the SingleSignOnFilter is used for authentication with AM, AM can view a session as idle even though a user continues to interact with IG. The user session eventually times out and the user must re-authenticate. When the SingleSignOnFilter filter is used with the PolicyEnforcementFilter, the session is refreshed each time IG requests a policy decision from AM. The session is less likely to become idle, and this property less required. ```json { "sessionIdleRefresh": { "enabled": configuration expression, "interval": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Enable refresh of idle sessions. Default: `false` * `interval`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Duration to wait after a session becomes idle before requesting a session refresh. Consider setting the refresh interval in line with the latest access time update frequency of AM. For example, if IG requests a refresh every 60 seconds, but the update frequency of AM is 5 minutes, AM ignores most of the IG requests. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Each session refresh must be reflected in the AM core token service. Setting the interval to a duration lower than one minute can adversely impact AM performance. | Default: `5 minutes` * `"sessionProperties"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* The list of user session properties to retrieve from AM by the [SessionInfoFilter](Filters.html#SessionInfoFilter). Default: All available session properties are retrieved from AM. * `"ssoTokenHeader"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-string)>, optional* The version number of the AM server. IG uses the AM version to establish endpoints for its interaction with AM. The AM version is derived as follows, in order of precedence: * Discovered value: AmService discovers the AM version. If `version` is configured with a different value, AmService ignores the value of `version` and issues a warning. * Value in `version`: AmService cannot discover the AM version, and `version` is configured. * Default value of AM 6: AmService cannot discover the AM version, and `version` is not configured. If you use a feature that is supported only in a higher AM version than discovered or specifed, a message can be logged or an error thrown. For example, if `sessionIdleRefresh` is enabled but the AM version is below the required AM 6.5.3, an error like the following is logged: ``` sessionIdleRefresh is only supported with AM version 6.5.3 and above, the configured AM version is 6 ``` Default: AM 6. ### More information [org.forgerock.openig.tools.am.AmService](../_attachments/apidocs/org/forgerock/openig/tools/am/AmService.html) ## 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](Expressions.html#Expressions). ### Usage ```json { "name": string, "type": "ClientRegistration", "config": { "clientId": configuration expression, "issuer": Issuer reference, "scopes": [ configuration expression, ...], "registrationHandler": Handler reference, "authenticatedRegistrationHandler": Handler reference, "clientSecret": configuration expression, //deprecated "clientSecretId": configuration expression, //deprecated "jwtExpirationTimeout": duration, //deprecated "keystore": reference, //deprecated "privateKeyJwtAlias": string, //deprecated "privateKeyJwtPassword": string, //deprecated "privateKeyJwtSecretId": configuration expression, //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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | * `"clientId"`: *configuration expression<[string](preface.html#definition-string)>, required* The `client_id` obtained when registering with the Authorization Server. See also [Expressions](Expressions.html#Expressions). * `"issuer"`: *Issuer [reference](preface.html#definition-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](#Issuer). * `"scopes"`: *array of configuration expression<[strings](preface.html#definition-string)>, 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](preface.html#definition-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](Handlers.html#ClientHandler). * `"authenticatedRegistrationHandler"`: *Handler [reference](preface.html#definition-reference), optional* HTTP client handler to invoke during client registration, to access endpoints that require client authentication. Configure this property as a [Chain](Handlers.html#Chain), using one of the following filters for client authentication: * [ClientSecretBasicAuthenticationFilter](Filters.html#ClientSecretBasicAuthenticationFilter) * [ClientSecretPostAuthenticationFilter](Filters.html#ClientSecretPostAuthenticationFilter) * [EncryptedPrivateKeyJwtClientAuthenticationFilter](Filters.html#EncryptedPrivateKeyJwtClientAuthenticationFilter) * [PrivateKeyJwtClientAuthenticationFilter](Filters.html#PrivateKeyJwtClientAuthenticationFilter) ```json { "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\, 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The secret required to authenticate the client to the Authorization Server. * `"clientSecretId"`: \_configuration expression\, 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../security-guide/keys.html#secret-types). * `"jwtExpirationTimeout"`: *duration, optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use `authenticatedRegistrationHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | Password to access the private key contained in the keystore. * `"privateKeyJwtSecretId"`: *configuration expression\, required when `private_key_jwt` is used for client authentication* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use `authenticatedRegistrationHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../security-guide/keys.html#secret-types). * `"secretsProvider"`: *SecretsProvider reference, optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use `authenticatedRegistrationHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The SecretsProvider object to query for the client's [GenericSecret](../security-guide/keys.html#secret-types). For more information, see [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). * `"tokenEndpointAuthMethod"`: *enumeration, optional* | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated; use `authenticatedRegistrationHandler` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](http://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). 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: ```http 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: ```http 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: ```http POST /token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=...& client_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 ](https://tools.ietf.org/html/rfc6749#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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../gateway-guide/oidc.html#iodc-am). ### More information [org.forgerock.openig.filter.oauth2.client.ClientRegistration](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/ClientRegistration.html) [Issuer](#Issuer), [AuthorizationCodeOAuth2ClientFilter](Filters.html#AuthorizationCodeOAuth2ClientFilter) [The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) [The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750) [OpenID Connect](http://openid.net/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](Handlers.html#ClientHandler), [ReverseProxyHandler](Handlers.html#ReverseProxyHandler), and [AmService](#AmService). ### Usage ```json { "name": string, "type": "ClientTlsOptions", "config": { "keyManager": [ Key manager reference, ...], "trustManager": [ Trust manager reference, ...], "sslCipherSuites": [ configuration expression, ...], "sslContextAlgorithm": configuration expression, "sslEnabledProtocols": [ configuration expression, ...], "alpn": object, "hostnameVerifier": configuration expression } } ``` ### Properties * `"keyManager"`: *array of key manager [references](preface.html#definition-reference), 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: * [SecretsKeyManager](secrets.html#SecretsKeyManager) * [KeyManager (deprecated)](KeyManager.html) 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](preface.html#definition-reference), optional* One or more of the following objects to manage IG's public key certificates: * [SecretsTrustManager](SecretsTrustManager.html) * [TrustAllManager](TrustAllManager.html) * [TrustManager (deprecated)](TrustManager.html) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](preface.html#definition-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, 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](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#jsse-cipher-suite-names). Default: Allow any cipher suite supported by the JVM. * `"sslContextAlgorithm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The `SSLContext` algorithm name, as listed in the table of [SSLContext Algorithms](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#sslcontext-algorithms) for the Java Virtual Machine (JVM). Default: `TLS` * `"sslEnabledProtocols"`: *array of configuration expression<[strings](preface.html#definition-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, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of [Additional JSSE Standard Names](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#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](preface.html#definition-object), optional* A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections. ```json { "alpn": { "enabled": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* * `true`: Enable ALPN. Required for HTTP/2 connections over TLS * `false`: Disable ALPN. Default: `true` * `"hostnameVerifier"`: *configuration expression<[enumeration](preface.html#definition-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)](../installation-guide/securing-connections.html#client-side-https). ## 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 ```json { "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](../configure/decorators.html#decorators-ig-am). ### More information [org.forgerock.openig.decoration.DelegateHeaplet](../_attachments/apidocs/org/forgerock/openig/decoration/DelegateHeaplet.html) ## 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](Handlers.html#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 . * 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](Filters.html#AssignmentFilter-example-addinfo). * 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](../about/about-sessions.html). ### Usage ```json { "name": string, "type": "JwtSession", "config": { "authenticatedEncryptionSecretId": configuration expression, "encryptionMethod": configuration expression, "cookie": object, "sessionTimeout": configuration expression, "persistentCookie": configuration expression, "secretsProvider": SecretsProvider reference, "skewAllowance": configuration expression, "useCompression": configuration expression, "encryptionSecretId": configuration expression, //deprecated "signatureSecretId": configuration expression, //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](preface.html#definition-secretid)>, 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](../security-guide/keys.html#secret-types). 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](https://datatracker.ietf.org/doc/html/rfc5116). Default: IG generates a default symmetric key for authenticated encryption. Consequently, IG instances cannot share the JWT session. * `"encryptionMethod"`: *configuration expression<[string](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc7518#section-5.1). Default: A256GCM * `"cookie"`: *[object](preface.html#definition-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. ```json { "name": configuration expression, "domain": configuration expression, "httpOnly": configuration expression, "path": configuration expression, "sameSite": configuration expression, "secure": configuration expression } ``` * `"name"` *configuration expression<[string](preface.html#definition-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](preface.html#definition-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](preface.html#definition-boolean)>, optional* Flag to mitigate the risk of client-side scripts accessing protected cookies. Default: `true` * `"path"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite). Default: `LAX` - `"secure"`: *configuration expression<[boolean](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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](preface.html#definition-reference), optional* The SecretsProvider object to query for the JWT session signing or encryption keys. For more information, refer to [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). - `"skewAllowance"`: *configuration expression<[duration](preface.html#definition-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](preface.html#definition-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\, optional* | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `authenticatedEncryptionSecretId` and `encryptionMethod` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../security-guide/keys.html#secret-types). - `"signatureSecretId"`: *configuration expression\, optional* | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `authenticatedEncryptionSecretId` and `encryptionMethod` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../security-guide/keys.html#secret-types). 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) 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](../installation-guide/jwtsession-using.html#jwtsession-encrypt). For information about managing multiple instances of IG in the same deployment, refer to the [Installation guide](../installation-guide/preface.html#preface). ### More information For information about IG sessions, refer to [Sessions](../about/about-sessions.html). ## KeyManager (deprecated) | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This object is deprecated; use [SecretsKeyManager](SecretsKeyManager.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The configuration of a Java Secure Socket Extension [KeyManager](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/javax/net/ssl/KeyManager.html) 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 ```json { "name": string, "type": "KeyManager", "config": { "keystore": KeyStore reference, "passwordSecretId": configuration expression, "alg": configuration expression, "secretsProvider": SecretsProvider reference, "password": string //deprecated } } ``` ### Properties * `"keystore"`: *KeyStore [reference](preface.html#definition-reference), required* The [KeyStore (deprecated)](KeyStore.html) 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](preface.html#definition-secretid)>, required* The secret ID of the password required to read private keys from the keystore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). * `"alg"`: *configuration expression<[string](preface.html#definition-string)>, optional* The certificate algorithm to use. Default: the default for the platform, such as `SunX509`. See also [Expressions](Expressions.html#Expressions). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider to query for the keystore password. For more information, refer to [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). * `"password"`: *string, required* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `passwordSecretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The password to read private keys from the keystore. ### Example The following example configures a KeyManager that depends on a [KeyStore (deprecated)](KeyStore.html) 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. ```json { "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](../_attachments/apidocs/org/forgerock/openig/security/KeyManagerHeaplet.html) [JSSE Reference guide ](https://docs.oracle.com/en/java/javase/17/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-93DEEE16-0B70-40E5-BBE7-55C3FD432345), [KeyStore (deprecated)](KeyStore.html), [TrustManager (deprecated)](TrustManager.html) ## KeyStore (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This object is deprecated; use [KeyStoreSecretStore](KeyStoreSecretStore.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The configuration for a Java [KeyStore](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/security/KeyStore.html), 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 ```json { "name": name, "type": "KeyStore", "config": { "url": configuration expression, "passwordSecretId": configuration expression, "type": configuration expression, "secretsProvider": SecretsProvider reference, "password": string //deprecated } } ``` ### Properties * `"url"`: *configuration expression<[url](preface.html#definition-url)>, required* URL to the keystore file. See also [Expressions](Expressions.html#Expressions). * `"passwordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, optional* The secret ID of the password required to read private keys from the KeyStore. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). 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](Expressions.html#Expressions). * `"type"`: *configuration expression<[string](preface.html#definition-string)>, optional* The secret store type. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The SecretsProvider to query for the keystore password. For more information, see [SecretsProvider](secrets.html#SecretsProvider). Default: The route's default secret service. For more information, refer to [Default secrets object](secrets.html#default-secrets-object). * `"password"`: *string, optional* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The use of this property is deprecated; use `passwordSecretId` instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The password to read private keys from the keystore. If the keystore is used as a truststore to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field. Default: No password is set. ### Example The following example configures a KeyStore that references the Java KeyStore file `$HOME/keystore.p12`. The KeyStore password is provided by a Java system property or environment variable, and retrieved by the SystemAndEnvSecretStore. By default, the password value must be base64-encoded. ```json { "name": "MyKeyStore", "type": "KeyStore", "config": { "url": "file://${env['HOME']}/keystore.p12", "passwordSecretId": "keystore.secret.id", "secretsProvider": "SystemAndEnvSecretStore" } } ``` ### More information [org.forgerock.openig.security.KeyStoreHeaplet](../_attachments/apidocs/org/forgerock/openig/security/KeyStoreHeaplet.html) [JSSE Reference guide](https://docs.oracle.com/en/java/javase/17/security/java-secure-socket-extension-jsse-reference-guide.html#GUID-93DEEE16-0B70-40E5-BBE7-55C3FD432345) [KeyManager](KeyManager.html) [TrustManager](TrustManager.html) ## 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](#ClientRegistration). ### Usage ```json { "name": string, "type": "Issuer", "config": { "wellKnownEndpoint": configuration expression, "authorizeEndpoint": configuration expression, "registrationEndpoint": configuration expression, "tokenEndpoint": configuration expression, "userInfoEndpoint": configuration expression, "endSessionEndpoint": configuration expression, "revocationEndpoint": configuration expression, "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](preface.html#definition-string), required* A name for the provider configuration. * `"wellKnownEndpoint"`: *configuration expression<[url](preface.html#definition-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](preface.html#definition-url)>, required unless obtained through wellKnownEndpoint* The URL to the provider's OAuth 2.0 authorization endpoint. * `"registrationEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, optional* The URL to the provider's OpenID Connect dynamic registration endpoint. * `"tokenEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, required unless obtained through wellKnownEndpoint* The URL to the provider's OAuth 2.0 token endpoint. * `"userInfoEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, optional* The URL to the provider's OpenID Connect UserInfo endpoint. Default: no UserInfo is obtained from the provider. * `"endSessionEndpoint"`: *configuration expression<[url](preface.html#definition-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](https://openid.net/specs/openid-connect-session-1_0-10.html). Default: No endpoint * `"revocationEndpoint"`: *configuration expression<[url](preface.html#definition-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](preface.html#definition-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](Handlers.html), [ClientHandler](Handlers.html#ClientHandler). - `"issuerRepository"`: *Issuer repository [reference](preface.html#definition-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](#IssuerRepository). * `"supportedDomains"`: *array of [patterns](preface.html#definition-pattern), optional* One or more domain patterns to match domain names that are handled by this issuer, used as a shortcut for [OpenID Connect discovery](http://openid.net/specs/openid-connect-discovery-1_0.html) before performing [OpenID Connect dynamic registration](http://openid.net/specs/openid-connect-registration-1_0.html). 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](https://www.rfc-editor.org/rfc/rfc7033) 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](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/regex/Pattern.html) 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: ```json { "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: ```json { "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](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/Issuer.html) ## 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 ```json { "name": string, "type": "IssuerRepository", "config": { "issuerHandler": Handler reference } } ``` ### Properties * `"issuerHandler"`: *Handler [reference](preface.html#definition-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](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/IssuerRepository.html) ## JdbcDataSource Manages connections to a JDBC data source. To configure the connection pool, add a JdbcDataSource object named `AuditService` in the route heap. ### Usage ```json { "name": string, "type": "JdbcDataSource", "config": { "dataSourceClassName": configuration expression, "driverClassName": configuration expression, "executor": ScheduledExectutorService reference, "jdbcUrl": configuration expression, "passwordSecretId": configuration expression, "poolName": configuration expression, "properties": object, "secretsProvider": SecretsProvider reference, "username": configuration expression } } ``` ### Properties * `"dataSourceClassName"`: *configuration expression<[string](preface.html#definition-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](#JdbcDataSource-properties). * `"driverClassName"`: *configuration expression<[string](preface.html#definition-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](preface.html#definition-reference), optional* A ScheduledExecutorService for maintenance tasks. Default: [ScheduledExecutorService](#ScheduledExecutorService). * `"jdbcUrl"`: *configuration expression<[url](preface.html#definition-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](#JdbcDataSource-properties). * `"passwordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, 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](../security-guide/keys.html#secret-types). * `"poolName"`: *configuration expression<[string](preface.html#definition-string)>, optional* The connection pool name. Use to identify a pool easily for maintenance and monitoring. * `"properties"`: *[object](preface.html#definition-object), optional* Server properties specific to the type of data source being used. The values of the object are evaluated as configuration expression<[strings](preface.html#definition-string)>. For information about available options, refer to the data source documentation. * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), optional* The [SecretsProvider](secrets.html#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](secrets.html#default-secrets-object). * `"username"`: *configuration expression<[string](preface.html#definition-string)>, optional* The username to access the database. ### Example For an example that uses JdbcDataSource, refer to [Log In With Credentials From a Database](../gateway-guide/sso-cdsso.html#credentials-database) and [Recording Access Audit Events in a Database](../maintenance-guide/auditing.html#audit-jdbc). The following example configures a JdbcDataSource with a `dataSourceClassName` and `url`: ```json "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: ```json "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: ```json "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](../_attachments/apidocs/org/forgerock/openig/sql/JdbcDataSourceHeaplet.html) ## ProxyOptions A proxy to which a [ClientHandler](ClientHandler.html) or [ReverseProxyHandler](ReverseProxyHandler.html) can submit requests, and an [AmService](AmService.html) 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](ClientHandler.html), [ReverseProxyHandler](ReverseProxyHandler.html), and [AmService](AmService.html): * No proxy. ```json { "name": string, "type": "NoProxyOptions" } ``` * System defined proxy options. ```json { "name": string, "type": "SystemProxyOptions" } ``` * Custom proxy ```json { "name": string, "type": "CustomProxyOptions", "config": { "uri": configuration expression, "username": configuration expression, "passwordSecretId": configuration expression, "secretsProvider": SecretsProvider reference } } ``` Default: NoProxyOptions ### Properties * `"uri"`: *configuration expression<[url](preface.html#definition-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](preface.html#definition-string)>, required if the proxy requires authentication* Username to access the proxy server. * `"passwordSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, 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](../security-guide/keys.html#secret-types). * `"secretsProvider"`: \_ SecretsProvider <[reference](preface.html#definition-reference)>, optional\_ The [SecretsProvider](secrets.html#SecretsProvider) to query for the proxy's password. For more information, refer to [SecretsProvider](secrets.html#SecretsProvider). ### Example In the following example, the handler passes outgoing requests to the proxy server, which requires authentication: ```json "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: ```json "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 ```json { "name": string, "type": "ScheduledExecutorService", "config": { "corePoolSize": configuration expression, "gracefulStop": configuration expression, "gracePeriod": configuration expression } } ``` ### Properties * `"corePoolSize"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-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. ```json { "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](../_attachments/apidocs/org/forgerock/openig/thread/ScheduledExecutorServiceHeaplet.html) ## 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](PolicyEnforcementFilter.html) 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 ```json "resourceUriProvider": { "type": "ScriptableResourceUriProvider", "config": { "type": configuration expression, "file": configuration expression, // Use either "file" "source": [ string, ... ], // or "source", but not both. "args": object, "clientHandler": Handler reference } } ``` ### Properties For information about properties, refer to [Scripts](Scripts.html). ## 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 ```json { "type": "ServerTlsOptions", "config": { "keyManager": [ Key manager reference, ...], // Use "keyManager" or "sni": object, // "sni", but not both "trustManager": [ Trust manager reference, ...], "sslCipherSuites": [ configuration expression, ...], "sslContextAlgorithm": configuration expression, "sslEnabledProtocols": [ configuration expression, ...], "alpn": object, "clientAuth": configuration expression, } } ``` ### 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](preface.html#definition-reference), 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: * [SecretsKeyManager](secrets.html#SecretsKeyManager) * [KeyManager (deprecated)](KeyManager.html) 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](preface.html#definition-reference), optional* One or more of the following objects to manage IG's public key certificates: * [SecretsTrustManager](SecretsTrustManager.html) * [TrustAllManager](TrustAllManager.html) * [TrustManager (deprecated)](TrustManager.html) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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 * `"sni"`: *[object](preface.html#definition-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](https://www.rfc-editor.org/rfc/rfc6066.html#page-6). 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](../installation-guide/envvar-sysprop.html#standalone-https-sni). ```json { "sni": { "serverNames": map, "defaultSecretId": configuration expression, "secretsProvider": SecretsProvider reference } } ``` * `serverNames`: *[map](preface.html#definition-map), required* A map of one or more data pairs with the format `Map`, 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: ```json { "serverNames": { "configuration expression": "configuration expression", ... } } ``` In the following example, the keys and values in the map are strings: ```json "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: ```json "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: ```json "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: ```json "serverNames": { "*.example.com": "my.wildcard.secret.id" } ``` * `"defaultSecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, 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](../security-guide/keys.html#secret-types). For information about how IG manages secrets, refer to [About secrets](../security-guide/keys.html#about-secrets). * `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required* The SecretsProvider to query for each secret ID. For more information, refer to [SecretsProvider](secrets.html#SecretsProvider). * `"sslCipherSuites"`: *array of configuration expression<[strings](preface.html#definition-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, 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](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#jsse-cipher-suite-names). Default: Allow any cipher suite supported by the JVM. * `"sslContextAlgorithm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The `SSLContext` algorithm name, as listed in the table of [SSLContext Algorithms](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#sslcontext-algorithms) for the Java Virtual Machine (JVM). Default: `TLS` * `"sslEnabledProtocols"`: *array of configuration expression<[strings](preface.html#definition-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, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of [Additional JSSE Standard Names](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#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](preface.html#definition-object), optional* A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections. ```json { "alpn": { "enabled": configuration expression } } ``` * `enabled`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* * `true`: Enable ALPN. Required for HTTP/2 connections over TLS * `false`: Disable ALPN. Default: `true` * `"clientAuth"`: *configuration expression<[enumeration](preface.html#definition-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: * [Set up IG for HTTPS (server-side)](../gateway-guide/oauth2.html#mtls-ig-deployment-standalone) * [Serve different certificates for TLS connections to different server names](../installation-guide/envvar-sysprop.html#standalone-https-sni) ## RequestResourceUriProvider Return a resource URL to include in policy decision requests to AM. The [PolicyEnforcementFilter](PolicyEnforcementFilter.html) 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 ```json "resourceUriProvider": { "type": "RequestResourceUriProvider", "config": { "useOriginalUri": configuration expression, "includeQueryParams": configuration expression } } ``` ### Properties * `useOriginalUri`: *configuration expression<[boolean](preface.html#definition-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](preface.html#definition-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](ScriptableResourceUriProvider.html). Default: `true` ## ScriptableIdentityAssertionPluginTechPreview An out-of-the box implementation of [IdentityAssertionPluginTechPreview](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionPluginTechPreview.html). Use with an [IdentityAssertionHandlerTechPreview](Handlers.html#IdentityAssertionHandlerTechPreview) for local processing, such as authentication. The plugin returns [IdentityAssertionClaims](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionClaims.html) to include in the outgoing JWT sent to Identity Cloud. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview are available in [Technology preview](https://docs.pingidentity.com/pinggateway/release-notes/stability.html#interface-stability). They aren't yet supported, may be functionally incomplete, and are subject to change without notice. | The script must: * Access the context, request, and claims of an incoming JWT, where the claims are available under the name `incomingClaims`. * Return an `IdentityAssertionClaims` containing the assertions to add to the outgoing JWT sent to Identity Cloud. ### Usage ```json { "name": string, "type": "ScriptableIdentityAssertionPluginTechPreview", "config": { "preProcessingFilter": Filter reference, "type": configuration expression, "file": configuration expression, // Use either "file" "source": [ string, ... ], // or "source", but not both "args": map, "clientHandler": Handler reference } } ``` ### Properties For information about other properties for ScriptableIdentityAssertionPluginTechPreview, refer to [Scripts](Scripts.html). * `"preProcessingFilter"`: *\_Filter [reference](preface.html#definition-reference), required* A [Filter](Filters.html) to perform user defined actions, such as local authentication and/or authorization. The Filter can be used to process the request before it reaches the script. ### Example The following example applies a `preProcessingFilter` that uses a ScriptableFilter to test whether the user is authenticated. If the user isn't authenticated, the request passes to another script to manage authentication. ``` { "name": "BasicAuthScriptablePlugin", "type": "ScriptableIdentityAssertionPluginTechPreview", "config": { "type": "application/x-groovy", "source": [ "import org.forgerock.openig.handler.assertion.IdentityAssertionClaims", "import org.forgerock.openig.handler.assertion.IdentityAssertionException", "if (request.headers.authorization != null && request.headers.authorization.values[0] == 'Basic user:password') {", return new IdentityAssertionClaims({Map.of("iguser", "user"))", "}", "return newExceptionPromise(new IdentityAssertionException('Invalid authentication'))", ], "preProcessingFilter": { "type": "ScriptableFilter", "config": { "type": "application/x-groovy", "source": [ "if (request.headers.authorization == null) {", " Response response = new Response(Status.UNAUTHORIZED)", " response.headers['WWW-Authenticate'] = \"Basic\"", " return response", "}", "return next.handle(context, request)", ], }, } } } ``` ### More information [org.forgerock.openig.handler.assertion.IdentityAssertionPlugin](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionPluginTechPreview.html) [IdentityAssertionClaims](../_attachments/apidocs/org/forgerock/openig/handler/assertion/IdentityAssertionClaims.html) ## 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 ```json { "name": string, "type": "TemporaryStorage", "config": { "initialLength": configuration expression, "memoryLimit": configuration expression, "fileLimit": configuration expression, "directory": configuration expression } } ``` ### Properties * `"initialLength"`: *configuration expression<[number](preface.html#definition-number)>, optional* Initial size of the memory buffer. Default: 8 192 bytes (8 KB). Maximum: The value of `"memoryLimit"`. * `"memoryLimit"`: *configuration expression<[number](preface.html#definition-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](preface.html#definition-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](preface.html#definition-string)>, optional* The directory where temporary files are created. Default: `$HOME/.openig/tmp` (on Windows,`%appdata%\OpenIG\tmp`) ### More information [org.forgerock.openig.io.TemporaryStorageHeaplet](../_attachments/apidocs/org/forgerock/openig/io/TemporaryStorageHeaplet.html) ## TlsOptions (deprecated) | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This object is deprecated; use [ClientTlsOptions](ClientTlsOptions.html) instead. For more information, refer to the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | Configures connections to the TLS-protected endpoint of servers, when IG is client-side. ### Usage ```json { "name": string, "type": "TlsOptions", "config": { "keyManager": [ Key manager reference, ...], "trustManager": [ Trust manager reference, ...], "sslCipherSuites": [ configuration expression, ...], "sslContextAlgorithm": configuration expression, "sslEnabledProtocols": [ configuration expression, ...], } } ``` ### Properties * `"keyManager"`: *array of key manager [references](preface.html#definition-reference) 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: * [SecretsKeyManager](secrets.html#SecretsKeyManager) * [KeyManager (deprecated)](KeyManager.html) 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](preface.html#definition-reference), optional* One or more of the following objects to manage IG's public key certificates: * [SecretsTrustManager](SecretsTrustManager.html) * [TrustAllManager](TrustAllManager.html) * [TrustManager (deprecated)](TrustManager.html) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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](preface.html#definition-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, 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](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#jsse-cipher-suite-names). Default: Allow any cipher suite supported by the JVM. * `"sslContextAlgorithm"`: *configuration expression<[string](preface.html#definition-string)>, optional* The `SSLContext` algorithm name, as listed in the table of [SSLContext Algorithms](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#sslcontext-algorithms) for the Java Virtual Machine (JVM). Default: `TLS` * `"sslEnabledProtocols"`: *array of configuration expression<[strings](preface.html#definition-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, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of [Additional JSSE Standard Names](https://docs.oracle.com/en/java/javase/17/docs/specs/security/standard-names.html#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 ## TrustAllManager Blindly trusts all server certificates presented the servers for protected applications. It can be used instead of a [TrustManager (deprecated)](TrustManager.html) 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 (deprecated)](TrustManager.html) instead. ### Usage ```none { "name": string, "type": "TrustAllManager" } ``` ### Example The following example configures a client handler that blindly trusts server certificates when IG connects to servers over HTTPS: ```json { "name": "BlindTrustClientHandler", "type": "ReverseProxyHandler", "config": { "trustManager": { "type": "TrustAllManager" } } } ``` ### More information [org.forgerock.openig.security.TrustAllManager](../_attachments/apidocs/org/forgerock/openig/security/TrustAllManager.html) ## 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 ```json { "name": string, "type": "UmaService", "config": { "protectionApiHandler": Handler reference, "amService": AmService reference, // Use either "amService" "wellKnownEndpoint": configuration expression, // or "wellKnownEndpoint", but not both. "resources": [ object, ... ] } } ``` ### Properties * `"protectionApiHandler"`: *Handler [reference](preface.html#definition-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](Handlers.html). * `"amService"`: *AmService [reference](preface.html#definition-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](https://docs.pingidentity.com/pingam/7.4/uma/uma-introduction.html#uma-discovery-intro) in AM's *User-Managed Access (UMA) 2.0 guide*. See also [AmService](#AmService). * `"wellKnownEndpoint"`: *configuration expression<[url](preface.html#definition-url)>, required if `amService` is not configured* The URI to the well-known endpoint for this UMA Authorization Server. If the UMA Authorization Server is not AM, use this property to define the endpoint. If `amService` is configured, it takes precedence over `wellKnownEndpoint`. Examples: * In this example, the UMA configuration is in the default realm of AM: ```none https://am.example.com:8088/openam/uma/.well-known/uma2-configuration ``` * In this example, the UMA configuration is in a European customer realm: ```none https://am.example.com:8088/openam/uma/realms/root/realms/customer/realms/europe/.well-known/uma2-configuration ``` For more information, refer to [AM as UMA Authorization Server](https://docs.pingidentity.com/pingam/7.4/uma/uma-introduction.html) in AM's *User-Managed Access (UMA) 2.0 guide*. * `"resources"`: *array of [objects](preface.html#definition-object), required* Resource objects matching the resources the resource owner wants to share. Each resource object has the following form: ```json { "pattern": resource pattern, "actions": [ { "scopes": [ scope string, ... ], "condition": runtime expression }, { ... } ] } ``` Each resource pattern can represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways: 1. When registering a resource set, IG uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used. 2. When responding to an initial request for a resource, IG derives the scopes for the ticket based on the scopes that apply according to the request. 3. When verifying the RPT, IG checks that all required scopes are encoded in the RPT. A description of each field follows: * `"pattern"`: *[pattern](preface.html#definition-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](Patterns.html). * `"actions"`: *array of [objects](preface.html#definition-object), optional* A set of scopes to authorize when the corresponding condition evaluates to `true`. ```json "actions": [ { "scopes": [ "#read" ], "condition": "${request.method == 'GET'}" }, { "scopes": [ "#create" ], "condition": "${request.method == 'POST'}" } ] ``` * `"scopes"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* One or more scopes that are authorized when the corresponding condition evaluates to `true`. For example, the scope `#read` grants read-access to a resource. * `"condition"`: *runtime expression<[boolean](preface.html#definition-boolean)>, required* When the condition evaluates to `true`, the corresponding scope is authorized. For example, the condition `${request.method == 'GET'}` is true when reading a resource. ### REST API for shares The REST API for UMA shares is exposed at a registered endpoint. IG logs the paths to registered endpoints when the log level is `INFO` or finer. Look for messages such as the following in the log: ``` UMA Share endpoint available at '/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share' ``` To access the endpoint over HTTP or HTTPS, prefix the path with the IG scheme, host, and port to obtain a full URL, such as `http://localhost:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share`. The UMA REST API supports create (POST only), read, delete, and query (`_queryFilter=true` only). For an introduction to common REST APIs, refer to [About ForgeRock Common REST](preface.html#sec-about-crest). 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 [API descriptors](../about/api-descriptor.html). For information about Common REST, refer to [About ForgeRock Common REST](preface.html#sec-about-crest). A share object has the following form: ```json { "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](Patterns.html). * `"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](https://docs.kantarainitiative.org/uma/wg/oauth-uma-grant-2.0-08.html) [org.forgerock.openig.uma.UmaSharingService](../_attachments/apidocs/org/forgerock/openig/uma/UmaSharingService.html)