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 PingGateway filters that communicate with that instance.
When PingGateway uses an AmService, PingGateway is positioned as the client of the service. By default, PingGateway is subscribed to Websocket notifications from AM, and the WebSocket connection can be secured by ClientTlsOptions.
Usage
{
"name": string,
"type": "AmService",
"config": {
"agent": object,
"secretsProvider": SecretsProvider reference,
"notifications": object,
"realm": configuration expression<string>,
"amHandler": Handler reference,
"sessionCache": object,
"sessionIdleRefresh": object,
"sessionProperties": [ configuration expression<string>, ... ],
"ssoTokenHeader": configuration expression<string>,
"url": configuration expression<url>,
"version": configuration expression<string>
}
}
Properties
"agent"
: object, required-
An PingGateway agent profile. When the agent is authenticated, the token can be used for tasks such as getting the user’s profile, making policy evaluations, and connecting to the AM notification endpoint.
{ "AmService": { "username": configuration expression<string>, "passwordSecretId": configuration expression<secret-id> } }
"username"
: configuration expression<string>, required-
Name of the AM agent profile.
"passwordSecretId"
: configuration expression<secret-id>, required-
The secret ID of the AM agent password. This secret ID must point to a GenericSecret.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for the agent password.
"realm"
: configuration expression<string>, optional-
The AM realm in which the PingGateway agent is created.
Default:
/
(top level realm). "amHandler"
: Handler reference, optional-
The Handler to use for communicating with AM. In production, use a ClientHandler that is capable of making an HTTPS connection to AM.
AmService does not use
amHandler
to subscribe to WebSocket notifications from AM. To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap, and refer to it from theamHandler
object and thenotifications
subpropertytls
.To facilitate auditing, configure this handler with a
ForgeRockClientHandler
, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.Alternatively, configure this handler as a chain containing a
TransactionIdOutboundFilter
, as in the following configuration:"amHandler": { "type": "Chain", "config": { "handler": "MySecureClientHandler", "filters": [ "TransactionIdOutboundFilter" ] } }
Default:
ForgeRockClientHandler
See also Handlers and ClientHandler.
"notifications"
: object, optional-
Configure a WebSocket notification service to subscribe to Websocket notifications from AM.
To subscribe to WebSocket notifications from AM, configure a ClientTlsOptions object in the heap, and refer to it from the
amHandler
object and thenotifications
subpropertytls
. Alternatively, useproxyOptions
to share a proxy configuration between theamHandler
and the notification service.For information, refer to WebSocket notifications.
{ "notifications": { "enabled": configuration expression<boolean>, "initialConnectionAttempts": configuration expression<number>, "reconnectDelay": configuration expression<duration>, "renewalDelay": configuration expression<duration>, "heartbeatInterval": configuration expression<duration>, "connectionTimeout": configuration expression<duration>, "idleTimeout": configuration expression<duration>, "tls": ClientTlsOptions reference, "proxyOptions": ProxyOptions reference, "vertx": object } }
enabled
: configuration expression<boolean>, optional-
A flag to enable WebSocket notifications. Set to
false
to disable WebSocket notifications.Default:
true
initialConnectionAttempts
: configuration expression<number>, optional-
The maximum number of times PingGateway 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, PingGateway attempts to reconnect to it an unlimited number of times.
Default:
5
reconnectDelay
: configuration expression<duration>, optional-
The time between attempts to re-establish a lost WebSocket connection.
When a WebSocket connection is lost, PingGateway waits for this delay and then attempts to re-establish the connection. If subsequent attempts fail, PingGateway waits and tries again an unlimited number of times.
Default:
5 seconds
renewalDelay
: configuration expression<duration>, optional-
The time before automatically renewing a WebSocket connection between PingGateway and AM. PingGateway renews connections transparently.
PingOne Advanced 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
orunlimited
to never automatically renew connections.Default:
50 minutes
heartbeatInterval
: configuration expression<duration>, optional-
The interval at which the AmService issues a heartbeat on WebSocket connections. When activity on the connection is low, the heartbeat prevents middleware or policies situated between PingGateway and AM from closing the connection for timeout.
Set to zero or unlimited to disable heartbeats.
Default:
1 minute
connectionTimeout
: configuration expression<duration>, optional-
The time PingGateway waits to establish a Websocket connection to AM before it considers the attempt as failed.
Default:
60 seconds
idleTimeout
: configuration expression<duration>, optional-
The time that a WebSocket connection to AM can be inactive before PingGateway closes it.
Default:
unlimited
tls
: ClientTlsOptions reference, optional-
Configure options for WebSocket connections to TLS-protected endpoints. Define a ClientTlsOptions object inline or in the heap.
Default: Connections to TLS-protected endpoints are not configured.
proxyOptions
: ProxyOptions reference>, optional-
A proxy server to which requests can be submitted. Use this property to relay requests to other parts of the network. For example, use it to submit requests from an internal network to the internet.
Provide the name of a ProxyOptions object defined in the heap or an inline configuration.
Default: A heap object named
ProxyOptions
. vertx
: 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.
"url"
: configuration expression<url>, required-
The URL of the AM service. When AM is running locally, this value could be
https://am.example.com/openam
. When AM is running in PingOne Advanced Identity Cloud, this value could behttps://myTenant.forgeblocks.com/am
. "sessionCache"
: object, optional-
In AM, if the realm includes a customized session property safelist, include
AMCtxId
in the list of properties. The customized session property safelist overrides the global session property safelist.Enable and configure caching of session information from AM, based on Caffeine. For more information, see the GitHub entry, Caffeine.
When
sessionCache
is enabled, PingGateway 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 PingGateway instances.When
sessionCache
is disabled, PingGateway must ask AM to verify the token for each request.PingGateway 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 configurationWhen PingGateway evicts session info entries from the cache, the next time the token is presented, PingGateway 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, PingGateway evicts a cached token almost as soon as it is revoked on AM, and in this way stays synchronized with AM. Subsequent requests to PingGateway 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 PingGateway that present the revoked token are considered as valid, and can cause incorrect authentication and authorization decisions until its natural eviction from the cache.
{ "sessionCache": { "enabled": configuration expression<boolean>, "executor": Executor service reference, "maximumSize": configuration expression<number>, "maximumTimeToCache": configuration expression<duration>, "onNotificationDisconnection": configuration expression<enumeration> } }
enabled
: configuration expression<boolean>, optional-
Enable caching.
Default:
false
executor
: Executor service reference, optional-
An executor service to schedule the execution of tasks, such as the eviction of entries in the cache.
Default:
ForkJoinPool.commonPool()
"maximumSize"
: configuration expression<number>, optional-
The maximum number of entries the cache can contain.
Default: Unlimited/unbound.
maximumTimeToCache
: configuration expression<duration>, optional-
The maximum duration for which to cache session info. Consider setting this duration to be less than the idle timeout of AM.
If
maximumTimeToCache
is longer thanmaxSessionExpirationTime
from SessionInfo,maxSessionExpirationTime
is used.Default:
-
When
sessionIdleRefresh
is set, idle timeout of AM minus 30 seconds. -
When
sessionIdleRefresh
is not set,maxSessionExpirationTime
, from SessionInfo.
-
onNotificationDisconnection
: configuration expression<enumeration>, optional-
The strategy to manage the cache when the WebSocket notification service is disconnected, and PingGateway receives no notifications for AM events. If the cache is not cleared it can become outdated, and PingGateway can allow requests on revoked sessions or tokens.
Cached entries that expire naturally while the notification service is disconnected are removed from the cache.
Use one of the following values:
-
NEVER_CLEAR
-
When the notification service is disconnected:
-
Continue to use the existing cache.
-
Deny access for requests that are not cached, but do not update the cache with these requests.
-
-
When the notification service is reconnected:
-
Continue to use the existing cache.
-
Query AM for incoming requests that are not found in the cache, and update the cache with these requests.
-
-
-
CLEAR_ON_DISCONNECT
-
When the notification service is disconnected:
-
Clear the cache.
-
Deny access to all requests, but do not update the cache with these requests.
-
-
When the notification service is reconnected:
-
Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)
-
Update the cache with these requests.
-
-
-
CLEAR_ON_RECONNECT
-
When the notification service is disconnected:
-
Continue to use the existing cache.
-
Deny access for requests that are not cached, but do not update the cache with these requests.
-
-
When the notification service is reconnected:
-
Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)
-
Update the cache with these requests.
-
-
Default:
CLEAR_ON_DISCONNECT
-
-
"sessionIdleRefresh"
: object, optional-
Enable and configure periodic refresh of idle sessions. When this property is enabled, PingGateway requests session refresh:
-
The first time PingGateway 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 PingGateway. 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 PingGateway requests a policy decision from AM. The session is less likely to become idle, and this property less required.
{ "sessionIdleRefresh": { "enabled": configuration expression<boolean>, "interval": configuration expression<duration> } }
enabled
: configuration expression<boolean>, optional-
Enable refresh of idle sessions.
Default:
false
interval
: configuration expression<duration>, optional-
Duration to wait after a session becomes idle before requesting a session refresh.
Consider setting the refresh interval in line with the latest access time update frequency of AM. For example, if PingGateway requests a refresh every 60 seconds, but the update frequency of AM is 5 minutes, AM ignores most of the PingGateway requests.
Each session refresh must be reflected in the AM core token service. Setting the interval to a duration lower than one minute can adversely impact AM performance. Default:
5 minutes
-
"sessionProperties"
: array of configuration expression<strings>, optional-
The list of user session properties to retrieve from AM by the SessionInfoFilter.
Default: All available session properties are retrieved from AM.
"ssoTokenHeader"
: configuration expression<string>, optional-
The header name or cookie name where this AM server expects to find SSO tokens.
If a value for
ssoTokenHeader
is provided, PingGateway uses that value. Otherwise, PingGateway queries the AM/serverinfo/*
endpoint for the header or cookie name.Default: Empty. PingGateway queries AM for the cookie name.
"version"
: configuration expression<string>, optional-
The version number of the AM server. PingGateway 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 ofversion
and issues a warning. -
Value in
version
: AmService cannot discover the AM version, andversion
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.
Default: AM 6.
-
ClientRegistration
A ClientRegistration holds information about registration with an OAuth 2.0 Authorization Server or OpenID Provider.
The configuration includes the client credentials that are used to authenticate to the identity provider. The client credentials can be included directly in the configuration, or retrieved in some other way using an expression, described in Expressions.
Usage
{
"name": string,
"type": "ClientRegistration",
"config": {
"clientId": configuration expression<string>,
"issuer": Issuer reference,
"scopes": [ configuration expression<string>, ...],
"registrationHandler": Handler reference,
"authenticatedRegistrationHandler": Handler reference,
"clientSecretUsage": configuration expression<enumeration>,
"clientSecretId": configuration expression<secret-id>,
"secretsProvider": SecretsProvider reference,
"skipSignatureVerification": configuration expression<boolean>,
"jwtExpirationTimeout": duration, //deprecated
"privateKeyJwtSecretId": configuration expression<secret-id>, //deprecated
"tokenEndpointAuthMethod": enumeration, //deprecated
"tokenEndpointAuthSigningAlg": string //deprecated
}
}
Properties
"clientId"
: configuration expression<string>, required-
The
client_id
obtained when registering with the Authorization Server. See also Expressions.When using a login page with AuthorizationCodeOAuth2ClientFilter, the link to the
/login
endpoint must refer to a validclientId
identified by this property. "issuer"
: Issuer reference, required-
The provider configuration to use for this client registration. Provide either the name of a Issuer object defined in the heap or an inline Issuer configuration object. See also Issuer.
"scopes"
: array of configuration expression<strings>, optional-
Array of scope strings to present to the user for approval, and include in tokens so that protected resources can make decisions about access.
Default: Empty
"registrationHandler"
: Handler reference, optional-
HTTP client handler to invoke during client registration, to access endpoints that do not require client authentication. Provide either the name of a Handler object defined in the heap or an inline Handler configuration object.
Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.
Default: ClientHandler.
"authenticatedRegistrationHandler"
: Handler reference, optional-
HTTP client handler to invoke during client registration, to access endpoints that require client authentication. Configure this property as a Chain, using one of the following filters for client authentication:
{ "name": "AuthenticatedRegistrationHandler", "type": "Chain", "config": { "handler": "ForgeRockClientHandler", "filters": [ { "type": "ClientSecretBasicAuthenticationFilter", "config": { "clientId": "service-client", "clientSecretId": "client.secret.id", "secretsProvider" : "SystemAndEnvSecretStore-1" } } ] } }
Default:
registrationHandler
with no authentication filter. "clientSecretUsage"
: configuration expression<enumeration>, optional-
Specifies how to use the
"clientSecretId"
; one of:-
CLIENT_AUTHENTICATION_ONLY
-
ID_TOKEN_VALIDATION_AND_CLIENT_AUTHENTICATION
-
ID_TOKEN_VALIDATION_ONLY
Default:
CLIENT_AUTHENTICATION_ONLY
-
"clientSecretId"
: configuration expression<secret-id>, required to verify ID tokens with HMAC-based signatures-
The secret ID of the client secret.
Set this for ID token validation when the OpenID provider signs ID tokens using an HMAC algorithm. In addition, set
"clientSecretUsage"
toID_TOKEN_VALIDATION_AND_CLIENT_AUTHENTICATION
orID_TOKEN_VALIDATION_ONLY
and use a"secretsProvider"
to access the client secret.This secret ID must point to a GenericSecret.
"secretsProvider"
: SecretsProvider reference, required to verify ID tokens with HMAC-based signatures-
The SecretsProvider object to query for the client’s GenericSecret. For more information, see SecretsProvider.
When the OpenID provider signs ID tokens using an HMAC algorithm, use this provider to access the
"clientSecretId"
. "skipSignatureVerification"
: configuration expression<boolean>, optional-
A flag for signature validation of OpenID Connect ID tokens:
-
true
: Don’t validate signatures.By default, for backward compatibility in this release, the default value of this property is
true
.Before using the value
true
, consider the security impact on your deployment. Use only when the connection between the Issuer and Client is direct and well secured. -
false
: Validate signatures.
Default:
true
-
"jwtExpirationTimeout"
: duration, optional-
This property is deprecated; use authenticatedRegistrationHandler
instead. For more information, refer to the Deprecated section of the Release Notes.When
private_key_jwt
is used for authentication, this property specifies the duration for which the JWT is valid.Default: 1 minute
"privateKeyJwtSecretId"
: configuration expression<secret-id>, required whenprivate_key_jwt
is used for client authentication-
This property is deprecated; use authenticatedRegistrationHandler
instead. For more information, refer to the Deprecated section of the Release Notes.The secret ID of the key to sign the JWT.
This secret ID must point to a CryptoKey.
"tokenEndpointAuthMethod"
: enumeration, optional-
This property is deprecated; use authenticatedRegistrationHandler
instead. For more information, refer to the Deprecated section of the Release Notes.The authentication method with which a client authenticates to the authorization server or OpenID provider at the token endpoint. For information about client authentication methods, see OpenID Client Authentication. The following client authentication methods are allowed:
-
client_secret_basic
: Clients that have received aclient_secret
value from the Authorization Server authenticate with the Authorization Server by using the HTTP Basic authentication scheme, as in the following example:POST /oauth2/token HTTP/1.1 Host: as.example.com Authorization: Basic .... Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=...
-
client_secret_post
: Clients that have received aclient_secret
value from the Authorization Server authenticate with the Authorization Server by including the client credentials in the request body, as in the following example:POST /oauth2/token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&; client_id=...& client_secret=...& code=...
-
private_key_jwt
: Clients send a signed JSON Web Token (JWT) to the Authorization Server. PingGateway builds and signs the JWT, and prepares the request as in the following example:POST /token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=...& client_id=<clientregistration_id>& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT
If the Authorization Server doesn’t support
private_key_jwt
, a dynamic registration falls back on the method returned by the Authorization Server, for example,client_secret_basic
orclient_secret_post
.If
tokenEndpointAuthSigningAlg
is not configured, theRS256
signing algorithm is used forprivate_key_jwt
.
Consider these points for identity providers:
-
Some providers accept more than one authentication method.
-
If a provider strictly enforces how the client must authenticate, align the authentication method with the provider.
-
If a provider doesn’t support the authentication method, the provider sends an HTTP 400 Bad Request response with an
invalid_client
error message, according to RFC 6749 The OAuth 2.0 Authorization Framework, section 5.2 . -
If the authentication method is invalid, the provider sends an
IllegalArgumentException
.
Default:
client_secret_basic
-
"tokenEndpointAuthSigningAlg"
: string, optional-
This property is deprecated; use authenticatedRegistrationHandler
instead. For more information, refer to the Deprecated section of the Release Notes.The JSON Web Algorithm (JWA) used to sign the JWT that is used to authenticate the client at the token endpoint. The property is used when
private_key_jwt
is used for authentication.Use one of the following algorithms:
-
RS256
: RSA using SHA-256 -
ES256
: ECDSA with SHA-256 and NIST standard P-256 elliptic curve -
ES384
: ECDSA with SHA-384 and NIST standard P-384 elliptic curve -
ES512
: ECDSA with SHA-512 and NIST standard P-521 elliptic curve
Default:
RS256
-
Example
Refer to AM as a single OpenID Connect provider.
ClientTlsOptions
Configures connections to the TLS-protected endpoint of servers, when PingGateway is client-side.
When PingGateway is client-side, PingGateway sends requests to a proxied application, or requests services from a third-party application. PingGateway is acting as a client of the application, and the application is acting as a server.
Use ClientTlsOptions in ClientHandler, ReverseProxyHandler, and AmService.
Usage
{
"name": string,
"type": "ClientTlsOptions",
"config": {
"keyManager": [ Key manager reference, ...],
"trustManager": [ Trust manager reference, ...],
"sslCipherSuites": [ configuration expression<string>, ...],
"sslContextAlgorithm": configuration expression<string>,
"sslEnabledProtocols": [ configuration expression<string>, ...],
"alpn": object,
"hostnameVerifier": configuration expression<enumeration>
}
}
Properties
"keyManager"
: array of key manager references, optional-
One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:
Key managers are used to prove the identity of the local peer during TLS handshake, as follows:
-
When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this PingGateway’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 PingGateway’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.
Default: None
-
"trustManager"
: array of trust manager references, optional-
One or more of the following objects to manage PingGateway’s public key certificates:
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, PingGateway 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 PingGateway uses the default and system certificates -
"sslCipherSuites"
: array of configuration expression<strings>, optional-
Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.
For information about the available cipher suite names, refer to the documentation for the Java virtual machine (JVM) where you run PingGateway. For Oracle Java, refer to the list of JSSE Cipher Suite Names.
Default: Allow any cipher suite supported by the JVM.
"sslContextAlgorithm"
: configuration expression<string>, optional-
The
SSLContext
algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).Default:
TLS
"sslEnabledProtocols"
: array of configuration expression<strings>, optional-
Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.
For information about the available protocol names, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of Additional JSSE Standard Names.
Follow these protocol recommendations:
-
Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.
-
If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.
-
Do not use deprecated versions SSL 3 or SSL 2.
Default: TLS 1.3, TLS 1.2
-
"alpn"
: object, optional-
A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.
{ "alpn": { "enabled": configuration expression<boolean> } }
enabled
: configuration expression<boolean>, optional-
-
true
: Enable ALPN. Required for HTTP/2 connections over TLS -
false
: Disable ALPN.
-
Default:
true
"hostnameVerifier"
: configuration expression<enumeration>, optional-
The method to handle hostname verification for outgoing SSL connections.
For backward compatibility, when a ClientHandler or ReverseProxyHandler includes the deprecated
"hostnameVerifier": "ALLOW_ALL"
configuration, it takes precedence over this property. A deprecation warning is written to the logs.Use one of the following values:
-
ALLOW_ALL
: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.If the SSL endpoint uses a raw IP address rather than a fully-qualified hostname, you must configure this property as
ALLOW_ALL
.To prevent the compromise of TLS connections, use
ALLOW_ALL
in development mode only. In production, useSTRICT
.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
matcheswww.example.com
but notsome.host.example.com
.
Default:
STRICT
-
Example
For an example that uses ClientTlsOptions, refer to Configure PingGateway for TLS (client-side).
Delegate
Delegates all method calls to a referenced handler, filter, or any object type.
Use a Delegate to decorate referenced objects differently when they are used multiple times in a configuration.
Usage
{
"filter or handler": {
"type": "Delegate",
[decorator reference, ...],
"config": {
"delegate": object
}
}
}
Example
For an example of how to delegate tasks to ForgeRockClientHandler
, and
capture PingGateway’s interaction with AM, refer to
Decorating PingGateway’s interactions with AM.
JwtSession
Configures settings for stateless sessions.
Session information is serialized as a secure JWT, that is encrypted and signed, and optionally compressed. The resulting JWT string is placed in 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 ofconfig.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, PingGateway builds a new session object for the route. Any child routes inherit the session. The session information is saved/persisted when the response exits the route. For more information, refer to Route.
-
Configure a JwtSession object in the
session
property of multiple sibling routes in the configuration, using an identical cookie name and cryptographic properties. Sibling routes are in the same configuration, with no ascending hierarchy to each other.When a JwtSession object is declared in a route, the session content is available only within that route. With this configuration, sibling routes can read/write in the same session.
Consider the following points when you configure JwtSession:
-
Only JSON-compatible types can be serialized into a JWT and included in JWT session cookies. Compatible types include primitive JSON structures, lists, arrays, and maps. For more information, refer to http://json.org.
-
The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, PingGateway 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 PingGateway from cleaning up empty session cookies, consider adding some information to the session context by using an AssignmentFilter. For an example, refer to Adding info to a session.
-
When HTTP clients perform multiple requests in a session that modify the content, the session information can become inconsistent.
For information about PingGateway sessions, refer to Sessions.
Usage
{
"name": string,
"type": "JwtSession",
"config": {
"authenticatedEncryptionSecretId": configuration expression<secret-id>,
"encryptionMethod": configuration expression<string>,
"cookie": object,
"sessionTimeout": configuration expression<duration>,
"persistentCookie": configuration expression<boolean>,
"secretsProvider": SecretsProvider reference,
"skewAllowance": configuration expression<duration>,
"useCompression": configuration expression<boolean>
}
}
Properties
"authenticatedEncryptionSecretId"
: configuration expression<secret-id>, optional-
The secret ID of the encryption key used to perform authenticated encryption on a JWT. Authenticated encryption encrypts data and then signs it with HMAC, in a single step.
This secret ID must point to a CryptoKey.
Authenticated encryption is achieved with a symmetric encryption key. Therefore, the secret must refer to a symmetric key.
For more information, refer to RFC 5116.
Default: PingGateway generates a default symmetric key for authenticated encryption. Consequently, PingGateway instances cannot share the JWT session.
"encryptionMethod"
: configuration expression<string>, optional-
The algorithm to use for authenticated encryption. For information about allowed encryption algorithms, refer to RFC 7518: "enc" (Encryption Algorithm) Header Parameter Values for JWE.
Default: A256GCM
"cookie"
: object, optional-
The configuration of the cookie used to store the encrypted JWT.
The maximum size of the JWT session cookie is 4 KBytes, as defined by the browser. If the cookie exceeds this size, PingGateway automatically splits it into multiple cookies.
Default: The cookie is treated as a host-based cookie.
{ "name": configuration expression<string>, "domain": configuration expression<string>, "httpOnly": configuration expression<boolean>, "path": configuration expression<string>, "sameSite": configuration expression<enumeration>, "secure": configuration expression<boolean> }
"name"
configuration expression<string>, optional-
Name of the JWT cookie stored on the user agent. For security, change the default name of cookies.
Default:
openig-jwt-session
"domain"
configuration expression<string>, optional-
Domain from which the JWT cookie can be accessed. When the domain is specified, a JWT cookie can be accessed from different hosts in that domain.
Set a domain only if the user agent is able to re-emit cookies on that domain on its next hop. For example, to re-emit a cookie on the domain
.example.com
, the user agent must be able to access that domain on its next hop.Default: The fully qualified hostname of the user agent’s next hop.
"httpOnly"
: configuration expression<boolean>, optional-
Flag to mitigate the risk of client-side scripts accessing protected cookies.
Default:
true
"path"
: configuration expression<string>, optional-
Path protected by this session.
Set a path only if the user agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path
/home/cdsso
, the user agent must be able to access that path on its next hop.Default: The path of the request that got the
Set-Cookie
in its response.
"sameSite"
: configuration expression<enumeration>, optional-
Options to manage the circumstances in which a cookie is sent to the server. Use one of the following values to reduce the risk of CSRF attacks:
-
STRICT
: Send the cookie only if the request was initiated from the cookie domain. Not case-sensitive.Use this value to reduce the risk of cross-site request forgery (CSRF) attacks.
-
LAX
: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain. Not case-sensitive.Use this value to reduce the risk of cross-site request forgery (CSRF) attacks.
-
NONE
: Send the cookie whenever a request is made to the cookie domain. Not case-sensitive.With this setting, consider setting
secure
totrue
to prevent browsers from rejecting the cookie. For more information, refer to SameSite cookies.
Default:
LAX
-
"secure"
: configuration expression<boolean>, optional-
Flag to limit the scope of the cookie to secure channels.
Set this flag only if the user agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the
secure
flag, the user agent must be connected to its next hop by HTTPS.Default:
false
"sessionTimeout"
: configuration expression<duration>, optional-
The duration for which a JWT session is valid. If the supporting cookie is persistent, this property also defines the expiry of the cookie.
The value must be above zero. The maximum value is 3650 days (approximately 10 years). If you set a longer duration, PingGateway truncates the duration to 3650 days.
Default: 30 minutes
"persistentCookie"
: configuration expression<boolean>,optional-
Whether or not the supporting cookie is persistent:
-
true
: the supporting cookie is a persistent cookie. Persistent cookies are re-emitted by the user agent until their expiration date or until they are deleted. -
false
: the supporting cookie is a session cookie. PingGateway 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, required-
The SecretsProvider to query for the JWT session signing or encryption keys.
"skewAllowance"
: configuration expression<duration>, optional-
The duration to add to the validity period of a JWT to allow for clock skew between different servers.
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 PingGateway clock. -
A JWT with an
exp
13:00 is expired after 13:02 on the PingGateway clock.
Default: To support a zero-trust policy, the skew allowance is by default
zero
. -
"useCompression"
: configuration expression boolean, optional-
A flag to compress the session JWT before it is placed in a cookie.
Compression can undermine the security of encryption. Evaluate this threat according to your use case before you enable compression. Default:
false
Example
For information about configuring a JwtSession with authenticated encryption, see Encrypt JWT sessions.
For information about managing multiple instances of PingGateway in the same deployment, refer to the Installation guide.
More information
For information about PingGateway sessions, refer to Sessions.
KeyManager (deprecated)
This object is deprecated; use SecretsKeyManager instead. For more information, refer to the Deprecated section of the Release Notes. |
The configuration of a Java Secure Socket Extension KeyManager to manage private keys for PingGateway. The configuration references the keystore that holds the keys.
When PingGateway acts as a server, it uses a KeyManager to prove its identity to the client. When PingGateway acts as a client, it uses a KeyManager to prove its identity to the server.
Usage
{
"name": string,
"type": "KeyManager",
"config": {
"keystore": KeyStore reference,
"passwordSecretId": configuration expression<secret-id>,
"alg": configuration expression<string>,
"secretsProvider": SecretsProvider reference
}
}
Properties
"keystore"
: KeyStore reference, required-
The KeyStore (deprecated) object that references the store for key certificates. When
keystore
is used in a KeyManager, it queries for private keys; whenkeystore
is used in a TrustManager, it queries for certificates.Provide either the name of the keystore object defined in the heap or an inline keystore configuration object.
"passwordSecretId"
: configuration expression<secret-id>, required-
The secret ID of the password required to read private keys from the keystore.
This secret ID must point to a GenericSecret.
"alg"
: configuration expression<string>, optional-
The certificate algorithm to use.
Default: the default for the platform, such as
SunX509
.See also Expressions.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for the keystore password.
Example
The following example configures a KeyManager that depends on a KeyStore (deprecated) configuration. The KeyManager and KeyStore passwords are provided by Java system properties or environment variables, and retrieved by the SystemAndEnvSecretStore. By default, the password values must be base64-encoded.
{
"name": "MyKeyManager",
"type": "KeyManager",
"config": {
"keystore": {
"type": "KeyStore",
"config": {
"url": "file://${env['HOME']}/keystore.p12",
"passwordSecretId": "keymanager.keystore.secret.id",
"secretsProvider": "SystemAndEnvSecretStore"
}
},
"passwordSecretId": "keymanager.secret.id",
"secretsProvider": "SystemAndEnvSecretStore"
}
}
KeyStore (deprecated)
This object is deprecated; use KeyStoreSecretStore instead. For more information, refer to the Deprecated section of the Release Notes. |
The configuration for a Java KeyStore, which stores cryptographic private keys and public key certificates.
Legacy keystore types such as JKS and JCEKS are supported but are not secure. Consider using the PKCS#12 keystore type. |
Usage
{
"name": name,
"type": "KeyStore",
"config": {
"url": configuration expression<url>,
"passwordSecretId": configuration expression<secret-id>,
"type": configuration expression<string>,
"secretsProvider": SecretsProvider reference
}
}
Properties
"url"
: configuration expression<url>, required-
URL to the keystore file.
See also Expressions.
"passwordSecretId"
: configuration expression<secret-id>, optional-
The secret ID of the password required to read private keys from the KeyStore.
This secret ID must point to a GenericSecret.
If the KeyStore is used as a truststore to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field.
Default: No password is set.
See also Expressions.
"type"
: configuration expression<string>, optional-
The secret store type.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for the keystore password.
Example
The following example configures a KeyStore that references the Java KeyStore
file $HOME/keystore.p12
. The KeyStore password is provided by a Java
system property or environment variable, and retrieved by the
SystemAndEnvSecretStore. By default, the password value must be base64-encoded.
{
"name": "MyKeyStore",
"type": "KeyStore",
"config": {
"url": "file://${env['HOME']}/keystore.p12",
"passwordSecretId": "keystore.secret.id",
"secretsProvider": "SystemAndEnvSecretStore"
}
}
Issuer
Describes an OAuth 2.0 Authorization Server or an OpenID Provider that PingGateway can use as a OAuth 2.0 client or OpenID Connect relying party.
The Issuer requires OpenID Connect ID Token signature validation. It doesn’t support ID Token encryption.
An Issuer is usually referenced from a ClientRegistration.
Usage
{
"name": string,
"type": "Issuer",
"config": {
"wellKnownEndpoint": configuration expression<url>,
"idTokenVerificationSecretId": configuration expression<string>,
"secretsProvider": SecretsProvider reference,
"authorizeEndpoint": configuration expression<url>,
"registrationEndpoint": configuration expression<url>,
"tokenEndpoint": configuration expression<url>,
"userInfoEndpoint": configuration expression<url>,
"endSessionEndpoint": configuration expression<url>,
"revocationEndpoint": configuration expression<url>,
"issuer": configuration expression<string>,
"issuerHandler": Handler reference,
"issuerRepository": Issuer repository reference,
"supportedDomains": [ pattern, ... ],
"idTokenSkewAllowance": configuration expression<duration>
}
}
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.
For token signature validation, if you don’t specify the well-known configuration URL, do specify the expected issuer and how to access the secret. For HMAC-based signature validation, PingGateway must have access to the symmetric key, such as the client secret it uses to connect to the OpenID provider. The verification secret ID expects a CryptoKey. The OAuth2 client secret ID to registering the client is a GenericSecret. At present, you can’t reuse the same secrets provider for both the client secret and signature validation.
The provider configuration object properties are as follows:
"name"
: string, required-
A name for the provider configuration.
"wellKnownEndpoint"
: configuration expression<url>, required unless authorizeEndpoint and tokenEndpoint are configured-
The URL to the well-known configuration resource as described in OpenID Connect 1.0 Discovery.
"idTokenVerificationSecretId"
: configuration expression<string>, optional-
When OpenID Connect ID token signature validation is enabled on the ClientRegistration and no
"wellKnownEndpoint"
is set, set this to reference the provider’s public key for asymmetric ID token signature validation.If the OpenID provider uses a symmetric (HMAC-based) signature algorithm, the symmetric key is the client secret. Configure the client secret ID in the ClientRegistration instead.
This secret ID must point to a CryptoKey in the
"secretsProvider"
.Default: Use the
jwks_uri
in the well-known configuration to get the asymmetric signature validation keys and ignore this setting. "secretsProvider"
: SecretsProvider reference, required whenidTokenVerificationSecretId
is set-
The SecretsProvider to query for the signature validation secret.
Default: Use the
jwks_uri
in the well-known configuration to get the asymmetric signature validation keys and ignore this setting. "authorizeEndpoint"
: configuration expression<url>, required unless obtained through wellKnownEndpoint-
The URL to the provider’s OAuth 2.0 authorization endpoint.
"registrationEndpoint"
: configuration expression<url>, optional-
The URL to the provider’s OpenID Connect dynamic registration endpoint.
"tokenEndpoint"
: configuration expression<url>, required unless obtained through wellKnownEndpoint-
The URL to the provider’s OAuth 2.0 token endpoint.
"userInfoEndpoint"
: configuration expression<url>, optional-
The URL to the provider’s OpenID Connect UserInfo endpoint.
Default: no UserInfo is obtained from the provider.
"endSessionEndpoint"
: configuration expression<url>, optional-
The URL to the Authorization Server’s
end_session_endpoint
. In OpenID Connect, when a request accesses this endpoint, PingGateway kills the user session in AM.Consider the following example endpoint:
https://am.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/endSession
For more information, refer to OpenID Connect Session Management.
Default: No endpoint
"revocationEndpoint"
: configuration expression<url>, optional-
The URL to the Authorization Server’s
revocation_endpoint
. When a request accesses this endpoint, PingGateway 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
"issuer"
: configuration expression<string>, required for OIDC unless obtained through the wellKnownEndpoint-
The identifier of the issuer for OpenID Connect ID tokens. Must match the
iss
claim value in the ID tokens.Default: Use the
issuer
in the well-known configuration. "issuerHandler"
: Handler reference, optional-
Invoke this HTTP client handler to communicate with the Authorization Server.
Provide either the name of a Handler object defined in the heap or an inline Handler configuration object.
Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.
Default: PingGateway uses the default ClientHandler.
See also Handlers, ClientHandler.
"issuerRepository"
: Issuer repository reference, optional-
A repository of OAuth 2.0 issuers, built from discovered issuers and the PingGateway 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 namedIssuerRepository
is created in the current route.See also IssuerRepository.
"supportedDomains"
: array of patterns, optional-
One or more domain patterns to match domain names that are handled by this issuer, used as a shortcut for OpenID Connect discovery before performing OpenID Connect dynamic registration.
In summary when the OpenID Provider is not known in advance, it might be possible to discover the OpenID Provider Issuer based on information provided by the user, such as an email address. The OpenID Connect discovery specification explains how to use WebFinger to discover the issuer. PingGateway can discover the issuer in this way. As a shortcut PingGateway can also use supported domains lists to find issuers already described in the PingGateway configuration.
To use this shortcut, PingGateway 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. PingGateway adds the scheme. For instance,
*.example.com
matches any host in theexample.com
domain. You can specify the port number as well as inhost.example.com:8443
. Patterns must be valid regular expression patterns according to the rules for the Java Pattern class. "idTokenSkewAllowance"
: configuration expression<duration>, optional-
Acceptable clock skew when validating OpenID Connect ID Tokens.
Default:
zero
Examples
The following example shows an AM issuer configuration for AM. AM exposes a well-known endpoint for the provider configuration, but this example demonstrates use of the other fields:
{
"name": "openam",
"type": "Issuer",
"config": {
"authorizeEndpoint":
"https://am.example.com:8443/openam/oauth2/authorize",
"registration_endpoint":
"https://am.example.com:8443/openam/oauth2/connect/register",
"tokenEndpoint":
"https://am.example.com:8443/openam/oauth2/access_token",
"userInfoEndpoint":
"https://am.example.com:8443/openam/oauth2/userinfo",
"supportedDomains": [ "mail.example.*", "docs.example.com:8443" ]
}
}
The following example shows an issuer configuration for Google:
{
"name": "google",
"type": "Issuer",
"config": {
"wellKnownEndpoint":
"https://accounts.google.com/.well-known/openid-configuration",
"supportedDomains": [ "gmail.*", "googlemail.com:8052" ]
}
}
IssuerRepository
Stores OAuth 2 issuers that are discovered or built from the configuration.
It is not normally necessary to change this object. Change it only for the following tasks:
-
To isolate different repositories in the same route.
-
To view the interactions of the well-known endpoint, for example, if the
issuerHandler
is delegating to another handler.
Usage
{
"name": string,
"type": "IssuerRepository",
"config": {
"issuerHandler": Handler reference
}
}
Properties
"issuerHandler"
: Handler reference, optional-
The default handler to fetch OAuth2 issuer configurations from the well-known endpoint.
Provide the name of a Handler object defined in the heap or an inline Handler configuration object.
Default: ForgeRockClientHandler
JdbcDataSource
Manages connections to a JDBC data source.
To configure the connection pool, add a JdbcDataSource object named AuditService
in the route heap.
Usage
{
"name": string,
"type": "JdbcDataSource",
"config": {
"dataSourceClassName": configuration expression<string>,
"driverClassName": configuration expression<string>,
"executor": ScheduledExectutorService reference,
"jdbcUrl": configuration expression<url>,
"passwordSecretId": configuration expression<secret-id>,
"poolName": configuration expression<string>,
"properties": object,
"secretsProvider": SecretsProvider reference,
"username": configuration expression<string>
}
}
Properties
"dataSourceClassName"
: configuration expression<string>, optional-
The data source class name to use to connect to the database.
Depending on the underlying data source, use either
jdbcUrl
, ordataSourceClassName
withurl
. See the Properties. "driverClassName"
: configuration expression<string>, optional-
Class name of the JDBC connection driver. The following examples can be used:
-
MySQL Connector/J:
com.mysql.jdbc.Driver
-
H2:
org.h2.Driver
This property is optional, but required for older JDBC drivers.
-
"executor"
: ScheduledExecutorService reference, optional-
A ScheduledExecutorService for maintenance tasks.
Default: ScheduledExecutorService.
"jdbcUrl"
: configuration expression<url>, optional-
The JDBC URL to use to connect to the database.
Depending on the underlying data source, use either
jdbcUrl
, ordataSourceClassName
withurl
. See the Properties. "passwordSecretId"
: configuration expression<secret-id>, required if the database is password-protected-
The secret ID of the password to access the database.
This secret ID must point to a GenericSecret.
"poolName"
: configuration expression<string>, optional-
The connection pool name. Use to identify a pool easily for maintenance and monitoring.
"properties"
: object, optional-
Server properties specific to the type of data source being used. The values of the object are evaluated as configuration expression<strings>.
For information about available options, refer to the data source documentation.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for passwords and cryptographic keys.
"username"
: configuration expression<string>, optional-
The username to access the database.
Example
For an example that uses JdbcDataSource, refer to Log In With Credentials From a Database and Recording Access Audit Events in a Database.
The following example configures a JdbcDataSource with a dataSourceClassName
and url
:
"config": {
"username": "testUser",
"dataSourceClassName": "org.h2.jdbcx.JdbcDataSource",
"properties": {
"url": "jdbc:h2://localhost:3306/auth"
},
"passwordSecretId": "database.password",
"secretsProvider": "MySecretsProvider"
}
The following example configures a JdbcDataSource with jdbcUrl
alone:
"config": {
"username": "testUser",
"jdbcUrl": "jdbc:h2://localhost:3306/auth",
"passwordSecretId": "database.password",
"secretsProvider": "MySecretsProvider"
}
The following example configures a JdbcDataSource with jdbcUrl
and driverName
. Use this format for older drivers, where jdbcUrl
does not provide enough information:
"config": {
"username": "testUser",
"jdbcUrl": "jdbc:h2://localhost:3306/auth",
"driverName": "org.h2.Driver",
"passwordSecretId": "database.password",
"secretsProvider": "MySecretsProvider"
}
KerberosIdentityAssertionPlugin
Use with an IdentityAssertionHandler to validate Kerberos authentication tickets locally.
The KerberosIdentityAssertionPlugin doesn’t support Windows New Technology LAN Manager (NTLM) tokens.
Usage
{
"name": string,
"type": "KerberosIdentityAssertionPlugin",
"config": {
"serviceLogin": ServiceLogin reference,
"trustedRealms": [configuration_expression<string>, ...]
}
}
Properties
"serviceLogin"
: ServiceLogin reference, required-
A service account object to log PingGateway in to the Kerberos server so that PingGateway can act on user tokens. PingGateway will be able to validate user tokens, for example.
PingGateway provides the following service account objects for the KerberosIdentityAssertionPlugin:
- UsernamePasswordServiceLogin
-
Log PingGateway in to the Kerberos server by using a service account username and password.
{ "type": "UsernamePasswordServiceLogin", "config": { "username": configuration_expression<string>, "passwordSecretId": configuration expression<secret-id>, "secretsProvider": SecretsProvider reference } }
"username"
: configuration expression<string>, required-
Service username.
"passwordSecretId"
: configuration expression<secret-id>, required if the proxy requires authentication-
The secret ID of the service account password.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for the password.
- KeytabServiceLogin
-
Log PingGateway in to the Kerberos server by using a Keytab file.
This service account object is less secure than UsernamePasswordServiceLogin; use it only for testing or to ease migration. In production environments, always use the most secure options available. { "type": "KeytabServiceLogin", "config": { "username": configuration_expression<string>, "keytabFile": configuration expression<secret-id>, "executor": ScheduledExecutorService reference } }
"username"
: configuration expression<string>, required-
Service username.
"keytabFile"
: configuration expression<string>, required-
Path to the keytab file. Both the username and keytabFile are required for login.
"executor"
: ScheduledExecutorService reference, optional-
An executor service to schedule the execution of tasks during a keytab service login.
Default: ScheduledExecutorService or an executor service declared in the heap.
"trustedRealms"
: array of configuration expression<strings>, optional-
A list of one or more Kerberos realms that are expected to match the principal’s realm from the user’s Kerberos ticket.
Kerberos tickets are accepted only if the principal’s realm matches a realm in the list.
Default: Empty
Examples
{
"type": "KerberosIdentityAssertionPlugin",
"config": {
"serviceLogin": "UsernamePasswordServiceLogin",
"trustedRealms": ["EXAMPLE.COM"]
}
}
{
"type": "UsernamePasswordServiceLogin",
"config": {
"username": "igsa",
"passwordSecretId": "igsa.id",
"secretsProvider": "mySecretsProvider"
}
}
When using a Kerberos keytab file, generate it for PingGateway with the Windows ktpass
command.
The following commands add and view a Service Principal Name (SPN) for the PingGateway service account, igsa
,
and generate a keytab file for PingGateway in the example.com
realm mapped to the service account username.
Run the commands as the Windows Administrator to ensure you have access to everything necessary:
# Add the SPN for the service account:
PS C:\path\to> setspn -s HTTP/ig.example.com igsa
# View the SPN for the service account:
PS C:\path\to> setspn -l igsa
Registered ServicePrincipalNames for CN=igsa,CN=Users,DC=example,DC=com:
HTTP/ig.example.com
# Generate the keytab file:
PS C:\path\to> ktpass -out keytab.file -princ HTTP/ig.example.com@EXAMPLE.COM -pass `
+rndPass -maxPass 256 -mapuser igsa -crypto All -ptype KRB5_NT_PRINCIPAL -kvno 0
In the PingGateway configuration, you can use the Kerberos principal as the username:
{
"type": "KeytabServiceLogin",
"config": {
"username": "HTTP/ig.example.com@EXAMPLE.COM",
"keytabFile": "/path/to/keytab.file"
}
}
ProxyOptions
A proxy to which a ClientHandler or ReverseProxyHandler can submit requests, and an AmService can submit Websocket notifications.
Use this object to configure a proxy for AM notifications, and use it in a ClientHandler or ReverseProxyHandler, and again in an AmService notifications block.
Usage
Use one of the following ProxyOption types with the proxyOptions
option of
ClientHandler, ReverseProxyHandler, and
AmService:
-
No proxy.
{ "name": string, "type": "NoProxyOptions" }
-
System defined proxy options.
{ "name": string, "type": "SystemProxyOptions" }
-
Custom proxy
{ "name": string, "type": "CustomProxyOptions", "config": { "uri": configuration expression<url>, "username": configuration expression<string>, "passwordSecretId": configuration expression<secret-id>, "secretsProvider": SecretsProvider reference } }
Default: NoProxyOptions
Properties
"uri"
: configuration expression<url>, required-
URI of a server to use as a proxy for outgoing requests.
The result of the expression must be a string that represents a valid URI, but is not a real
java.net.URI
object. "username"
: configuration expression<string>, required if the proxy requires authentication-
Username to access the proxy server.
"passwordSecretId"
: configuration expression<secret-id>, required if the proxy requires authentication-
The secret ID of the password to access the proxy server.
This secret ID must point to a GenericSecret.
"secretsProvider"
: _ SecretsProvider <reference>, required-
The SecretsProvider to query for the proxy’s password.
Example
In the following example, the handler passes outgoing requests to the proxy server, which requires authentication:
"handler": {
"type": "ClientHandler" or "ReverseProxyHandler",
"config": {
"proxyOptions": {
"type": "CustomProxyOptions",
"config": {
"uri": "http://proxy.example.com:3128",
"username": "proxyuser",
"passwordSecretId": "myproxy.secret.id",
"secretsProvider": "SystemAndEnvSecretStore"
}
}
}
}
In the following example, the AmService notification service passes Websocket notifications to the proxy server, which requires authentication:
"type": "AmService",
"config": {
...
"notifications": {
"proxyOptions": {
"type": "CustomProxyOptions",
"config": {
"uri": "http://proxy.example.com:3128",
"username": "proxyuser",
"passwordSecretId": "myproxy.secret.id",
"secretsProvider": "SystemAndEnvSecretStore"
}
}
}
}
}
ScheduledExecutorService
An executor service to schedule tasks for execution after a delay or for repeated execution with a fixed interval of time in between each execution. You can configure the number of threads in the executor service and how the executor service is stopped.
The ScheduledExecutorService
is shared by all downstream components that use
an executor service.
Usage
{
"name": string,
"type": "ScheduledExecutorService",
"config": {
"corePoolSize": configuration expression<number>,
"gracefulStop": configuration expression<boolean>,
"gracePeriod": configuration expression<duration>
}
}
Properties
"corePoolSize"
: configuration expression<number>, optional-
The minimum number of threads to keep in the pool. If this property is an expression, the expression is evaluated as soon as the configuration is read.
The value must be an integer greater than zero.
Default: 1
"gracefulStop"
: configuration expression<boolean>, optional-
Defines how the executor service stops.
If true, the executor service does the following:
-
Blocks the submission of new jobs.
-
If a grace period is defined, waits for up to that maximum time for submitted and running jobs to finish.
-
Removes submitted jobs without running them.
-
Attempts to end running jobs.
If false, the executor service does the following:
-
Blocks the submission of new jobs.
-
If a grace period is defined, ignores it.
-
Removes submitted jobs without running them.
-
Attempts to end running jobs.
Default: true
-
"gracePeriod"
: configuration expression<duration>, optional-
The maximum time that the executor service waits for running jobs to finish before it stops. If this property is an expression, the expression is evaluated as soon as the configuration is read.
If all jobs finish before the grace period, the executor service stops without waiting any longer. If jobs are still running after the grace period, the executor service removes the scheduled tasks, and notifies the running tasks for interruption.
When
gracefulStop
isfalse
, the grace period is ignored.Default: 10 seconds
Example
The following example creates a thread pool to execute tasks. When the executor service is instructed to stop, it blocks the submission of new jobs, and waits for up to 10 seconds for submitted and running jobs to complete before it stops. If any jobs are still submitted or running after 10 seconds, the executor service stops anyway and prints a message.
{
"name": "ExecutorService",
"comment": "Default service for executing tasks in the background.",
"type": "ScheduledExecutorService",
"config": {
"corePoolSize": 5,
"gracefulStop": true,
"gracePeriod": "10 seconds"
}
}
ScriptableResourceUriProvider
Use a script to return a resource URL to include in policy decision requests to AM. The result of the script must be a string that represents a resource URL. The PolicyEnforcementFilter uses the returned resource URL as a key to identify cached policy decisions.
To increase performance, use ScriptableResourceUriProvider in conjunction with AM policies to maximize the the cache hit ratio.
When a request matches a cached policy decision, PingGateway can reuse the decision without asking AM for a new decision. When caching is disabled, PingGateway must ask AM to make a decision for each request.
Usage
"resourceUriProvider": {
"type": "ScriptableResourceUriProvider",
"config": {
"type": configuration expression<string>,
"file": configuration expression<string>, // Use either "file"
"source": [ string, ... ], // or "source", but not both.
"args": object,
"clientHandler": Handler reference
}
}
Properties
For information about properties, refer to Scripts.
ServerTlsOptions
When PingGateway is server-side, applications send requests to PingGateway or request services from PingGateway. PingGateway is acting as a server of the application, and the application is acting as a client.
ServerTlsOptions configures the TLS-protected endpoint when PingGateway is
server-side. Use ServerTlsOptions in admin.json
.
Usage
{
"type": "ServerTlsOptions",
"config": {
"keyManager": [ Key manager reference, ...], // Use "keyManager" or
"sni": object, // "sni", but not both
"trustManager": [ Trust manager reference, ...],
"sslCipherSuites": [ configuration expression<string>, ...],
"sslContextAlgorithm": configuration expression<string>,
"sslEnabledProtocols": [ configuration expression<string>, ...],
"alpn": object,
"clientAuth": configuration expression<enumeration>,
}
}
Properties
Either sni
or keyManager
must be configured.
When both are configured, sni
takes precedence and a warning is logged.
When neither is configured, an exception is thrown and a warning is logged.
"keyManager"
: array of key manager references, required ifsni
isn’t configured-
One or more of the following objects to serve the same secret key and certificate pair for TLS connections to all server names in the deployment:
Key managers are used to prove the identity of the local peer during TLS handshake, as follows:
-
When ServerTlsOptions is used in an HTTPS connector configuration (server-side), the key managers to which ServerTlsOptions refers are used to prove this PingGateway’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 PingGateway’s identity to the remote peer (server-side). This configuration is used in mTLS scenarios.
Default: None
-
"trustManager"
: array of trust manager references, optional-
One or more of the following objects to manage PingGateway’s public key certificates:
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, PingGateway 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 PingGateway uses the default and system certificates -
"sni"
: object, required ifkeyManager
is not configured-
Server Name Indication (SNI) is an extension of the TLS handshake, to serve different secret key and certificate pairs to the TLS connections on different server names. Use this property to host multiple domains on the same machine. For more information, refer to Server Name Indication.
During a TLS handshake, vert.x accesses secret key and certificate pairs synchronously; they are loaded in memory at PingGateway startup, and must be present. You must restart PingGateway to update a secret key and certificate pair.
For an example that uses this property, refer to Serve different certificates for TLS connections to different server names.
{ "sni": { "serverNames": map, "defaultSecretId": configuration expression<secret-id>, "secretsProvider": SecretsProvider reference } }
serverNames
: map, required-
A map of one or more data pairs with the format
Map<String, String>
, where:-
The key is the name of server provided during TLS handshake, or a configuration expression that evaluates to the name
-
The value is a string representing the secret ID of the servers' secret key/certificate pair. Alternatively, it can be a configuration expression that evaluates to that string.
The following format is required:
{ "serverNames": { "configuration expression<string>": "configuration expression<string>", ... } }
In the following example, the keys and values in the map are strings:
"serverNames": { "app1.example.com": "my.app1.secretId", "app2.example.com": "my.app2.secretId", "*.test.com": "my.wildcard.test.secretId" }
In the following example, the keys and values in the map are configuration expressions:
"serverNames": { "${server.name.available.at.config.time}" : "${secret.id.available.at.config.time}" }
Note the following points:
-
One server cannot be mapped to multiple certificates.
PingGateway cannot provide multiple certificates for the same server name, as is allowed by Java’s key managers.
-
Multiple servers can be mapped to one certificate.
Map server names individually. In the following configuration, both server names use the same certificate:
"serverNames": { "cat.com" : "my.secret.id", "dog.org" : "my.secret.id" }
Use the
*
wildcard in the server name to map groups of server names. In the following configuration,app1.example.com
andapp2.example.com
use the same certificate:"serverNames": { "*.example.com": "my.wildcard.secret.id" }
-
-
"defaultSecretId"
: configuration expression<secret-id>, required-
The secret ID representing the certificate to use when an unmapped server name is provided during TLS handshake.
This secret ID must point to a CryptoKey.
For information about how PingGateway manages secrets, refer to About secrets.
"secretsProvider"
: SecretsProvider reference, required-
The SecretsProvider to query for each secret ID.
"sslCipherSuites"
: array of configuration expression<strings>, optional-
Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.
For information about the available cipher suite names, refer to the documentation for the Java virtual machine (JVM) where you run PingGateway. For Oracle Java, refer to the list of JSSE Cipher Suite Names.
Default: Allow any cipher suite supported by the JVM.
"sslContextAlgorithm"
: configuration expression<string>, optional-
The
SSLContext
algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine (JVM).Default:
TLS
"sslEnabledProtocols"
: array of configuration expression<strings>, optional-
Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.
For information about the available protocol names, refer to the documentation for the Java Virtual Machine (JVM). For Oracle Java, refer to the list of Additional JSSE Standard Names.
Follow these protocol recommendations:
-
Use TLS 1.3 when it is supported by available libraries, otherwise use TLS 1.2.
-
If TLS 1.1 or TLS 1.0 is required for backwards compatibility, use it only with express approval from enterprise security.
-
Do not use deprecated versions SSL 3 or SSL 2.
Default: TLS 1.3, TLS 1.2
-
"alpn"
: object, optional-
A flag to enable the Application-Layer Protocol Negotiation (ALPN) extension for TLS connections.
{ "alpn": { "enabled": configuration expression<boolean> } }
enabled
: configuration expression<boolean>, optional-
-
true
: Enable ALPN. Required for HTTP/2 connections over TLS -
false
: Disable ALPN.
-
Default:
true
"clientAuth"
: configuration expression<enumeration>, optional-
The authentication expected from the client. Use one of the following values:
-
REQUIRED
: Require the client to present authentication. If it is not presented, then decline the connection. -
REQUEST
: Request the client to present authentication. If it is not presented, then accept the connection anyway. -
NONE
: Accept the connection without requesting or requiring the client to present authentication.
Default:
NONE
-
RequestResourceUriProvider
Return a resource URL to include in policy decision requests to AM. The PolicyEnforcementFilter uses the returned resource URL as a key to identify cached policy decisions.
To increase performance, use RequestResourceUriProvider in conjunction with AM policies to maximize the the cache hit ratio.
When a request matches a cached policy decision, PingGateway can reuse the decision without asking AM for a new decision. When caching is disabled, PingGateway must ask AM to make a decision for each request.
Usage
"resourceUriProvider": {
"type": "RequestResourceUriProvider",
"config": {
"useOriginalUri": configuration expression<boolean>,
"includeQueryParams": configuration expression<boolean>
}
}
Properties
useOriginalUri
: configuration expression<boolean>, optional-
When 'true`, use the value of
UriRouterContext.originalUri
as the resource URL when requesting policy decisions from AM.When
false
, use the currentRequest.uri
value. Consider that the value might have been modified by thebaseURI
of the route or by any other filter executed before the PolicyEnforcementFilter.Default:
false
includeQueryParams
: configuration expression<boolean>, optional-
When
true
, include query parameters in the resource URL when requesting a policy decision from AM.When
false
, strip all query parameters from the resource URL when requesting a policy decision from AM. To strip some but not all query parameters, use ScriptableResourceUriProvider.Default:
true
ScriptableIdentityAssertionPlugin
An out-of-the box implementation of IdentityAssertionPlugin to support use-cases that aren’t provided by a PingGateway plugin.
Use with an IdentityAssertionHandler for local processing, such as authentication. The plugin returns IdentityAssertionClaims to include in the identity assertion JWT PingGateway sends to PingOne Advanced Identity Cloud.
The script does the following:
-
Validates the identity request JWT.
-
(Optional) Takes a single String that represents the principal or a principal and a map of additional claims from the IdentityRequestJwtContext.
-
If a PreProcessingFilter is configured, triggers the filter.
-
Returns principal and identity claims in the identity assertion JWT.
If script execution fails, the plugin creates an IdentityAssertionPluginException.
Usage
{
"name": string,
"type": "ScriptableIdentityAssertionPlugin",
"config": {
"preProcessingFilter": Filter reference,
"type": configuration expression<string>,
"file": configuration expression<string>, // Use either "file"
"source": [ string, ... ], // or "source", but not both
"args": map,
"clientHandler": Handler reference
}
}
Properties
For information about other properties for ScriptableIdentityAssertionPlugin, refer to Scripts.
Example
The following example applies a preProcessingFilter
that uses a ScriptableFilter
to test whether the user is authenticated. If a Basic Authorization Header isn’t
found, a response is generated to trigger a Basic Authentication.
{ "name": "BasicAuthScriptablePlugin", "type": "ScriptableIdentityAssertionPlugin", "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("iguser", Map.of("auth", "basic"))", "}", "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)", ], }, } } }
ScriptableIdentityAssertionPluginTechPreview
An out-of-the box implementation of IdentityAssertionPluginTechPreview.
Use with an IdentityAssertionHandlerTechPreview for local processing, such as authentication. The plugin returns IdentityAssertionClaims to include in the outgoing JWT sent to PingOne Advanced Identity Cloud.
The IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview are available in Technology preview. 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 PingOne Advanced Identity Cloud.
Usage
{
"name": string,
"type": "ScriptableIdentityAssertionPluginTechPreview",
"config": {
"preProcessingFilter": Filter reference,
"type": configuration expression<string>,
"file": configuration expression<string>, // 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.
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)", ], }, } } }
TemporaryStorage
Allocates temporary buffers for caching streamed content during request processing. Initially uses memory; when the memory limit is exceeded, switches to a temporary file.
Usage
{
"name": string,
"type": "TemporaryStorage",
"config": {
"initialLength": configuration expression<number>,
"memoryLimit": configuration expression<number>,
"fileLimit": configuration expression<number>,
"directory": configuration expression<string>
}
}
Properties
"initialLength"
: configuration expression<number>, optional-
Initial size of the memory buffer.
Default: 8 192 bytes (8 KB). Maximum: The value of
"memoryLimit"
. "memoryLimit"
: configuration expression<number>, optional-
Maximum size of the memory buffer. When the memory buffer is full, the content is transferred to a temporary file.
Default: 65 536 bytes (64 KB). Maximum: 2 147 483 647 bytes (2 GB).
"fileLimit"
: configuration expression<number>, optional-
Maximum size of the temporary file. If the file is bigger than this value, PingGateway responds with an OverflowException.
Default: 1 073 741 824 bytes (1 GB). Maximum: 2 147 483 647 bytes (2 GB).
"directory"
: configuration expression<string>, optional-
The directory where temporary files are created.
Default:
$HOME/.openig/tmp
(on Windows,%appdata%\OpenIG\OpenIG\tmp
)
TrustAllManager
Blindly trusts all server certificates presented the servers for protected applications. It can be used instead of a TrustManager in test environments to trust server certificates that were not signed by a well-known CA, such as self-signed certificates.
The TrustAllManager is not safe for production use. Use a properly configured TrustManager instead.
Example
The following example configures a client handler that blindly trusts server certificates when PingGateway connects to servers over HTTPS:
{
"name": "BlindTrustClientHandler",
"type": "ReverseProxyHandler",
"config": {
"trustManager": {
"type": "TrustAllManager"
}
}
}
UmaService
The UmaService includes a list of resource patterns and associated actions that define the scopes for permissions to matching resources. When creating a share using the REST API described below, you specify a path matching a pattern in a resource of the UmaService.
Usage
{
"name": string,
"type": "UmaService",
"config": {
"protectionApiHandler": Handler reference,
"amService": AmService reference, // Use either "amService"
"wellKnownEndpoint": configuration expression<url>, // or "wellKnownEndpoint", but not both.
"resources": [ object, ... ]
}
}
Properties
"protectionApiHandler"
: Handler reference, required-
The handler to use when interacting with the UMA Authorization Server to manage resource sets, such as a ClientHandler capable of making an HTTPS connection to the server.
For more information, refer to Handlers.
"amService"
: AmService reference, required ifwellKnownEndpoint
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 overwellKnownEndpoint
.For more information, refer to UMA discovery in AM’s User-Managed Access (UMA) 2.0 guide.
See also AmService.
"wellKnownEndpoint"
: configuration expression<url>, required ifamService
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 overwellKnownEndpoint
.Examples:
-
In this example, the UMA configuration is in the default realm of AM:
https://am.example.com:8088/openam/uma/.well-known/uma2-configuration
-
In this example, the UMA configuration is in a European customer realm:
https://am.example.com:8088/openam/uma/realms/root/realms/customer/realms/europe/.well-known/uma2-configuration
For more information, refer to AM as UMA Authorization Server in AM’s User-Managed Access (UMA) 2.0 guide.
-
"resources"
: array of objects, required-
Resource objects matching the resources the resource owner wants to share.
Each resource object has the following form:
{ "pattern": resource pattern, "actions": [ { "scopes": [ scope string, ... ], "condition": runtime expression<boolean> }, { ... } ] }
Each resource pattern can represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways:
-
When registering a resource set, PingGateway uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used.
-
When responding to an initial request for a resource, PingGateway derives the scopes for the ticket based on the scopes that apply according to the request.
-
When verifying the RPT, PingGateway checks that all required scopes are encoded in the RPT.
A description of each field follows:
"pattern"
: pattern, required-
A pattern matching resources to be shared by the resource owner, such as
.*
to match any resource path, and/photos/.*
to match paths starting with/photos/
.See also Patterns.
"actions"
: array of objects, optional-
A set of scopes to authorize when the corresponding condition evaluates to
true
."actions": [ { "scopes": [ "#read" ], "condition": "${request.method == 'GET'}" }, { "scopes": [ "#create" ], "condition": "${request.method == 'POST'}" } ]
"scopes"
: array of configuration expression<strings>, optional-
One or more scopes that are authorized when the corresponding condition evaluates to
true
.For example, the scope
#read
grants read-access to a resource. "condition"
: runtime expression<boolean>, required-
When the condition evaluates to
true
, the corresponding scope is authorized.For example, the condition
${request.method == 'GET'}
is true when reading a resource.
-
REST API for shares
The REST API for UMA shares is exposed at a registered endpoint. PingGateway
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
PingGateway scheme, host, and port to obtain a full URL, such as
http://localhost:8080/openig/api/system/objects/_router/routes/00-uma/objects/umaservice/share
.
The UMA REST API supports create (POST only), read, delete, and query
(_queryFilter=true
only). For an introduction to common REST APIs, refer to
About ForgeRock Common REST.
In the present implementation, PingGateway does not have a mechanism for persisting shares. When PingGateway stops, the shares are discarded.
For information about API descriptors for the UMA share endpoint, refer to API descriptors. For information about Common REST, refer to About ForgeRock Common REST.
A share object has the following form:
{
"path": pattern,
"pat": UMA protection API token (PAT) string,
"id": unique identifier string,
"resource_id": unique identifier string,
"user_access_policy_uri": URI string
}
"path"
: pattern, required-
A pattern matching the path to protected resources, such as
/photos/.*
.This pattern must match a pattern defined in the UmaService for this API.
See also Patterns.
"pat"
: PAT string, required-
A PAT granted by the UMA Authorization Server given consent by the resource owner.
In the present implementation, PingGateway 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.