IG 7.1.2

Handlers

Handler objects process a request and context, and return a response. The way the response is created depends on the type of handler.

IG provides the following handlers:

Chain

Dispatches a request and context to an ordered list of filters, and then finally to a handler.

Filters process the incoming request and context, pass it on to the next filter, and then to the handler. After the handler produces a response, the filters process the outgoing response and context as it makes its way to the client. Note that the same filter can process both the incoming request and the outgoing response but most filters do one or the other.

A Chain can be placed in a configuration anywhere that a handler can be placed.

Unlike ChainOfFilters, Chain finishes by dispatching the request to a handler. For more information, see ChainOfFilters.

Usage

{
     "name": string,
     "type": "Chain",
     "config": {
         "filters": [ Filter reference, ... ],
         "handler": Handler reference
     }
}

Properties

"filters": array of filter references, required

An array of names of filter objects defined in the heap, and inline filter configuration objects.

The chain dispatches the request to these filters in the order they appear in the array.

See also Filters.

"handler": Handler reference, required

Either the name of a handler object defined in the heap, or an inline handler configuration object.

The chain dispatches to this handler after the request has traversed all of the specified filters.

See also Handlers.

Example

{
     "name": "LoginChain",
     "type": "Chain",
     "config": {
         "filters": [ "LoginFilter" ],
         "handler": "ReverseProxyHandler"
     }
}

More Information

org.forgerock.openig.filter.ChainHandlerHeaplet

ClientHandler

Creates a response to a request by forwarding the request to a third-party service accessible through HTTP, and reconstructing the response from the received bytes.

When IG relays the request to the third-party service, IG is acting as a client of the service. IG is client-side.

A third-party service is one that IG calls for data, such as an HTTP API or AM, or one to which IG submits data.

If IG fails to connect to the third-party service, the ClientHandler propagates the error along the chain.

Use ClientHandler to submit requests to third-party services such as AM or HTTP APIs. Do not use it to proxy requests to a protected application. To proxy requests to a protected application, use a ReverseProxyHandler instead.

Usage

{
  "name": string,
  "type": "ClientHandler",
  "config": {
    "connections": configuration expression<number>,
    "disableReuseConnection": configuration expression<boolean>,
    "stateTrackingEnabled": configuration expression<boolean>,
    "hostnameVerifier": configuration expression<enumeration>,
    "soTimeout": duration string,
    "connectionTimeout": duration string,
    "connectionTimeToLive": duration string,
    "numberOfWorkers": configuration expression<number>,
    "protocolVersion": configuration expression<enumeration>,
    "http2PriorKnowledge": configuration expression<boolean>,
    "proxy": Server reference,
    "systemProxy": boolean,
    "temporaryStorage": string,
    "tls": ClientTlsOptions reference,
    "asyncBehavior": enumeration,
    "retries": object,
    "websocket": object
  }
}

Properties

"connections": configuration expression<number>, optional

When IG is in standalone mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool, for each Vert.x HTTP client. The number of Vert.x HTTP clients is configured by the gatewayUnits property of admin.json. For example, when connections = 64, and gatewayUnits = 3, the maximum number of concurrent HTTP/1.1 connections in the client connection pool is 192.

When IG is in web container mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool. Default: 64

"connectionTimeout": duration string, optional

Time to wait to establish a connection, expressed as a duration

Default: 10 seconds

"connectionTimeToLive": duration string, optional
Not supported for IG in standalone mode.

Amount of time before a reusable pooled connection expires.

Set this property to expire reusable pooled connections after a fixed duration. For example, to prevent the reuse of connections set this property in routes for applications where the IP address (baseURI) is not stable or can change.

Default: Unlimited

"disableReuseConnection": configuration expression<boolean>, optional

Supported only for IG in web container mode.

Whether to disable connection reuse.

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported for IG in standalone mode.

By default, the Apache HTTP Client does not allow connection reuse when a client certificate is used for authentication. However, because the client certificate is defined at the client level, it is acceptable for requests to the same target to share a client certificate.

Use in combination with disableReuseConnection:

disableReuseConnection stateTrackingEnabled Description

false (default)

true (default)

Do not allow connection reuse when a client certificate is used for authentication.

false (default)

false

Allow connection reuse when a client certificate is used for authentication.

true

true (default) or false

Do not allow connection reuse.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

Way to handle hostname verification for outgoing SSL connections. 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.

    This setting allows a certificate issued for one company to be accepted as a valid certificate for another company.

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

  • 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

"numberOfWorkers": configuration expression<number>, optional

Not supported for IG in standalone mode.

The number of worker threads dedicated to processing outgoing requests.

Increasing the value of this attribute can be useful in deployments where a high number of simultaneous connections remain open, waiting for protected applications to respond.

Default: One thread per CPU available to the JVM.

"protocolVersion": configuration expression<enumeration>, optional

Supported only for IG in standalone mode.

The version of HTTP protocol to use when processing requests:

  • HTTP/2:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS, process requests using HTTP/2.

  • HTTP/1.1:

    • For HTTP and HTTPS, process requests using HTTP/1.1.

  • Not set:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS with alpn enabled in ClientTlsOptions, process requests using HTTP/1.1, with an HTTP/2 upgrade request. If the targeted server can use HTTP/2, the client uses HTTP/2.

      For HTTPS with alpn disabled in ClientTlsOptions, process requests using HTTP/1.1, without an HTTP/2 upgrade request.

      Note that alpn is enabled by default in ClientTlsOptions.

    Default: Not set

In HTTP/1.1 request messages, a Host header is required to specify the host and port number of the requested resource. In HTTP/2 request messages, the Host header is not available.

In scripts or custom extensions that use HTTP/2, use UriRouterContext.originalUri.host or UriRouterContext.originalUri.port in requests.
"http2PriorKnowledge": configuration expression<boolean>, optional

This property is used only when IG is running in standalone mode, and when protocolVersion is HTTP/2.

Specifies whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only.

  • false: The client checks whether the server supports HTTP/2 by sending an HTTP/1.1 request to upgrade the connection to HTTP/2:

    • If the server supports HTTP/2, the server upgrades the connection to HTTP/2, and subsequent requests are processed over HTTP/2.

    • If the server does not support HTTP/2, the connection is not upgraded, and subsequent requests are processed over HTTP/1.

  • true: The client does not check that the server supports HTTP/2. The client sends HTTP/2 requests to the server, assuming that the server supports HTTP/2.

Default: false

"proxy": Server 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.

If both proxy and systemProxy are defined, proxy takes precedence.

"proxy" : {
  "uri": configuration expression<uri string>,
  "username": configuration expression<string>,
  "passwordSecretId": configuration expression<secret-id>,
  "secretsProvider": SecretsProvider reference
}
uri: configuration expression<uri string>, 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.

For information about supported formats for secret-id, see secret-id.

"secretsProvider": SecretsProvider reference, optional

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

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

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

"handler": {
  "type": "ClientHandler",
  "config": {
     "proxy": {
        "uri": "http://proxy.example.com:3128",
        "username": "proxyuser",
        "passwordSecretId": "myproxy.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore"
     }
  }
}
"soTimeout": duration string, optional

Socket timeout, after which stalled connections are destroyed, expressed as a duration

Default: 10 seconds

"systemProxy": boolean, optional

Submit outgoing requests to a system-defined proxy, set by the following system properties or their HTTPS equivalents:

  • http.proxyHost, the host name of the proxy server.

  • http.proxyPort, the port number of the proxy server. The default is 80.

  • http.nonProxyHosts, a list of hosts that should be reached directly, bypassing the proxy.

    This property can’t be used with a proxy that requires a username and password. Use the property proxy instead.

    If both proxy and systemProxy are defined, proxy takes precedence.

    For more information, see Java Networking and Proxies.

    Default: False.

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

Default: The temporary storage object named TemporaryStorage, declared in the top-level heap.

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on ClientTlsOptions. Define the object inline or in the heap.

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

"asyncBehavior": enumeration, optional

Specifies how the HTTP client behaves for asynchronous responses. Set the value to streaming or non_streaming:

  • streaming: ( Not supported for IG in standalone mode )

    Responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. The value is not case-sensitive.

    Streaming mode reduces latency and is mandatory for Server-Sent Events (SSE) and the support of very large files (bigger than 2 GB). If thread starvation occurs, consider increasing numberOfWorkers, the number of worker threads dedicated to processing outgoing requests.

  • non_streaming:

    Responses are processed when the entity content is entirely available. The value is not case-sensitive.

    Non-streaming mode does not support SSE or very large files. However, it has higher latency, and does not cause thread starvation.

Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

When a runtime error occurs during the execution of a request to a remote server, IG schedules a new execution of the request after the specified delay, until the allowed number of retries is reached or the execution succeeds.

A WARN level entry is logged if all retry attempts fail. A DEBUG level entry is logged if retries succeed, capturing the number of retries.

"enabled": boolean, optional

Enable retries.

Default: true

"executor": ScheduledExecutorService reference, optional

The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService

See also ScheduledExecutorService.

"count": number, optional

The maximum number of retries to perform. After this threshold is passed and if the request is still not successful, then the ClientHandler propagates the failure.

Default: 5

"delay": duration, optional

The time to wait before retrying the request.

After a failure to send the request, if the number of retries is below the threshold, a new attempt is scheduled with the executor service after this delay.

Default: 10 seconds

The following example configures the handler to retry the request only once, after a 1-minute delay:

{
  "retries": {
    "count": 1,
    "delay": "1 minute"
  }
}

The following example configures the handler to retry the request at most 20 times, every second:

{
  "retries": {
    "count": 20,
    "delay": "1 second"
  }
}

The following example configures the handler to retry the request 5 times, every 10 seconds (default values), with a dedicated executor:

{
  "retries": {
    "executor": {
      "type": "ScheduledExecutorService",
      "config": {
        "corePoolSize": 20
      }
    }
  }
}
"websocket": object, optional

Enable upgrade from HTTP or HTTPS protocol to WebSocket protocol.

For IG in standalone mode, list the subprotocols that are proxied by IG in the vertx property of AdminHttpApplication (admin.json).

For more information and an example of proxying WebSocket traffic, see Proxy WebSocket Traffic

When IG is running in Jetty, it cannot proxy WebSocket traffic. 
{
  "websocket": {
    "enabled": boolean,
    "connectionTimeout": duration string,
    "soTimeout": duration string,
    "numberOfSelectors": number,
    "tls": ClientTlsOptions reference,
    "vertx": object
  }
}

For more information, see The WebSocket Protocol, RFC6455.

"enabled": boolean, optional

Enable upgrade from HTTP protocol and HTTPS protocol to WebSocket protocol.

Default: false

"connectionTimeout": duration string, optional

The maximum time allowed to establish a WebSocket connection.

Default: The value of handler’s main connectionTimeout.

"soTimeout": duration string, optional

The time after which stalled connections are destroyed.

If there can be long delays between messages, consider increasing this value. Alternatively, keep the connection active by using WebSocket ping messages in your application.

Default: The value of handler’s main soTimeout.

"numberOfSelectors": number, optional

The maximum number of worker threads.

In deployments with a high number of simultaneous connections, consider increasing the value of this property.

Default: 2

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on a ClientTlsOptions configuration. Define a ClientTlsOptions object inline or in the heap.

Default: Use ClientTlsOptions defined for the handler

vertx: object, optional

Vert.x-specific configuration for this connector, where IG does not provide its own first-class configuration. Vert.x options are described in HttpClientOptions.

For properties where IG provides its own first-class configuration, Vert.x configuration options are disallowed, and the IG configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed client-side:

  • port

  • connectTimeout

  • idleTimeout

  • idleTimeoutUnit

  • protocolVersion

  • http2ClearTextUpgrade

  • verifyHost

  • ssl

  • enabledSecureTransportProtocols

  • enabledCipherSuites

  • proxyOptions

  • keyStoreOptions

  • keyCertOptions

  • pemKeyCertOptions

  • pfxKeyCertOptions

  • trustOptions

  • trustStoreOptions

  • pemTrustOptions

  • pfxTrustOptions

  • useAlpn

  • alpnVersions

The following default vertx configuration provided by this handler overrides the Vert.x defaults:

  • tryUsePerFrameWebSocketCompression = true

  • tryUsePerMessageWebSocketCompression = true

The following example configures the maximum frame size and message size for Websocket connections:

"vertx": {
  "maxWebSocketFrameSize": 200000000,
  "maxWebSocketMessageSize": 200000000,
  "tryUsePerMessageWebSocketCompression": true
}

Example

The following object configures a ClientHandler named Client:

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

More Information

org.forgerock.openig.handler.ClientHandlerHeaplet

DesKeyGenHandler

This object is deprecated and likely to be removed in a future release.

Consider using AM’s password replay post-authentication plugin class com.sun.identity.authentication.spi.JwtReplayPassword. The plugin encrypts the password captured by AM during authentication, and stores it in a session property. IG looks up the property, decrypts it, and replays the password. For an example, see Get Login Credentials From AM.

Generates a DES key for use with AM.

Usage

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

More Information

org.forgerock.openig.handler.DesKeyGenHandler

DispatchHandler

When a request is handled, the first condition in the list of conditions is evaluated. If the condition expression yields true, the request is dispatched to the associated handler with no further processing. Otherwise, the next condition in the list is evaluated.

Usage

{
  "name": string,
  "type": "DispatchHandler",
  "config": {
    "bindings": [
      {
        "condition": runtime expression<boolean>,
        "handler": Handler reference,
        "baseURI": runtime expression<uri string>,
      }, ...
    ]
  }
}

Properties

"bindings": array of objects, required

A list of bindings of conditions and associated handlers to dispatch to.

"condition": runtime expression<boolean>, optional

An inline expression to define a condition based on the request, context, or IG runtime environment, such as system properties or environment variables.

Conditions are defined using IG expressions, as described in Expressions, and are evaluated as follows:

  • If the condition evaluates to true, the request is dispatched to the associated handler.

  • If the condition evaluates to false, the next condition in the list is evaluated.

  • If no condition is specified, the request is dispatched unconditionally to the associated handler.

For example conditions and requests that match them, see Example Conditions and Requests.

Default: No condition is specified.

"handler": Handler reference, required

A handler to dispatch the request to if the associated condition yields true, or if there is no associated condition.

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

See also Handlers.

"baseURI": runtime expression<uri string>, optional

A base URI that overrides the existing request URI. Only scheme, host, and port are used in the supplied URI.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

In the following example, the binding condition looks up the hostname of the request. If it finds a match, the value is used for the baseURI. Otherwise, the default value is used:

{
  "properties": {
    "uris": {
      "app1.example.com": {
        "baseURI": "http://backend1:8080/"
      },
      "app2.example.com": {
        "baseURI": "http://backend2:8080/"
      },
      "default": {
        "baseURI": "http://backend3:8080/"
      }
    }
  },
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${not empty uris[contexts.router.originalUri.host]}",
          "baseURI": "${uris[contexts.router.originalUri.host].baseURI}",
          "handler": "ReverseProxyHandler"
        },
        {
          "baseURI": "${uris['default'].baseURI}",
          "handler": "ReverseProxyHandler"
        }
      ]
    }
  }
}

Default: No change to the base URI

Example

The following sample is from a SAML 2.0 federation configuration:

  • If the incoming URI matches /saml, then IG dispatches to a SamlFederationHandler without further processing.

  • If the previous condition is not met, and the user name is not set in the session context, then IG dispatches the request to a SPInitiatedSSORedirectHandler.

    In this case, the user has not authenticated with the SAML 2.0 Identity Provider, so the SPInitiatedSSORedirectHandler initiates SAML 2.0 SSO from the Service Provider, which is IG.

  • If neither of the previous conditions are met, the request goes through a LoginChain handler.

{
    "name": "DispatchHandler",
    "type": "DispatchHandler",
    "config": {
        "bindings": [
            {
                "condition": "${find(request.uri.path, '^/saml')}",
                "handler": "SamlFederationHandler"
            },
            {
                "condition": "${empty session.username}",
                "handler": "SPInitiatedSSORedirectHandler",
                "baseURI": "http://www.example.com:8081"
            },
            {
                "handler": "LoginChain",
                "baseURI": "http://www.example.com:8081"
            }
        ]
    }
}

More Information

org.forgerock.openig.handler.DispatchHandler

Expressions

ForgeRockClientHandler

The ForgeRockClientHandler is a Handler available by default on the heap that chains a default ClientHandler with a TransactionIdOutboundFilter. This supports ForgeRock audit by supporting the initiation or propagation of audit information from IG to the audit framework. For more information, see AuditService.

The following default ForgeRockClientHandler is available as a default object on the heap, and can be referenced by the name ForgeRockClientHandler.

{
     "name": "ForgeRockClientHandler",
     "type": "Chain",
     "config": {
         "filters": [ "TransactionIdOutboundFilter" ],
         "handler": "ClientHandler"
     }
}

Example

For an example that uses ForgeRockClientHandler to log interactions between IG and AM, see Decorating IG’s Interactions With AM.

More Information

org.forgerock.openig.heap.Keys

JwkSetHandler

Expose cryptographic keys cryptographic keys as JWK set. Use this handler so that a downstream application can reuse the exposed keys for their assigned purpose.

Consider the following limitations:

  • When the public key is not available, the corresponding private key cannot be exposed. Note, however, that it is not recommended to expose private keys as JWK.

  • Keys in secure storage, such as a Hardware Security Module (HSM) or remote server, cannot be exposed.

For a description of how secrets are managed, see Secrets.

For information about JWKs and JWK Sets, see RFC-7517, JSON Web Key (JWK).

Usage

{
  "name": string,
  "type": "JwkSetHandler",
  "config": {
    "secretsProvider": SecretsProvider reference,
    "purposes": [ configuration object, ... ]
  }
}
"secretsProvider": SecretsProvider reference, required

The SecretsProvider to use to resolve the secret. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"purposes": array of objects, required

One or more purposes for the secret.

{
  "purposes": [
    {
      "secretId":  configuration expression<secret-id>,
      "keyUsage": configuration expression<enumeration>
    },
    ...
  ]
}
"secretId": configuration expression<secret-id>, required

The secret ID of the key used by the JwtBuilderFilter to sign or encrypt the JWT.

"keyUsage": configuration expression<enumeration>, required

The allowed use of the key:

  • AGREE_KEY: Export the private key used in the key agreement protocol, for example, Diffie-Hellman.

  • ENCRYPT: Export the public key used to encrypt data.

  • DECRYPT: Export the private key used to decrypt data.

  • SIGN: Export the private key used to sign data.

  • VERIFY: Export the public key used to verify signature data.

  • WRAP_KEY: Export the public key used to encrypt (wrap) other keys.

  • UNWRAP_KEY: Export the private key used to decrypt (unwrap) other keys.

Examples

This example uses a JwkSetHandler to expose a signing key used by the JwtBuilderFilter:

  1. Set an environment variable for the base64-encoded secret to sign the JWT:

    $ export SIGNING_KEY_SECRET_ID='cGFzc3dvcmQ='

  2. Add the following route to IG:

    • Linux

    • Windows

    $HOME/.openig/config/routes/jwksethandler.json
    appdata\OpenIG\config\routes\jwksethandler.json
    {
  "name": "jwksethandler",
  "condition": "${find(request.uri.path, '/jwksethandler')}",
  "heap": [
    {
      "name": "SecretKeyPropertyFormat-1",
      "type": "SecretKeyPropertyFormat",
      "config": {
        "format": "BASE64",
        "algorithm": "AES"
      }
    },
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore",
      "config": {
        "mappings": [{
          "secretId": "signing.key.secret.id",
          "format": "SecretKeyPropertyFormat-1"
        }]
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "JwtBuilderFilter-1",
          "type": "JwtBuilderFilter",
          "config": {
            "template": {
              "name": "${contexts.userProfile.commonName}",
              "email": "${contexts.userProfile.rawInfo.mail[0]}"
            },
            "secretsProvider": "SystemAndEnvSecretStore-1",
            "signature": {
              "secretId": "signing.key.secret.id",
              "algorithm": "HS256"
            }
          }
        }
      ],
      "handler": {
        "type": "JwkSetHandler",
        "config": {
          "secretsProvider": "SystemAndEnvSecretStore-1",
          "purposes": [{
            "secretId": "signing.key.secret.id",
            "keyUsage": "SIGN"
          }]
        }
      }
    }
  }
}

    Notice the following features of the route:

    • The route matches requests to /jwksethandler.

    • The JWT signing key is managed by the SysEnvStoreSecretStore in the heap, which refers to the SecretKeyPropertyFormat for the secret’s format.

    • The JwtBuilderFilter signature property refers to the JWT signing key in the SysEnvStoreSecretStore.

    • The JwkSetHandler refers to the JWT signing key.

  3. Go to http://openig.example.com:8080/jwksethandler.

    The signing key is displayed as an array, as follows:

    {
  "keys": [
    {
      "k": "cGFzc3dvcmQ",
      "kid": "signing.key.secret.id",
      "kty": "oct",
      "use": "sig"
    }
  ]
}

    The JWK set secret is ULR base64-encoded. Although the secret is set with the value cGFzc3dvcmQ=, the value cGFzc3dvcmQ is exposed.

More Information

org.forgerock.openig.handler.JwkSetHandler

ReverseProxyHandler

Proxy requests to protected applications.

When IG relays the request to the protected application, IG is acting as a client of the application. IG is client-side.

(Not supported for IG in standalone mode.) If the request is to upload or download a large file to or from the protected application, consider setting asyncBehavior to streaming, and increasing the value of soTimeout.

If IG fails to connect to the protected application, the ReverseProxyHandler does not propagate the error along the chain. Instead, it changes the runtime exception into a 502 Bad Gateway response.

Use ReverseProxyHandler in a route to proxy requests to a protected application. To submit requests to third-party services, such as AM or HTTP APIs, use a ClientHandler instead.

Usage

{
  "name": string,
  "type": "ReverseProxyHandler",
  "config": {
    "connections": configuration expression<number>,
    "disableReuseConnection": configuration expression<boolean>,
    "stateTrackingEnabled": configuration expression<boolean>,
    "hostnameVerifier": configuration expression<enumeration>,
    "soTimeout": duration string,
    "connectionTimeout": duration string,
    "connectionTimeToLive": duration string,
    "numberOfWorkers": configuration expression<number>,
    "protocolVersion": configuration expression<enumeration>,
    "http2PriorKnowledge": configuration expression<boolean>,
    "proxy": Server reference,
    "systemProxy": boolean,
    "temporaryStorage": string,
    "tls": ClientTlsOptions reference,
    "asyncBehavior": enumeration,
    "retries": object,
    "websocket": object
  }
}

Properties

"connections": configuration expression<number>, optional

When IG is in standalone mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool, for each Vert.x HTTP client. The number of Vert.x HTTP clients is configured by the gatewayUnits property of admin.json. For example, when connections = 64, and gatewayUnits = 3, the maximum number of concurrent HTTP/1.1 connections in the client connection pool is 192.

When IG is in web container mode, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool. Default: 64

"connectionTimeout": duration string, optional

Amount of time to wait to establish a connection, expressed as a duration

Default: 10 seconds

"connectionTimeToLive": duration string, optional
Not supported for IG in standalone mode.

Amount of time before a reusable pooled connection expires.

Set this property to expire reusable pooled connections after a fixed duration. For example, to prevent the reuse of connections set this property in routes for applications where the IP address (baseURI) is not stable or can change.

Default: Unlimited

"disableReuseConnection": configuration expression<boolean>, optional

Supported only for IG in web container mode.

Whether to disable connection reuse.

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported for IG in standalone mode.

By default, the Apache HTTP Client does not allow connection reuse when a client certificate is used for authentication. However, because the client certificate is defined at the client level, it is acceptable for requests to the same target to share a client certificate.

Use in combination with disableReuseConnection:

disableReuseConnection stateTrackingEnabled Description

false (default)

true (default)

Do not allow connection reuse when a client certificate is used for authentication.

false (default)

false

Allow connection reuse when a client certificate is used for authentication.

true

true (default) or false

Do not allow connection reuse.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

Way to handle hostname verification for outgoing SSL connections. 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.

    This setting allows a certificate issued for one company to be accepted as a valid certificate for another company. To prevent the compromise of TLS connections, use this setting in development mode only. In production, use STRICT.

  • 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

"numberOfWorkers": configuration expression<number>, optional

Not supported for IG in standalone mode.

The number of worker threads dedicated to processing outgoing requests.

Increasing the value of this attribute can be useful in deployments where a high number of simultaneous connections remain open, waiting for protected applications to respond.

Default: One thread per CPU available to the JVM.

"protocolVersion": configuration expression<enumeration>, optional

Supported only for IG in standalone mode.

The version of HTTP protocol to use when processing requests:

  • HTTP/2:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS, process requests using HTTP/2.

  • HTTP/1.1:

    • For HTTP and HTTPS, process requests using HTTP/1.1.

  • Not set:

    • For HTTP, process requests using HTTP/1.1.

    • For HTTPS with alpn enabled in ClientTlsOptions, process requests using HTTP/1.1, with an HTTP/2 upgrade request. If the targeted server can use HTTP/2, the client uses HTTP/2.

      For HTTPS with alpn disabled in ClientTlsOptions, process requests using HTTP/1.1, without an HTTP/2 upgrade request.

      Note that alpn is enabled by default in ClientTlsOptions.

    Default: Not set

In HTTP/1.1 request messages, a Host header is required to specify the host and port number of the requested resource. In HTTP/2 request messages, the Host header is not available.

In scripts or custom extensions that use HTTP/2, use UriRouterContext.originalUri.host or UriRouterContext.originalUri.port in requests.
"http2PriorKnowledge": configuration expression<boolean>, optional

This property is used only when IG is running in standalone mode, and when protocolVersion is HTTP/2.

Specifies whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only.

  • false: The client checks whether the server supports HTTP/2 by sending an HTTP/1.1 request to upgrade the connection to HTTP/2:

    • If the server supports HTTP/2, the server upgrades the connection to HTTP/2, and subsequent requests are processed over HTTP/2.

    • If the server does not support HTTP/2, the connection is not upgraded, and subsequent requests are processed over HTTP/1.

  • true: The client does not check that the server supports HTTP/2. The client sends HTTP/2 requests to the server, assuming that the server supports HTTP/2.

Default: false

"proxy": Server 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, to submit requests from an internal network to the internet.

If both proxy and systemProxy are defined, proxy takes precedence.

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

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

"handler": {
  "type": "ReverseProxyHandler",
  "config": {
     "proxy": {
        "uri": "http://proxy.example.com:3128",
        "username": "proxyuser",
        "passwordSecretId": "myproxy.secret.id"
     }
  }
}
"soTimeout": duration string, optional

Socket timeout, after which stalled connections are destroyed, expressed as a duration

If SocketTimeoutException errors occur in the logs when you try to upload or download large files, consider increasing soTimeout.

Default: 10 seconds

"systemProxy": boolean, optional

Submit outgoing requests to a system-defined proxy, set by the following system properties or their HTTPS equivalents:

  • http.proxyHost, the host name of the proxy server.

  • http.proxyPort, the port number of the proxy server. The default is 80.

  • http.nonProxyHosts, a list of hosts that should be reached directly, bypassing the proxy.

    This property can’t be used with a proxy that requires a username and password. Use the property proxy instead.

    If both proxy and systemProxy are defined, proxy takes precedence.

    For more information, see Java Networking and Proxies.

    Default: False.

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

Default: The temporary storage object named TemporaryStorage, declared in the top-level heap.

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on ClientTlsOptions. Define the object inline or in the heap.

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

"asyncBehavior": enumeration, optional

Specifies how the HTTP client behaves for asynchronous responses. Set the value to streaming or non_streaming:

  • streaming: Not supported in standalone mode

    Responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. The value is not case-sensitive.

    Streaming mode reduces latency and is mandatory for Server-Sent Events (SSE) and the support of very large files (bigger than 2 GB). If thread starvation occurs, consider increasing numberOfWorkers, the number of worker threads dedicated to processing outgoing requests.

  • non_streaming: Responses are processed when the entity content is entirely available. The value is not case-sensitive.

    Non-streaming mode does not support SSE or very large files. However, it has higher latency, and does not cause thread starvation.

    If timeout errors occur in the logs, consider setting soTimeout to limit the timeout, and setting asyncBehavior to non_streaming.

    Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

When a runtime error occurs during the execution of a request to a remote server, IG schedules a new execution of the request after the specified delay, until the allowed number of retries is reached or the execution succeeds.

A WARN level entry is logged if all retry attempts fail. A DEBUG level entry is logged if retries succeed, capturing the number of retries.

"enabled": boolean, optional

Enable retries.

Default: true

"executor": ScheduledExecutorService reference, optional

The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService

See also ScheduledExecutorService.

"count": number, optional

The maximum number of retries to perform. After this threshold is passed and if the request is still not successful, then the ClientHandler propagates the failure.

Default: 5

"delay": duration, optional

The time to wait before retrying the request.

After a failure to send the request, if the number of retries is below the threshold, a new attempt is scheduled with the executor service after this delay.

Default: 10 seconds

The following example configures the handler to retry the request only once, after a 1-minute delay:

{
  "retries": {
    "count": 1,
    "delay": "1 minute"
  }
}

The following example configures the handler to retry the request at most 20 times, every second:

{
  "retries": {
    "count": 20,
    "delay": "1 second"
  }
}

The following example configures the handler to retry the request 5 times, every 10 seconds (default values), with a dedicated executor:

{
  "retries": {
    "executor": {
      "type": "ScheduledExecutorService",
      "config": {
        "corePoolSize": 20
      }
    }
  }
}
"websocket": object, optional

Enable upgrade from HTTP or HTTPS protocol to WebSocket protocol.

For IG in standalone mode, list the subprotocols that are proxied by IG in the vertx property of AdminHttpApplication (admin.json).

For more information and an example of proxying WebSocket traffic, see Proxy WebSocket Traffic

When IG is running in Jetty, it cannot proxy WebSocket traffic. 
{
  "websocket": {
    "enabled": boolean,
    "connectionTimeout": duration string,
    "soTimeout": duration string,
    "numberOfSelectors": number,
    "tls": ClientTlsOptions reference,
    "vertx": object
  }
}

For more information, see The WebSocket Protocol, RFC6455.

"enabled": boolean, optional

Enable upgrade from HTTP protocol and HTTPS protocol to WebSocket protocol.

Default: false

"connectionTimeout": duration string, optional

The maximum time allowed to establish a WebSocket connection.

Default: The value of handler’s main connectionTimeout.

"soTimeout": duration string, optional

The time after which stalled connections are destroyed.

If there can be long delays between messages, consider increasing this value. Alternatively, keep the connection active by using WebSocket ping messages in your application.

Default: The value of handler’s main soTimeout.

"numberOfSelectors": number, optional

The maximum number of worker threads.

In deployments with a high number of simultaneous connections, consider increasing the value of this property.

Default: 2

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on a ClientTlsOptions configuration. Define a ClientTlsOptions object inline or in the heap.

Default: Use ClientTlsOptions defined for the handler

vertx: object, optional

Vert.x-specific configuration for this connector, where IG does not provide its own first-class configuration. Vert.x options are described in HttpClientOptions.

For properties where IG provides its own first-class configuration, Vert.x configuration options are disallowed, and the IG configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed client-side:

  • port

  • connectTimeout

  • idleTimeout

  • idleTimeoutUnit

  • protocolVersion

  • http2ClearTextUpgrade

  • verifyHost

  • ssl

  • enabledSecureTransportProtocols

  • enabledCipherSuites

  • proxyOptions

  • keyStoreOptions

  • keyCertOptions

  • pemKeyCertOptions

  • pfxKeyCertOptions

  • trustOptions

  • trustStoreOptions

  • pemTrustOptions

  • pfxTrustOptions

  • useAlpn

  • alpnVersions

The following default vertx configuration provided by this handler overrides the Vert.x defaults:

  • tryUsePerFrameWebSocketCompression = true

  • tryUsePerMessageWebSocketCompression = true

The following example configures the maximum frame size and message size for Websocket connections:

"vertx": {
  "maxWebSocketFrameSize": 200000000,
  "maxWebSocketMessageSize": 200000000,
  "tryUsePerMessageWebSocketCompression": true
}

More Information

org.forgerock.openig.handler.ReverseProxyHandlerHeaplet

ResourceHandler

Serves static content from a directory.

Usage

{
  "name": string,
  "type": "ResourceHandler",
  "config": {
    "directories": [ configuration expression<string>, ... ],
    "basePath": configuration expression<string>,
    "welcomePages": [ configuration expression<string>, ... ]
  }
}

Properties

"directories": array of configuration expressions<string>, required

A list of one or more directories in which to search for static content.

When multiple directories are specified in an array, the directories are searched in the listed order.

"basePath": _configuration expression<string>, required if the route is not /

The base path of the incoming request for static content.

To specify no base path, leave this property out of the configuration, or specify it as "basePath": "" or "basePath": "/".

Default: "".

"welcomePages": array of configuration expressions<string>, optional

A set of static content to serve from one of the specified directories when no specific resource is requested.

When multiple sets of static content are specified in an array, the sets are searched for in the listed order. The first set that is found is used.

Default: Empty list

Example

The following example serves requests to http://openig.example.com:8080 with the static file index.html from /path/to/static/pages/:

{
  "name": "StaticWebsite",
  "type": "ResourceHandler",
  "config": {
    "directories": ["/path/to/static/pages"],
    "welcomePages": ["index.html"]
  }
}

When the basePath is /website, the example serves requests to http://openig.example.com:8080/website:

{
  "name": "StaticWebsite",
  "type": "ResourceHandler",
  "config": {
    "directories": ["/path/to/static/pages"],
    "basePath": "/website",
    "welcomePages": ["index.html"]
  }
}

More Information

org.forgerock.openig.handler.resources.ResourceHandler

org.forgerock.http.protocol.Entity

Route

Routes are configuration files that you add to IG to manage requests. They are flat files in JSON format. You can add routes in the following ways:

Every route must call a handler to process requests and produce responses to requests.

When a route has a condition, it can handle only requests that meet the condition. When a route has no condition, it can handle any request.

Routes inherit settings from their parent configuration. This means that you can configure global objects in the config.json heap, for example, and then reference the objects by name in any other IG configuration.

For examples of route configurations see Configure Routers and Routes.

Usage

{
  "handler": Handler reference or inline Handler declaration,
  "heap": [ configuration object, ... ],
  "condition": runtime expression<boolean>,
  "name": string,
  "secrets": configuration object,
  "session": JwtSession object,
  "auditService": AuditService object,
  "globalDecorators": configuration object,
  "decorator name": decorator configuration object
}

Properties

"handler": Handler reference, required

For this route, dispatch the request to this handler.

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

See also Handlers.

"heap": array of configuration objects, optional

Heap object configuration for objects local to this route.

Objects referenced but not defined here are inherited from the parent.

You can omit an empty array. If you only have one object in the heap, you can inline it as the handler value.

See also Heap Objects.

"condition": runtime expression<boolean>, optional

An inline expression to define a condition based on the request, context, or IG runtime environment, such as system properties or environment variables.

Conditions are defined using IG expressions, as described in Expressions, and are evaluated as follows:

  • If the condition evaluates to true, the request is dispatched to the route.

  • If the condition evaluates to false, the condition for the next route in the configuration is evaluated.

  • If no condition is specified, the request is dispatched unconditionally to the route.

For debugging, log the routes for which IG evaluates a condition, and the route that matches a condition. Add the following line to a custom $HOME/.openig/config/logback.xml, and restart IG:

<logger name="org.forgerock.openig.handler.router.RouterHandler" level="trace" />

For information, see Managing Logs.

For example conditions and requests that match them, see Example Conditions and Requests.

An external request can never match a condition that uses the reserved administrative route. Therefore, routes that use these conditions are effectively ignored. For example, if /openig is the administrative route, a route with the following condition is ignored: ${matches(request.uri.path, '^/openig/my/path')}.

Default: No condition is specified.

"name": string, optional

Name for the route.

The Router uses the name property to order the routes in the configuration. If the route does not have a name property, the Router uses the route ID.

The route ID is managed as follows:

  • When you add a route manually to the routes folder, the route ID is the value of the _id field. If there is no _id field, the route ID is the filename of the added route.

  • When you add a route through the Common REST endpoint, the route ID is the value of the mandatory _id field.

  • When you add a route through Studio, you can edit the default route ID.

    CAUTION: The filename of a route cannot be default.json. The route name property or route ID cannot be default.

Default: route ID

"secrets": configuration object, optional

An object that configures an inline array of one or more secret stores, as defined in Default Secrets Object.

"session": JwtSession object, optional

Stateless session implementation for this route. Define a JwtSession object inline or in the heap.

When a request enters the route, IG builds a new session object for the route. The session content is available to the route’s downstream handlers and filters. Session content available in the ascending configuration (a parent route or config.json) is not available in the new session.

When the response exits the route, the session content is serialized as a secure JWT that is encrypted and signed, and the resulting JWT string is placed in a cookie. Session information set inside the route is no longer available. The session references the previous session object.

Default: Do not change the session storage implementation.

For more information, see JwtSession, and Sessions.

"auditService": AuditService object, optional

Provide an audit service for the route. Provide either the name of an AuditService object defined in the heap, or an inline AuditService configuration object.

Default: No auditing of a configuration. The NoOpAuditService provides an empty audit service to the top-level heap and its child routes.

"globalDecorators": one or more decorations, optional

Decorate all compatible objects in the route with one or more decorators referred to by the decorator name, and provide the configuration as described in Decorators:

"globalDecorators": {
  "decorator name": decoration configuration
  ...
}

The following object decorates all compatible objects in the route with a capture and timer decorator:

"globalDecorators": {
  "capture": "all",
  "timer": true
}

Default: No decoration.

"decorator name": decoration, optional

Decorate the main handler of this route with a decorator referred to by the decorator name, and provide the configuration as described in Decorators.

Default: No decoration.

Route Metrics at the Prometheus Scrape Endpoint

Route metrics at the Prometheus Scrape Endpoint have the following labels:

  • name: Route name, for example, My Route.

    If the router was declared with a default handler, then its metrics are published through the route named default.

  • route: Route identifier, for example, my-route.

  • router: Fully qualified name of the router, for example, gateway.main-router.

The following table summarizes the recorded metrics:

Name Monitoring Type Description

ig_route_request_active

Gauge

Number of requests being processed.

ig_route_request_total

Counter

Number of requests processed by the router or route since it was deployed.

ig_route_response_error_total

Counter

Number of responses that threw an exception.

ig_route_response_null_total

Counter

Number of responses that were not handled by IG.

ig_route_response_status_total

Counter

Number of responses by HTTP status code family. The family label depends on the HTTP status code:

  • Informational (1xx)

  • Successful (2xx)

  • Redirection (3xx)

  • Client_error (4xx)

  • Server_error (5xx)

  • Unknown (status code >= 600)

ig_route_response_time

Summary

A summary of response time observations.

For more information about the the Prometheus Scrape Endpoint, see Prometheus Scrape Endpoint.

Route Metrics at the Common REST Monitoring Endpoint

Route metrics at the Common REST Monitoring Endpoint are published with an _id in the following pattern:

  • heap.router-name.route.route-name.metric

The following table summarizes the recorded metrics:

Name Monitoring Type Description

request

Counter

Number of requests processed by the router or route since it was deployed.

request.active

Gauge

Number of requests being processed by the router or route at this moment.

response.error

Counter

Number of responses that threw an exception.

response.null

Counter

Number of responses that were not handled by IG.

response.status.client_error

Counter

Number of responses with an HTTP status code 400-499, indicating client error.

response.status.informational

Counter

Number of responses with an HTTP status code 100-199, indicating that they are provisional responses.

response.status.redirection

Counter

Number of responses with an HTTP status code 300-399, indicating a redirect.

response.status.server_error

Counter

Number of responses with an HTTP status code 500-599, indicating server error.

response.status.successful

Counter

Number of responses with an HTTP status code 200-299, indicating success.

response.status.unknown

Counter

Number of responses with an HTTP status code 600-699, indicating that a request failed and was not executed.

response.time

Timer

Time-series summary statistics.

For more information about the the Common REST Monitoring Endpoint, see Common REST Monitoring Endpoint.

Router

A handler that performs the following tasks:

  • Defines the routes directory and loads routes into the configuration.

  • Depending on the scanning interval, periodically scans the routes directory and updates the IG configuration when routes are added, removed, or changed. The router updates the IG configuration without needing to restart IG or access the route.

  • Manages an internal list of routes, where routes are ordered lexicographically by route name. If a route is not named, then the route ID is used instead. For more information, see Route.

  • Routes requests to the first route in the internal list of routes, whose condition is satisfied.

    Because the list of routes is ordered lexicographically by route name, name your routes with this in mind:

    • If a request satisfies the condition of more than one route, it is routed to the first route in the list whose condition is met.

    • Even if the request matches a later route in the list, it might never reach that route.

    If a request does not satisfy the condition of any route, it is routed to the default handler if one is configured.

The router does not have to know about specific routes in advance - you can configure the router first and then add routes while IG is running.

Studio deploys and undeploys routes through a main router named _router, which is the name of the main router in the default configuration. If you use a custom config.json, make sure that it contains a main router named _router.

Usage

{
    "name": string,
    "type": "Router",
    "config": {
        "defaultHandler": Handler reference,
        "directory": expression,
        "scanInterval": duration string or integer
    }
}

An alternative value for type is RouterHandler.

Properties

"defaultHandler": Handler reference, optional

Handler to use when a request does not satisfy the condition of any route.

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

Default: If no default route is set either here or in the route configurations, IG aborts the request with an internal error.

See also Handlers.

"directory": expression, optional

Directory from which to load route configuration files.

Default: The default directory for route configuration files, at $HOME/.openig(on Windows, appdata\OpenIG).

With the following example, route configuration files are loaded from /path/to/safe/routes instead of from the default directory:

{
  "type": "Router",
  "config": {
    "directory": "/path/to/safe/routes"
  }
}
If you define multiple routers, configure directory so that the routers load route configuration files from different directories.

An infinite route-loading sequence is triggered when a router starts a route that, directly or indirectly, starts another router, which then loads route configuration files from the same directory.

See also Expressions.

"scanInterval": duration string or integer, optional

Time interval at which IG scans the specified directory for changes to routes. When a route is added, removed, or changed, the router updates the IG configuration without needing to restart IG or access the route.

When an integer is used for the scanInterval, the time unit is seconds.

To load routes at startup only, and prevent changes to the configuration if the routes are changed, set the scan interval to disabled.

Default: 10 seconds

Router Metrics at the Prometheus Scrape Endpoint

Router metrics at the Prometheus Scrape Endpoint have the following labels:

  • fully_qualified_name: Fully qualified name of the router, for example, gateway.main-router.

  • heap: Name of the heap in which this router is declared, for example, gateway.

  • name: Simple name declared in router configuration, for example, main-router.

The following table summarizes the recorded metrics:

Name Monitoring Type Description

ig_router_deployed_routes

Gauge

Number of routes deployed in the configuration.

For more information about the the Prometheus Scrape Endpoint, see Prometheus Scrape Endpoint.

Router Metrics at the Common REST Monitoring Endpoint

Router metrics at the Common REST Monitoring Endpoint are JSON objects, with the following form:

  • [heap name].[router name].deployed-routes

The following table summarizes the recorded metrics:

Name Monitoring Type Description

deployed-routes

Gauge

Number of routes deployed in the configuration.

For more information about the the Common REST Monitoring Endpoint, see Common REST Monitoring Endpoint.

More Information

org.forgerock.openig.handler.router.RouterHandler

SamlFederationHandler

A handler to play the role of SAML 2.0 Service Provider (SP).

Consider the following requirements for this handler:

  • This handler does not support filtering; do not use it as the handler for a chain, which can include filters.

  • Do not use this handler when its use depends on something in the response. The response can be handled independently of IG, and can be null when control returns to IG. For example, do not use this handler in a SequenceHandler where the postcondition depends on the response.

  • Requests to the SamlFederationHandler must not be rebased, because the request URI must match the endpoint in the SAML metadata.

Usage

{
    "name": string,
    "type": "SamlFederationHandler",
    "config": {
        "assertionMapping": object,
        "redirectURI": runtime expression<uri string>,
        "secretsProvider": SecretsProvider reference,
        "assertionConsumerEndpoint": runtime expression<uri string>,
        "authnContext": runtime expression<string>,
        "authnContextDelimiter": runtime expression<string>,
        "logoutURI": runtime expression<uri string>,
        "sessionIndexMapping": runtime expression<string>,
        "singleLogoutEndpoint": runtime expression<uri string>,
        "singleLogoutEndpointSoap": runtime expression<uri string>,
        "SPinitiatedSLOEndpoint": runtime expression<uri string>,
        "SPinitiatedSSOEndpoint": runtime expression<uri string>,
        "useOriginalUri": runtime expression<boolean>,
        "subjectMapping": runtime expression<string>
    }
}

Properties

"assertionMapping": object, required

The transformation of attributes from the incoming assertion to attribute value pairs in IG.

Each entry in this object has the form localName:incomingName, where:

  • localName is the attribute name set in the session

  • incomingName is the attribute name set in the incoming assertion

    The following example is an assertionMapping object:

    {
    "username": "mail",
    "password": "mailPassword"
}

    If the incoming assertion contains the statement:

    mail = demo@example.com
mailPassword = demopassword

    Then the following values are set in the session:

    username = demo@example.com
password = demopassword

    For this to work, edit the <Attribute name="attributeMap"> element in the SP extended metadata file, $HOME/.openig/SAML/sp-extended.xml, so that it matches the assertion mapping configured in the SAML 2.0 Identity Provider (IDP) metadata.

    Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the localName.

    To prevent different handlers from overwriting each others' data, use unique localName settings when protecting multiple service providers.

"redirectURI": runtime expression<uri string>, required

Set this to the page that the filter used to HTTP POST a login form recognizes as the login page for the protected application.

This is how IG and the Federation component work together to provide SSO. When IG detects the login page of the protected application, it redirects to the Federation component. Once the Federation handler validates the SAML exchanges with the IDP, and sets the required session attributes, it redirects back to the login page of the protected application. This allows the filter used to HTTP POST a login form to finish the job by creating a login form to post to the application based on the credentials retrieved from the session attributes.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for keys when AM provides signed or encrypted SAML assertions.

When this property is not set, the keys are provided by direct keystore look-ups based on entries in the SP extended metadata file, sp-extended.xml.

For more information, see SecretsProvider.

Default: Empty.

"assertionConsumerEndpoint": runtime expression<string>, optional

Default: fedletapplication (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"authnContext": runtime expression<string>, optional

Name of the session field to hold the value of the authentication context. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "authnContext": "myAuthnContext", then IG sets session.myAuthnContext to the authentication context specified in the assertion. When the authentication context is password over protected transport, then this results in the session containing "myAuthnContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport".

Default: map to session.authnContext

"authnContextDelimiter": runtime expression<string>, optional

The authentication context delimiter used when there are multiple authentication contexts in the assertion.

Default: |

"logoutURI": runtime expression<string>, optional

Set this to the URI to visit after the user is logged out of the protected application.

You only need to set this if the application uses the single logout feature of the Identity Provider.

"sessionIndexMapping": runtime expression<string>, optional

Name of the session field to hold the value of the session index. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "sessionIndexMapping": "mySessionIndex", then IG sets session.mySessionIndex to the session index specified in the assertion. This results in the session containing something like "mySessionIndex": "s24ccbbffe2bfd761c32d42e1b7a9f60ea618f9801".

Default: map to session.sessionIndex

"singleLogoutEndpoint": runtime expression<string>, optional

Default: fedletSLORedirect (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"singleLogoutEndpointSoap": runtime expression<string>, optional

Default: fedletSloSoap (same as the Fedlet)

If you modify this attribute, change the metadata to match.

"SPinitiatedSLOEndpoint": runtime expression<string>, optional

Default: SPInitiatedSLO

If you modify this attribute, change the metadata to match.

"SPinitiatedSSOEndpoint": runtime expression<string>, optional

Default: SPInitiatedSSO

If you modify this attribute, change the metadata to match.

"useOriginalUri": runtime expression<boolean>, optional

When true, use the original URI instead of a rebased URI when validating RelayState and Assertion Consumer Location URLs. Use this property if a baseUri decorator is used in the route or in config.json.

Default: false

"subjectMapping": runtime expression<string>, optional

Name of the session field to hold the value of the subject name. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "subjectMapping": "mySubjectName", then IG sets session.mySubjectName to the subject name specified in the assertion. If the subject name is an opaque identifier, then this results in the session containing something like "mySubjectName": "vtOk+APj1s9Rr4yCka6V9pGUuzuL".

Default: map to session.subjectName

Example

For an example of how to set up IG as a SAML service provider, see Act As a SAML 2.0 Service Provider.

In the following example, IG receives a SAML 2.0 assertion from the IDP, and then logs the user in to the protected application using the username and password from the assertion:

{
    "name": "SamlFederationHandler",
    "type": "SamlFederationHandler",
    "config": {
        "assertionMapping": {
            "username": "mail",
            "password": "mailPassword"
        },
        "redirectURI": "/login",
        "logoutURI": "/logout"
    }
}

More Information

org.forgerock.openig.handler.saml.SamlFederationHandler

ScriptableHandler

Creates a response to a request by executing a script.

Scripts must return either a Promise<Response, NeverThrowsException> or a Response.

This section describes the usage of ScriptableHandler. For information about script properties, available global objects, and automatically imported classes, see Scripts.

Usage

{
    "name": string,
    "type": "ScriptableHandler",
    "config": {
        "type": string,
        "file": expression,                    // Use either "file"
        "source": string or array of strings   // or "source", but not both
        "args": object,
        "clientHandler": Handler reference
    }
}

Properties

For information about properties for ScriptableHandler, see Scripts.

More Information

org.forgerock.openig.handler.ScriptableHandler

SequenceHandler

Processes a request through a sequence of handlers. This allows multi-request processing such as retrieving a form, extracting form content (for example, nonce) and submitting in a subsequent request. Each handler in the bindings is dispatched to in order; the binding postcondition determines if the sequence should continue.

Usage

{
    "name": string,
    "type": "SequenceHandler",
    "config": {
        "bindings": [
            {
                "handler": Handler reference,
                "postcondition": runtime expression<boolean>
            }
        ]
    }
}

Properties

"bindings": array of objects, required

A list of bindings of handler and postcondition to determine that sequence continues.

"handler": Handler reference, required

Dispatch to this handler.

Either the name of the handler heap object to dispatch to, or an inline Handler configuration object.

See also Handlers.

"postcondition": runtime expression<boolean>, optional

If the expression evaluates to true, the sequence continues. If a condition is not specified, the sequence continues unconditionally.

Default: No condition is specified.

See also Expressions.

More Information

org.forgerock.openig.handler.SequenceHandler

StaticResponseHandler

Creates a response to a request statically or based on something in the context.

Usage

{
     "name": string,
     "type": "StaticResponseHandler",
     "config": {
         "status": configuration expression<number>,
         "reason": configuration expression<string>,
         "version": configuration expression<string>,
         "headers": object,
         "entity": runtime expression<string>
     }
}

Properties

"status": configuration expression<number>, required

The response status code (for example, 200).

"reason": configuration expression<string>, optional

The response status reason (for example, "OK").

"version": configuration expression<string>, optional

Protocol version. Default: "HTTP/1.1".

"headers": object, optional

Header fields to set in the response, with the format name: value, …​ ], where:

  • name is a configuration expression that resolves to a string for a header name. If multiple expressions resolve to the same final string, name has multiple values.

  • value is a runtime expression that resolves to one or more header values.

    When the property entity is used, you are recommended to set a Content-Type header with the correct content type value. The following example sets the content type of a message entity in the response:

    "headers": {
  "Content-Type": [ "text/html" ]
}

    The following example is used in 05-federate.json to redirect the original URI from the request:

"headers": {
  "Location": [
     "http://sp.example.com:8080/saml/SPInitiatedSSO"
  ]
}
"entity": runtime expression<string>, optional

The message entity to include in the response. If present, it must conform to the Content-Type header and set the content length header automatically.

Attackers during reconnaissance can use response messages to identify information about a deployment. For security, limit the amount of information in messages, and avoid using words that help identify IG.

Default: No message entity

Example

{
  "name": "ErrorHandler",
  "type":"StaticResponseHandler",
  "config": {
    "status": 500,
    "reason": "Error",
    "headers": {
      "Content-Type": [ "text/html" ]
    },
    "entity": "<html><h2>Epic #FAIL</h2></html>"
  }
}

More Information

org.forgerock.openig.handler.StaticResponseHandler

Copyright © 2010-2023 ForgeRock, all rights reserved.