/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-based access tokens and OpenID Connect ID tokens.

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

Note that HMAC-based algorithms, direct encryption, and AES key wrapping encryption algorithms use the client secret instead of a public key. Therefore, clients do not need to check the JWK URI endpoint for those algorithms.

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.

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.

To 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://tenant-name.forgeblocks.com/am/oauth2/realms/root/realms/alpha/.well-known/openid-configuration
    {
      "request_parameter_supported": true,
      "claims_parameter_supported": false,
      "introspection_endpoint": "https://tenant-name.forgeblocks.com/am/oauth2/realms/root/realms/alpha/introspect",
      "check_session_iframe": "https://tenant-name.forgeblocks.com/am/oauth2/realms/root/realms/alpha/connect/checkSession",
      "scopes_supported": [],
      "issuer": "https://tenant-name.forgeblocks.com/am/oauth2/realms/root/realms/alpha",
      "id_token_encryption_enc_values_supported": [
        "A256GCM",
        "A192GCM",
        "A128GCM",
        "A128CBC-HS256",
        "A192CBC-HS384",
        "A256CBC-HS512"
      ],
    …​
      "jwks_uri": "https://tenant-name.forgeblocks.com/am/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://tenant-name.forgeblocks.com/am/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://tenant-name.forgeblocks.com/am/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"
          },
          …​
       ]
    }

Displaying Every Algorithm and Key Type Associated to 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.