Access Management 7.3.2

/oauth2/connect/jwk_uri

Each realm configured for OAuth 2.0 exposes a JSON web key (JWK) URI endpoint that contains public keys that clients can use to:

  • Verify the signature of client-side access tokens and OpenID Connect ID tokens.

  • Encrypt OpenID Connect ID requests to AM sent as a JWT.

Where do the keys come from?

By default, the endpoint exposes an internal URI relative to the AM deployment. For example, openam/oauth2/realms/root/connect/jwk_uri.

The keys appearing in that URI are those configured in the AM secret stores, regardless of the algorithms configured in the OAuth 2.0 provider. This is to support the process of deprecating keys/algorithms.

Secrets are configured by default; delete the ones you aren’t planning to use so that they aren’t exposed on the endpoint.

In environments where secrets are centralized, you may want AM to share the URI of your secrets API instead of the local AM endpoint. To configure it, go to Realms > Realm Name > Services > OAuth2 Provider, and add the new URI to the Remote JSON Web Key URL field.

Public keys are for asymmetric encryption. Symmetric key algorithms, such as direct encryption and AES key wrapping encryption use the client secret, and HMAC-based algorithms use the secret mapped to the am.services.oauth2.stateless.signing.HMAC label. Clients don’t need to check the JWK URI endpoint for these algorithms.

The endpoint is exposed, but I haven’t configured an OAuth 2.0 provider yet

Web and Java agents use an internal OAuth 2.0 provider to connect to AM. This provider exposes the endpoint so that agents can access the key configured for the am.global.services.oauth2.oidc.agent.idtoken.signing secret ID.

Configure the base URL source service to change the URL used in the .well-known endpoints used in OpenID Connect 1.0 and UMA.

The following table summarizes the high-level tasks you need to complete to manage the JWK URI endpoint in your environment:

Task Resources

Learn where to find and how to query the JWK URI endpoint.

Clients need to find the endpoint to, for example, validate tokens signed by AM.

Access the keys exposed by the JWK URI endpoint

Control which keys are displayed.

The JWK URI endpoint returns keys based on the secret mappings configured for the relevant OAuth 2.0/OpenID connect functionality. Therefore, to control which keys are displayed, ensure that you only map the secrets required in your environment.

Configure ID token signatures

Learn how to deprecate algorithms and how to rotate public keys.

You may need to perform these tasks to replace algorithms with more secure ones.

Deprecate algorithms and rotate public keys

Customize the key ID (kid) of the exposed keys.

By default, AM generates a kid for each public key exposed in the jwk_uri endpoint when AM is configured as an OAuth 2.0 authorization server.

You need to customize AM if any exposed keys in your environment need a specific kid.

Customize public key IDs

Decide if the JWK URI endpoint should display duplicated key IDs

By default, each kid exposed by the jwk_uri endpoint matches a unique secret, as required by the RFC7517 specification.

If you have several algorithms and key types associated with one kid, configure AM to display them individually.

Display every algorithm and key type associated with a key ID

Access the keys exposed by the JWK URI endpoint

Perform the following steps to access the public keys:

  1. To find the JWK URI that AM exposes, perform an HTTP GET at /oauth2/realms/root/.well-known/openid-configuration.

    For example:

    $ curl https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/.well-known/openid-configuration
{
  "request_parameter_supported": true,
  "claims_parameter_supported": false,
  "introspection_endpoint": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/introspect",
  "check_session_iframe": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/checkSession",
  "scopes_supported": [],
  "issuer": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha",
  "id_token_encryption_enc_values_supported": [
    "A256GCM",
    "A192GCM",
    "A128GCM",
    "A128CBC-HS256",
    "A192CBC-HS384",
    "A256CBC-HS512"
  ],
…​
  "jwks_uri": "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/jwk_uri",
  "subject_types_supported": [
    "public"
  ],
…​
}

    By default, AM exposes the JWK URI as an endpoint relative to the deployment URI. For example, https://openam.example.com:8443/openam/oauth2/realms/root/connect/jwk_uri.

    In environments where secrets are centralized, you may want AM to share the URI of your secrets API instead of the local AM endpoint.

    To configure it, go to Realms > Realm Name > Services > OAuth2 Provider, and add the new URI to the Remote JSON Web Key URL field.

  2. Perform an HTTP GET at the JWK URI to get the relevant public keys.

    For example:

    $ curl https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/jwk_uri
{
"keys":[
      {
         "kty":"EC",
         "kid":"I4x/IijvdDsUZMghwNq2gC/7pYQ=",
         "use":"sig",
         "x5t":"GxQ9K-sxpsH487eSkJ7lE_SQodk",
         "x5c":[
            "MIIB/zCCAYYCCQDS7UWmBdQtETAJ0mN0TZL7/MaY…​"
               ],
         "x":"k5wSvW_6JhOuCj-9PdDWdEA4oH90RSmC2GTliiUHAhXj6rmTdE2S-_zGmMFxufuV",
         "y":"XfbR-tRoVcZMCoUrkKtuZUIyfCgAy8b0FWnPZqevwpdoTzGQBOXSNi6uItN_o4tH",
         "crv":"P-384"
      },
      …​
   ]
}

Configure ID token signatures

ID tokens are signed by default with a test key configured during installation. Change this key on production-like and production environments.

Perform the steps in this procedure to configure the signing algorithm AM should use to sign OpenID Connect tokens:

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.

  2. In the OpenID Connect tab, ensure that the ID Token Signing Algorithms supported list has the signing algorithms your environment requires.

    AM supports the signing algorithms listed in JSON Web Algorithms (JWA): "alg" (Algorithm) Header Parameter Values for JWS.

    Note that the alias mapped to the algorithms are defined in the secret stores, as shown in the table below:

    Secret ID mappings for signing OpenID Connect tokens

    The following table shows the secret ID mapping used to sign OpenID Connect ID tokens and backchannel logout tokens:

    Secret ID Default alias Algorithms(1)

    am.services.oauth2.oidc.signing.ES256

    es256test

    ES256

    am.services.oauth2.oidc.signing.ES384

    es384test

    ES384

    am.services.oauth2.oidc.signing.ES512

    es512test

    ES512

    am.services.oauth2.oidc.signing.RSA

    rsajwtsigningkey

    PS256
    PS384
    PS512
    RS256
    RS384
    RS512

    am.services.oauth2.oidc.signing.EDDSA

    EdDSA with SHA-512

    (1) The following applies to confidential clients only:

    If you select an HMAC algorithm for signing ID tokens (HS256, HS384, or HS512), the Client Secret property value in the OAuth 2.0 Client is used as the HMAC secret instead of an entry from the secret stores.

    Since the HMAC secret is shared between AM and the client, a malicious user compromising the client could potentially create tokens that AM would trust. Therefore, to protect against misuse, AM also signs the token using a non-shared signing key configured in the am.services.oauth2.jwt.authenticity.signing secret ID.

    By default, secret IDs are mapped to demo keys contained in the default keystore provided with AM and mapped to the default-keystore keystore secret store. Use these keys for demo and test purposes only. For production environments, replace the secrets as required and create mappings for them in a secret store configured in AM.

    For more information about managing secret stores and mapping secret IDs to aliases, see Secrets, certificates, and keys.

  3. If the client is configured in AM, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client ID.

    Clients registering dynamically can see the algorithms that the provider supports by making a call to the /oauth2/.well-known/openid-configuration endpoint.

  4. In the ID Token Signing Algorithm field, enter the signing algorithm that AM will use to sign the ID token for this client.

    Note that the OAuth 2.0 provider must support signing with the chosen algorithm.

  5. Save your changes.

    AM is ready to sign ID tokens with the algorithm you configured.

    If you chose a non-HMAC-based algorithm, the client will need to make a request to AM’s JWK URI endpoint for the realm to recover the signing public key they can use to validate the ID tokens.

Deprecate algorithms and rotate public keys

With signing and encryption methods changing so rapidly, during the lifecycle of your OAuth 2.0 environment you will need to deprecate older, less secure signing and/or encrypting algorithms in favor of new ones.

In the same way, you will rotate the keys AM uses for signing and encryption if you suspect they may have been leaked or just due to security policies, such as deprecating algorithms or because they have reached the end of their lifetime.

The keys you expose in the JWK URI endpoint should reflect the algorithms currently supported by AM as well as the deprecated ones. Otherwise, clients still using tokens signed with deprecated keys would not be able to validate them.

This is why deprecating supported algorithms in the OAuth 2.0/OpenID Connect provider is a two-step process:

  1. Remove the old algorithm from the OAuth 2.0 provider supported algorithm list.

    This stops new clients from registering with that algorithm.

  2. After a grace period, remove the secret mapping associated to that algorithm.

    This removes the associated public keys from the JWK URI endpoint.

Deprecate supported algorithms and their keys

Perform the steps in this procedure to deprecate an algorithm and its related keys. If you only want to deprecate keys or rotate them as part of your environment’s security policies, refer to Map and rotate secrets instead.

  1. Configure the new algorithm, if required.

    • Go to Realms > Realm Name > Services > OAuth2 Provider > OpenID Connect.

    • In the ID Token Signing Algorithm supported field, add the new signing algorithm, if not already present.

    • In the ID Token Encryption Algorithms supported field, add the new encryption algorithm, if not already present.

    • Save your changes.

  2. Configure secret ID mappings for the keys using the new algorithm, if required.

    Learn more in Secret stores.

  3. Remove the algorithm to be deprecated from the relevant OAuth 2.0 provider algorithm list:

    • Go to Realms > Realm Name > Services > OAuth2 Provider > OpenID Connect.

    • In the ID Token Signing Algorithm supported field, remove the deprecated signing algorithm.

    • In the ID Token Encryption Algorithms supported field, remove the deprecated encryption algorithm.

    • Save your changes.

  4. Decide on a grace period.

    For example, a month. During this period both the deprecated and the new algorithms/keys are supported.

    New clients cannot register with the deprecated algorithms and are forced to use a supported algorithm. However, since the deprecated keys are still mapped to secret IDs, existing clients still can use them to validate active tokens and encrypt requests.

    Existing clients must change their configuration during the grace period to use one of the supported algorithms.

  5. After the grace period, remove the secret ID mappings relevant to the deprecated algorithm.

    Learn more about secret mappings in Map and rotate secrets.

Customize public key IDs

By default, AM generates a key ID (kid) for each public key exposed in the jwk_uri URI when AM is configured as an OAuth 2.0 authorization server.

For keys stored in a keystore or HSM secret store, you can customize how key ID values are determined by writing an implementation of the KeyStoreKeyIdProvider interface and configuring it in AM:

  1. Write your own implementation of the KeyStoreKeyIdProvider interface that provides a specific key ID for a provided public key. For more information, see the KeyStoreKeyIdProvider interface in the Access Management Java API Specification.

  2. In the AM admin UI, configure the OAuth 2.0/OpenID Connect Provider service, if you haven’t already done so.

    For more information, see Authorization server configuration.

  3. Go to Configure > Server Defaults > Advanced.

  4. Add an advanced server property called org.forgerock.openam.secrets.keystore.keyid.provider, whose value is the fully qualified name of the class you wrote in previous steps.

    For example:

    org.forgerock.openam.secrets.keystore.keyid.provider = com.mycompany.am.secrets.CustomKeyStoreKeyIdProvider

  5. Restart the AM instance or the container in which it runs.

  6. Verify that the customized key IDs are displayed by navigating to the OAuth 2.0 authorization server’s jwk_uri URI.

    For example, https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/connect/jwk_uri.

Display every algorithm and key type associated with a key ID

By default, each key ID (kid) exposed by the jwk_uri endpoint matches a unique secret, as recommended by the RFC7517 specification. This means that each kid is of a particular key type, and uses a particular algorithm.

If you have several algorithms and key types associated with one kid, configure the JWK URI endpoint to display them as different keys in the JWK. Note that when including all combinations associated with a kid, that kid does not uniquely identify a particular secret.

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.

  2. Enable Include all kty and alg combinations in jwk_uri.

  3. Save your changes.

  4. Verify that you can now see duplicate kid entries for different combinations of algorithms and key types.

    For more information, see Access the keys exposed by the JWK URI endpoint.