PKCE in WSO2 IS server

If you are using WSO2 IS server for authorization purposes (via OAuth2.0 protocol), you must know about PKCE. PKCE stands for Proof Key for Code Exchange and used in authorization code grant type.Basically, it is a protection mechanism for exchanging authorization code between auth server and client application.Through this article, I’ll explain

1. Why we need PKCE
2. what is PKCE
3. How PKCE works
4. How to use PKCE in wso2 ISserver

Why we need PKCE?

In the normal authorization code grant type, public clients are susceptible to the authorization code interception attack especially if the communication path is not protected by TLS connection, an attacker can easily get the authorization code(auth code) and used to gain access token from auth server.

In native apps case, it is very easy for a malicious app to get the auth code if it registers itself as a handler for the custom scheme in addition to the legitimate OAuth 2.0 app.In this case, even in TLS connection, the malicious app can get the auth code easily.

Authorization Grant type flow

So if the channel is not protected/TLS (even if it is TLS there are ways to intercept it) in 4 or 5 step it is possible for an attacker to get the auth code and use it to get an access token ie proceed with 6 for in his self.

What is PKCE?

PKCE is method client can use to protect his auth code from these kinds of attacks.In PKCE while sending an authorization code request, client will add a code challenge along with it and auth server will map that code challenge to the generated auth code.

When the client tries to request for an access token to the token endpoint it should send another parameter called “code verifier” along with the request.If the code verifier matches the code challenge then auth server will provide the access token.I’ll explain more about this matching process and how this will secure auth code in below sections.

Now all you need to understand is while sending your authorization code request, you sent an additional parameter — “code challenge” and auth code will bind to this code challenge.When you request for an access token, you provide “code verifier” to proof that auth code is generated for yourself.

How PKCE works

Now comes the best part in understanding PKCE, the way PKCE works is very simple and elegant but hard to attack.This flow will be done in below steps.

PKCE steps

1. The client will generate a “code verifier”.eg say a value x.
2. Then client has to decide a code challenge method.This can be plain or a hash method.If the client didn’t select any method default method will be plain. eg Now take code challenge as f().
3. Now client will apply that code challenge to code verifier and create the code challenge. Here it will be f(x).
4. When sending the authorization request to auth server client will include code challenge(required) and code challenge method(optional) in the request.
5. When auth server receives the request it will map the code challenge to it.may be it can save the value in database mapping the auth code or put the code challenge value inside auth code. Then auth server will provide the auth code to the client.
6. While sending the access token request, the client will send the code verifier along with the auth code.
7. When receiving this request auth server will apply the code challenge method to the code verifier and see whether it is equal to code challenge.

simple equation we can say

code_challenge = code_challenge_method(code_verifier)

In our example:

code_challenge is f(x);

code_verifier is x;

code_challenge_method is f();

The new flow in the authorization grant type will be like this:

The new authorization flow with PKCE

If you see the flow the in step 2, I have mentioned code_challenge as mandatory and code_challenge_method as optional.Let talk about them in brief

Basically, code_challenge_method is the function you apply on code_verifier to create code_challenge.Code_challenge_method can be either

1.Plain:

If a code_challenge method is mention as plain or not mention at all it will take this plain value. Then code_challenge will like:

code_challenge = code_verifier

2. SHA256:

To have the code_challenge as SHA256, we should mention this in request otherwise plain value will be assumed.For SHA256 code challenge will be like

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Here base64url is same as base64encoding(used so that all machine can identify as same value) but trailing “=” will be removed and “+” & “/” are placed by “-” & “_” to avoid unnecessary length in URL.(otherwise ‘+’ becomes ‘%2B’, ‘/’ becomes ‘%2F’ and ‘=’ becomes ‘%3D in URL)

As much as possible, it is better to select the code challenge method as SHA256 then the flow will become more secure and hard to guess(if someone try to brute force it)

How to use PKCE in wso2 ISserver

Let’s see how we can turn on PKCE in wso2 IS server.Basically IS server can support PKCE automatically but it is not a mandatory thing so normal flow can work without any interruption.So in order to insist PKCE do as follow:

1. First download the WSO2 IS server and log in to the management console
2. Then go to Service provider tap and add a SP.
3. Then go and select Inbound authentication Config tap and select Oauth/OpenID connect configuration.

4.Now select configure button and it will pop a menu like below

5.Here tick the PKCE mandatory to set PKCE mandory for your authorization code flow with PKCE.(before that you have to set Call back URL)

If you are using WSO2 IS server for auth2.o, give a try on this feature.This will help you to make your network more secure and it is very easy to implement.You can try this out in playground sample application.

Summary

In brief PKCE will make authorization transfer more secure (in that try select code_challenge_method as SHA256).It has a simple mechanism like code_challenge = code_challenge_method(code_verifier).

References:

1. PKCE specification