PingAuthorize

Configuring the JWKS endpoint cache

Configure the JSON Web Key Set (JWKS) endpoint cache to manage the key set caching behavior for the Policy Editor in OIDC mode.

About this task

To improve performance, the Policy Editor is configured to cache the JWKS endpoint response indefinitely (when key set caching is enabled). Whenever the Policy Editor encounters a key ID not present in the cache, it makes a request to the JWKS endpoint, regardless of the caching configuration.

You can choose from the following configuration values. This configuration option only affects server-side behavior:

Value Behavior

Any negative integer

Caches the key set indefinitely (default configuration)

0

Disables key set caching

Positive integer

Sets the key set cache expiry time in seconds

In general, using the options.yml file to modify the behavior and output of setup requires restarting the Policy Editor. If you have already run setup once, provide the --ignoreWarnings option to overwrite any existing configuration files.

Doing so, however, overwrites the admin keystore and decision point shared secrets. Additionally, providing --generateSelfSignedCertificate overwrites the server keystore. Be sure to back up the admin and server keystores and your original configuration.yml file if you intend to reuse them.

Steps

  1. Make a copy of the default options file:

    $ cp config/options.yml my-options.yml
  2. In the core section of the new options file, uncomment the Authentication.oidcJwksCacheExpirySeconds field.

    1. Optional: Change the default value to set a cache expiry limit or disable key set caching:

      # This option only affects server-side behavior.
      #
      Authentication.oidcJwksCacheExpirySeconds: 3600
  3. If necessary, stop the Policy Editor:

    $ bin/stop-server
  4. Run setup using the --optionsFile argument and customize all other options as appropriate for your needs:

    $ bin/setup demo \
      --adminUsername admin \
      --generateSelfSignedCertificate \
      --decisionPointSharedSecret pingauthorize \
      --hostname  <pap-hostname>  \
      --port  <pap-port>  \
      --adminPort  <admin-port>  \
      --licenseKeyFile  <path-to-license>  \
      --optionsFile my-options.yml
  5. Start the Policy Editor and provide the OIDC well known configuration URL to the PING_OIDC_CONFIGURATION_ENDPOINT environment variable at startup.

    $ env PING_OIDC_CONFIGURATION_ENDPOINT=<well-known-url>  \
      bin/start-server

    Instead of using the OIDC well known configuration URL to provide the value for the JWKS endpoint, you can specify different values in the ui section of the new options file. Uncomment the fields as specified in the following example and set the URL values for authorizationEndpoint and jwksUri:

    ui:
      authClientConfig:
        authWellKnownEndpoints:
          authorizationEndpoint: https://<oidc-host>:<oidc-port>/as/authorize
          jwksUri: https://<oidc-host>:<oidc-port>/JWKS

    If you provide a custom value for jwksUri in options.yml, omit the PING_OIDC_CONFIGURATION_ENDPOINT environment variable in this step.