/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 are not planning to use so that they are not 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.
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 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 |
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. |
|
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. |
|
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. |
|
Customize the key ID ( By default, AM generates a You need to customize AM if any exposed keys in your environment need a specific |
|
Decide if the JWK URI endpoint should display duplicated key IDs By default, each If you have several algorithms and key types associated with one |
Access the keys exposed by the JWK URI endpoint
Perform the following steps to access the public keys:
-
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.
-
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:
-
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider.
-
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
RS512am.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.
-
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. -
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.
-
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:
-
Remove the old algorithm from the OAuth 2.0 provider supported algorithm list.
This stops new clients from registering with that algorithm.
-
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, see Map and rotate secrets instead.
-
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.
-
-
Configure secret ID mappings for the keys using the new algorithm, if required.
For more information, see Secret stores.
-
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.
-
-
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.
-
After the grace period, remove the secret ID mappings relevant to the deprecated algorithm.
For more information about secret mappings, see 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:
-
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. -
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.
-
Go to Configure > Server Defaults > Advanced.
-
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
-
Restart the AM instance or the container in which it runs.
-
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.
-
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect.
-
Enable Include all kty and alg combinations in jwk_uri.
-
Save your changes.
-
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.