Validating JWT based on JWKS

This section describes how a JWT can be validated based on JWKS.

Introduction

Currently, when configuring external identity providers in WSO2 Identity Server, relevant X.509 public certificate of the Identity provider needs to be uploaded for signature verification purposes. However, you can also provide the keys of the identity provider in jwks_uri format. The JWKS uri represents the cryptographic keys used by the identity provider for signing RS256 tokens. We need to have a way to support JWKS based validation for signatures.

The main benefit of allowing JWKS endpoint configuration is its ability to handle key rotation by external identity providers. Configuring this endpoint would enable you to programmatically discover JSON web keys and allow the third party identity providers to publish new keys without having the overhead of notifying each and every client application. This allows smooth key rollover and integration.

Following sequence diagram illustrates the scenario where a JWT obtained from a third party IDP is validated using the JWKS Based JWT Validator.

The steps of the above diagram are explained below:

Step 1: 

• User requests a JWT assertion from the Identity Provider.

• A valid JWT is returned with the response

Step 2:

• The user initiates a token request to WSO2 Server’s token endpoint using JWT grant type with the obtained JWT assertion.

• Access Token Issuer handles all the requests sent to the token endpoint.

Step 3:

• Access token issuer invokes the JWT Grant Handler to validate the provided JWT assertion.

  Deploys and configures the JWT client-handler artifacts

Step 4:

• JWT Grant Handler invokes the JWKS Based JWT validator to validate the JWT signature using IDP’s jwks endpoint.

Step 5:

• JWKS Based JWT validator validates the JWT using IDP’s JWKS

Step 6:

• Upon JWT Grant Validation, Access Token issuer issues a new access token to the user.

Here, the retrieved JWKS is cached against the jwks_uri. When validating a JWT, we use the 'kid' header parameter which is an indicator for the key used to sign the JWT at the IDP, and compare it against the JWKS 'kid' properties. If a matched 'kid' is found among the key set, the JWT will be validated using the corresponding key. In case of key roll-over at the IDP, the JWT is signed using the new keys and hence the matching key is not found in the cached JWKS. When a matching key is not found, the validator retrieves the latest JWKS from the IDP JWKS endpoint and obtain the matching key for signature validation. 

Configuring JWKS based JWT Validator

Follow the below steps to configure JWKS based JWT Validator.

Configuring identity.xml

1. Make sure you have the following configurations to <SERVER_HOME>/repository/conf/identity/identity.xml. You can find this somewhere under <Server> tag.

   <JWTValidatorConfigs>
      <Enable>true</Enable>
      <JWKSEndpoint>
     	<HTTPConnectionTimeout>1000</HTTPConnectionTimeout>
     	<HTTPReadTimeout>1000</HTTPReadTimeout>
     	<HTTPSizeLimit>51200</HTTPSizeLimit>
      </JWKSEndpoint>
   </JWTValidatorConfigs>

   You can use customized values for the above HTTP connection configurations. If not customized, the default values will be used for establishing HTTP connections on IDP's jwks_uri. Also make sure that the <Enable> property is set to true.

2. Restart the server.
   
   

Configuring the Identity Provider

Now we need to configure JWKS IdP with as an Identity Provider in IS. 

1. Log in to the management console and select Add under Identity Providers menu in the Main menu.  

2. Provide the following values to configure the IDP:

   Under basic information:

   • • Identity Provider Name: Enter an issuer name (iss value in the JWT) as the identity provider name.

     • Alias: Give the Recipient URL configured in the external IDP as the alias E.g: https://localhost:9443/oauth2/token

     • Configure jwks_uri for IS

       • Under Identity Provider configuration UI select "Use IDP JWKS endpoint" option in 'Choose IDP certificate type' field.

       • In the 'Identity Provider's JWKS Endpoint' field, enter the jwks_uri of the Identity Provider. e.g., https://exampleidp.com/oauth2/default/v1/keys

   

3. Click Register to save the details.