PKCE Support for WSO2 Identity Server 5.2.0

In this post, we will look at a new feature introduced in WSO2 Identity Server (IS) 5.2.0 which is Proof Key for Code Exchange (PKCE). WSO2 implements the PKCE specification described here. It is recommended to use as OAuth 2.0 public clients utilizing the Authorization Code Grant are susceptible to the authorization code interception attack and this spec introduces a technique to mitigate against the treat through the use of PKCE.

Implementation of PKCE in WSO2 IS

A. With PKCE, the client sends two additional parameters when requesting an authorization code. It creates a "code verifier" and derives a transformed version of the code verifier named "code challenge" through a transformation method and pass the code challenge and the transformation method along with the authorization request.

Here, there are two types of transformation methods.

     i. Plain 

     If the plain transformation method is used -> code_challenge = code_verifier

     ii. S256

     If the S256 transformation method is used -> code_challenge = BASE64URL- ENCODE(SHA256(ASCII(code_verifier)))

B. IS records the code challenge and transformation method associated with the authorization request and responds to the request with the Authorization code.

C. To retrieve the Access Token, now the client sends a request with Authorization Code and Code Verifier generated at step A.

D. IS transforms the code verifier using the transformation method recorded in step B and compares the result with the code challenge saved at step B. If both are equal, the Access Token is sent to client. Otherwise access will be denied for the user.

Any attacker who intercepts the authorization code at step B is unable to retrieve the Access Token as they are not aware of the Code Verifier. 

How to use PKCE in WSO2 IS

Registering a Service Provider 

Install WSO2 IS 5.2.0 from here and register a Service Provider.

1. Log in to the Management Console. 

2. Navigate to the Main menu to access the Identity menu. Click Add under Service Providers.

3. Fill in the Service Provider Name (eg. Playground) and click on Register.

4. Under Inbound Authentication Configuration, configure the playground application as an OAuth 2.0 application with following configurations. 

• Callback URL - http://localhost:8080/playground2/oauth2client
• Allowed Grant Types - All grant types
• PKCE Mandatory - Keep as default (unselected)
• Support PKCE 'Plain' Transform Algorithm - Keep as default (selected)

After successful registration the application is given a Client Id and a Client Secret.

Retrieving the User Info using Playground Application 

1. Deploy the Playground sample app which is used as the client to demonstrate this feature. You can set up the sample app by following this guide.

2. Access the playground application

http://localhost:8080/playground2/

3. Enter the details as follows and Authorize. (Reflects Step A above)

• Client ID and Callback URL should be the same as in the registered service provider
• Once you select "Use PKCE", the code challenge and the code verifier will be generated according to the selected transformation method

4. Login to the Authorization Server (IS).

5. Select a user consent - Approve or Approve Always

6.  The Authorization Code is sent to the client. (Reflects Step B above)

Enter the details as follows and Get Access Token. (Reflects Step C above)

• Client Secret and Callback URL should be the same as in the registered service provider
• The PKCE Verifier is the same code verifier generated at step 3.

7. Since the correct PKCE Code verifier is passed, IS should successfully do the transformation, match the code challenges and send the Access Token to the client as below. (Reflects Step D above)

Enter the user info endpoint as below and get user info.

8. User information should be successfully retrieved as below.

As mentioned earlier, PKCE will come in handy to mitigate interception attacks and secure your application which uses Authorization Code grant type. With WSO2 IS implementing it, allows users to register their apps with IS and secure it more from these vulnerabilities. 

Hope this post shed some light on this new feature. Do let us know if you have any queries.