Getting Started with OAuth 2.0 using WSO2 Identity Server 5.3.0 and Playground2 Sample

This blog post provides step by step instructions for trying out OAuth 2.0 using WSO2 Identity Server. Here I use Identity Server 5.3.0 which is the latest released version by the time of this writing. The official documentation for this is available in https://docs.wso2.com/display/IS530/OAuth+2.0+with+WSO2+Playground , however for a beginner, it does not provide all the instructions such as creating a Service Provider with necessary configuration. However, by following the steps below, you can simply setup Identity Server and the playground2 sample webapp and test the entire OAuth 2.0 flow.

Creating the Service Provider

First step is to create a service provider in Identity Server. This is required because when a client application talks to Identity Server via OAuth 2.0, Identity Server has to identify the client and the incoming traffic. We set this configuration inside the service provider.

Login to the Management Console of Identity Server and create a service provider. Here I give the name for the service provider as ‘playground2’.

Then, expand the ‘Inbound Authentication Configuration’ section in the service provider’s configuration and click on ‘Configure’ link which is listed under ‘OAuth/OpenID Connect Configuration’.

Set the configuration as shown in following image. As the Callback URL, we need to provide the URL of the client where Identity Server can send the responses (authorization code and access token will be sent by Identity Server to this URL of the client).

In my setup, I have deployed the playground2 sample in tomcat which runs in the localhost at port 8080. Therefore I provide the Callback URL as http://localhost:8080/playground2/oauth2client .

Then I can see the OAuth client key and the client secret generated by Identity Server.

Next step is to set the claim configuration of the service provider. By setting this, the playground2 client app will receive the user’s claims defined here when it requests for user’s profile information.

Here I add the claims using the Local Claim Dialect where the claim names received by playground2 app would follow the pattern http://wso2.org/claims/<claim name>. If you need to receive the claim names differently, you can define a custom claim dialect here.

Here I have added some claims to be received by the client as user profile information and I have defined the email address claim as the subject identifier which can be used to uniquely identify users in the client app’s end.

Creating a User for Testing

When testing the OAuth 2.0 grant types (flows), we need to authenticate with a user account (in grant types like authorization code) and then the client app can receive user claims defined in the profile. For that I am creating a user account here and setting the claims in the profile.

In the Management Console, go to Main -> Identity -> Users and Roles and click on Add. Then click on Add New User.

Give a username and password for the user account.

Here I grant admin role to the user since this is just a demonstration.

After adding the user, go to the User Profile.

Fill the values in the profile of the user.

By following the steps above, we have successfully configured Identity Server for trying out the OAuth 2.0 grant types.

Setting Up the Playground2 Sample OAuth 2.0 Client

Next step is to setup the OAuth 2.0 client application. The playground2 sample which is released with Identity Server 5.3.0 can be found in https://github.com/wso2/product-is/tree/v5.3.0/modules/samples/oauth2/playground2 . You can build the sample and get the .war file and deploy it in an application server like Apache Tomcat. Here I have deployed the application in tomcat which runs on port 8080 of localhost.

So, I can access the Playground2 app in browser in http://localhost:8080/playground2 .

Here I try out the Authorization Code grant type. Following similar steps, other grant types also can be tested easily.

As the Client Id, I enter the OAuth Client Key which I got when I created the Service Provider.

As the scope, I provide ‘openid’ since I need to retrieve the user claims in the profile.

The Callback URLof Playground2 app is http://localhost:8080/playground2/oauth2client . The Authorize Endpoint of Identity Server is https://localhost:9443/oauth2/authorize since the Identity Server runs on localhost at port 9443 in my environment.

After filling the above data and sending the authorize request to Identity Server, it prompts to login as I have not yet logged into Identity Server.

After authentication, I see the following screen to provide mandatory claims. (I have already added values for these claims in the profile of the user I logged in, so I’m not sure why it’s asked again).

Then we can see the user consent page where it shows that the client app needs the user’s permission to access the profile information of the users. So I approve this.

Now, Identity Server sends the authorization code to the Playground2 client through browser redirection. Here we need to provide the Access Token Endpoint of Identity Server, which is https://localhost:9443/oauth2/token . In addition to that, we need to provide the Client Secret which we received after creating the service provider.

After that, we can request for the access token from Identity Server, providing the authorization code.

Then the Identity Server sends the OAuth 2.0 access token. In order to request user’s profile claims, we need to send the request to the UserInfo endpoint of Identity Server. The URL is

https://localhost:9443/oauth2/userinfo?schema=openid .

Now the client app receives the claims of the user profile.