Wednesday, October 11, 2017

Getting Started with OAuth 2.0 using WSO2 Identity Server

WSO2 Identity Server can act as an authorization server in OAuth 2.0 [1] protocol. In this blog post, I am providing the steps for you to try out each OAuth grant type using WSO2 Identity Server. As the Identity Server supports the standard requests and responses in OAuth grant types, the same steps would be applicable for other OAuth authorization servers as well. Here I use the Identity Server 5.3.0 version, which is the latest released GA version at the time of this writing.

Protocol Endpoints

Once you start WSO2 Identity Server, by default it runs on localhost and on port 9443. So, the OAuth 2.0 protocol endpoints in the authorization server are as following.

Authorization Endpoint : https://localhost:9443/oauth2/authorize


Client Registration

Before making OAuth requests, we should register a client application in Identity Server to obtain the credentials of the client.

Login to the Management Console and Add a Service Provider.


In the Service Provider configuration, expand Inbound Authentication Configuration and under that you will find OAuth/OpenID Connect Configuration. Click on the Configure option there.


The Callback URL is the Redirection Endpoint (redirect_uri) of the client application where the authorization server should send the responses. Here I define the redirect_uri with the dummy value http://myoauthclient.com/callback although I do not have a client application running in that URL. That is fine because we can manually run through all the OAuth grant types using any dummy redirect_uri. If you are trying this out, you can put any URL as you wish.

In the configuration, it has checkboxes for each grant type. I am keeping all the checkboxes selected here, although in this article I will only demonstrate the authorization code, implicit, resource owner password credentials and client credentials grant types.

After successfully registering the OAuth client application, we can obtain the Client Key and Client Secret for the application. Update the service provider to persist the configuration of the OAuth client.

These are the values I have got. When you try out the same steps, you can use the values which you have received.

Client Key : 3T6XUzSJBZVHWlyzfV0Q3d7r7DEa
Client Secret : 39jR0RugVmUIfnVLgWVnfkEHIUoa


Authorization Code Grant Type

For trying out the authorization code grant type, we can prepare a URL like below (to the authorization endpoint of Identity Server with required query parameters) and visit that in the browser. Note that the redirect_uri is URL encoded.


Then, Identity Server would authenticate the user (resource owner). Here I need to provide user account credentials and login to Identity Server.


Then it will show the User Consent Page and ask the user to grant authorization for the client for the requested scopes.


Then, Identity Server will redirect the user agent (browser) to the redirect_uri with the query parameter ‘code’ that has the authorization code value. (Here since I don’t have a web application running in the redirect_uri, it shows the error. However I can manually extract the authorization code from the URL and continue the flow.

Now that we have the authorization code, next step is to request the OAuth access token from the Token Endpoint of the Identity Server. Here, we need to authenticate the client application. For that, in the HTTP Headers, I need to use the “Authorization: Basic XXX” header where the value is the Base 64 encoded string of ClientID:ClientSecret value.

I am using curl for making the HTTP POST request to the Token Endpoint. Similarly we can use any HTTP client (even RESTClient addon in browser).


curl -k -X POST --header "Authorization: Basic M1Q2WFV6U0pCWlZIV2x5emZWMFEzZDdyN0RFYTozOWpSMFJ1Z1ZtVUlmblZMZ1dWbmZrRUhJVW9h" --data "grant_type=authorization_code&redirect_uri=http%3A%2F%2Fmyoauthclient.com%2Fcallback&code=3d7f3e3c-8989-3301-8fdc-4f912fd2d5f8" https://localhost:9443/oauth2/token



As the response, I receive the following JSON payload which contains the OAuth access token and also the refresh token.


{
  "access_token":"44b279b3-2c3b-3a6f-b51b-845c15f3dd26",
  "refresh_token":"9380f382-dfd7-39d2-bee6-a89162d19d37",
  "scope":"openid",
  "id_token":"eyJ4NXQiOiJObUptT0dVeE16WmxZak0yWkRSaE5UWmxZVEExWXpkaFpUUmlPV0UwTldJMk0ySm1PVGMxWkEiLCJraWQiOiJkMGVjNTE0YTMyYjZmODhjMGFiZDEyYTI4NDA2OTliZGQzZGViYTlkIiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoidWlob20wZXNhelZJMHI3WUtJLUJuUSIsInN1YiI6ImFkbWluIiwiYXVkIjpbIjNUNlhVelNKQlpWSFdseXpmVjBRM2Q3cjdERWEiXSwiYXpwIjoiM1Q2WFV6U0pCWlZIV2x5emZWMFEzZDdyN0RFYSIsImF1dGhfdGltZSI6MTUwNzc1MjQwMCwiaXNzIjoiaHR0cHM6XC9cL2xvY2FsaG9zdDo5NDQzXC9vYXV0aDJcL3Rva2VuIiwiZXhwIjoxNTA3NzU2MTc3LCJpYXQiOjE1MDc3NTI1Nzd9.hM43uJBQyI72OJXzHKzB0C1AxBgaOSPi6PySJr7HJyeR1k-AXxCDuWGfTsSVSf4WZNfaPaxMgw-xyjmLVztyqXOpXQXolDgnOMwkJYc4vrDrkg7gqxJhpoedS_bdg1905Gj-xYBawNfxYSdEXoaYxNIoGpTYOBSlK2wtxm0ExbE",
  "token_type":"Bearer",
  "expires_in":3600
}


Implicit Grant Type

In this grant, we can prepare the URL as following with the required parameters and invoke the authorization endpoint of Identity Server.


Once we access this URL in the browser, it will prompt for user authentication (if the user is not already logged into Identity Server) and then it will get the user’s approval from the User Consent page. Finally it will redirect the user-agent to the redirect_uri where the OAuth access token would be sent in the URL fragment.



Resource Owner Password Credentials Grant Type

Here we directly invoke the Token Endpoint of Identity Server with the required parameters. In the HTTP body, we need to provide the resource owner’s credentials as username and password parameters. In the HTTP Authorization header, we need to send the client’s credentials (clientID and clientSecret).

curl -k -X POST -H "Authorization: Basic M1Q2WFV6U0pCWlZIV2x5emZWMFEzZDdyN0RFYTozOWpSMFJ1Z1ZtVUlmblZMZ1dWbmZrRUhJVW9h" --data "grant_type=password&scope=openid&username=admin&password=admin" https://localhost:9443/oauth2/token

The response we get here is similar to Authorization Code grant’s response.



Client Credentials Grant Type

Here, we directly invoke the Token Endpoint of Identity Server, sending the required parameters. For authenticating the client, we use the Authorization HTTP header.

curl -k -X POST -H "Authorization: Basic M1Q2WFV6U0pCWlZIV2x5emZWMFEzZDdyN0RFYTozOWpSMFJ1Z1ZtVUlmblZMZ1dWbmZrRUhJVW9h" --data "grant_type=client_credentials&scope=openid" https://localhost:9443/oauth2/token


Retrieving User Profile Information using OAuth Access Token

Once we have obtained the OAuth access token for a user, then we can invoke the User Info Endpoint of Identity Server providing the access token in the Authorization header as a bearer token.

curl -k -X POST -H "Authorization: Bearer 44b279b3-2c3b-3a6f-b51b-845c15f3dd26" https://localhost:9443/oauth2/userinfo?schema=openid

Then in the response, we receive the user’s profile attributes as a JSON message.


We can configure the attributes to be received in the JSON response from the Service Provider configuration. In the Claim Configuration section of the Service Provider, we can add the claims we require in the response.


Additionally, we need to make sure the request claim URIs are already there in the OIDC claim dialect (http://wso2.org/oidc/claim). If a claim is not already there in the OIDC claim dialect, then we need to add it in order to be included in the JSON response sent by the Identity Server.

Also, we need to make sure the user’s profile has the values set for the claims that we need to include in the response.



References


Tharindu Edirisinghe
Platform Security Team
WSO2

Tuesday, September 19, 2017

Using Salesforce as an Identity Provider for WSO2 Identity Server over SAML 2.0 Web SSO


This article provides all the necessary steps to be followed when configuring WSO2 Identity Server to federate user identity with Salesforce.com.

System Architecture and Message Flow


Following diagram shows the important components in this setup and shows the order of the message flow.


In a high level view, here I have a web application (travelocity.com sample app) that tries to get authenticated with WSO2 Identity Server over SAML 2.0 protocol. When the authentication request comes, Identity Server forwards the request to Salesforce by sending another SAML authentication request. Then, Salesforce prompts the user to login. Here, the end user should have an account created in Salesforce.com. After the user is logged in, Salesforce then sends the SAML response to Identity Server, which contains the SAML assertion that holds the authenticated user’s attributes (claims). Then, WSO2 Identity Server processes the response sent by Salesforce, and generates its own SAML response (claim transformation can be done during the process) and sends it to the client web application. Finally, the client web application processes the received SAML response, identifies the logged in user and completes the authentication process.

Now let’s get started setting up the above environment. First I am configuring the Salesforce, then WSO2 Identity Server and finally, the client web application.

Salesforce Configuration


The following sections below provide all necessary steps to be followed and the configuration to be created in Salesforce side.

Creating a Salesforce Account


If you do not have a Salesforce account yet, visit the Identity Platfrom of Salesforce from https://www.salesforce.com/products/platform/products/identity/  and click on ‘Try for Free’.


Then you need to fill the registration form and submit. After that, login to Salesforce Developer account on https://developer.salesforce.com/ and when it requests your permission to access your profile information, proceed with clicking ‘Allow’.


You might need to fill some additional details about you to continue.


Once above steps are done, you will see the following dashboard. Click on the Settings icon located in the top of the right hand side and then click on ‘Setup’.



Registering a Domain in Salesforce


Now, for using Salesforce as an Identity Provider, we need to have a domain registered in Salesforce. For that, in the search text box located in the left menu panel, type ‘my domain’. Then you will see ‘My Domain’ link getting listed under Company Settings. Click on that.


Fill the text box with a suitable domain and register it. The domain will follow the pattern https://<your_domain>.my.salesforce.com.


After completing the above steps, it will take around 2 minutes (or couple of more minutes) for Salesforce to publicly make the domain available. Once that is done, you will receive an email.

Creating the Identity Provider Configuration in Salesforce


For Salesforce to act as an Identity Provider, we need to setup an Identity Provider in Salesforce side. For that, in the search textbox in left menu, type ‘identity provider’ and it will suggest you the ‘Identity Provider’ link listed under ‘Identity’ settings. Click on that and then enable the Identity Provider.



Then, you can download the public certificate of this Identity Provider and the Meta Data. You need to keep the downloaded files to be used later, when configuring the Identity Provider in WSO2 Identity Server.


Creating the Service Provider Configuration in Salesforce


Next step is to create the Service Provider in Salesforce side. This is how Salesforce identifies the informing authentication requests and decide how to proceed. Inside the Identity Provider settings, in the Service Providers section, click on the link available for creating the Service Provider.


You can give a name for the Service Provider and fill the required details.





In the ‘Web App Settings’ click on ‘Enable SAML’ checkbox. Then, fill the Entity Id text box with a suitable name. Note that the same name you enter here has to be put in WSO2 Identity Server when creating the Identity Provider configuration in that later.

The ACS URL (Assertion Consumer URL) is the endpoint in WSO2 Identity Server which accepts the response sent by Salesforce. That is https://localhost:9443/commonauth (you can put the IP address if any).

The Issuer is the Domain URL you got from Salesforce after registering your domain.

As the IDP Certificate, you can select the certificate from the dropdown. The SAML responses/assertions will be signed from the same certificate.



Once completing above steps, save the settings and it will show a summary of the service provider configuration.




If you need to edit the Service Provider configuration later, in the left menu, search for ‘apps’ and it will list ‘Manage Connected Apps’ link. From there, you can see the already created applications (Service Provider Configuration is added inside an application) and edit them.





Here is the Application which I created for this usecase which lists all the configuration created.



Here, there are two important URLs to be note which are given below for your reference.



SP-Initiated POST Endpoint
https://tharinduatwso2.my.salesforce.com/idp/endpoint/HttpPost
SP-Initiated Redirect Endpoint
https://tharinduatwso2.my.salesforce.com/idp/endpoint/HttpRedirect


In Salesforce end, there are two different endpoints as above, for HTTP POST binding and HTTP Redirect Binding in SAML protocol. We need to use once appropriately (This is important when setting up the Identity Provider configuration in WSO2 Identity Server later).

Creating a User Profile


Now that the Identity Provider configuration and Service Provider configuration are created in Salesforce side, next step is to create a user profile and bind the application we created above, to that. You can use an already existing profile as you wish without creating a new profile if you wish.


Here, under ADMINISTRATION -> Users, click on Profiles and click on ‘New’ for creating a new profile.



Here I am cloning the existing ‘Standard User’ profile and creating a new profile with the name ‘Identity User’. (you can use any name as per your requirement).



Then I edit the created profile.



In the Profile configuration, under the ‘Connected App Access’ section, I click on the IdentityServer application and enable it. Here, IdentityServer is the application I created previously when creating the Service Provider configuration.



If you are not creating a new user profile, you can edit an existing user profile and enable the application for accessing as above.

Creating a User in Salesforce


Next step is to create a user in Salesforce. This is the user account that we are using when Salesforce prompts for user authentication in the this flow. If you already have users in Salesforce, you can skip creating new users.

In the search textbox in the left menu, search for ‘users’  and it will list the ‘Users’ link. From there, you can create new users.



Here I fill the user’s personal information. The important step is the select the user’s profile. The profile you select here must have the application (created previously) enabled for ‘Connected App Access’ as discussed before.


Here I click on ‘Save’ and complete user account creation. (The end user will receive an email for activating the account and resetting password).


With above, we have completed all necessary configuration in Salesforce side.

WSO2 Identity Server Configuration


The following sections below provide all necessary steps to be followed and the configuration to be created in WSO2 Identity Server side. Here I use WSO2 Identity Server 5.3.0 version (latest released GA version by the time of this writing).

Create Identity Provider Configuration


In this step, we create the configuration for letting WSO2 Identity Server know how to talk to Salesforce. Here add an Identity Provider and give the name salesforce.com. You can give any name as you wish.

Then you can give the ‘Identity Provide Public Certificate’ which you downloaded from Salesforce when configuring the Identity Provider in Salesforce. (You can skip this if you are going to create the configuration using SAML Metadata file, which I will explain in the next step).


Inside the Identity Provider configuration, expand the Federated Authenticators -> SAML2 Web SSO Configuration.

Click on the ‘Enable SAML2 Web SSO’ checkbox for enabling this SAML authenticator for this Identity Provider configuration.

Provide the Service Provider Entity Id field with the same name you defined in the Salesforce’s Service Provider’s ‘Entity Id’ field.

Then, you can either manually fill all the details and complete the configuration, or you can use the Metadata file downloaded from Salesforce Identity Provider, so it will automatically fill the details for you.

Here I am using the Metadata file downloaded from Salesforce to create the required SAML configuration.


Once you try to register the Identity Provider using the metadata file, it will show this warning. You can continue as we do not have created the configuration already. If you added the Salesforce’s Identity Provider certificate previously, it will be replaced. So, if you are creating the Identity Provider’s SAML configuration from the metadata file, adding the public certificate manually is not required.


Then I can see the required configuration is created. Alternatively you can do the same manually, without using the metadata file.



In above configuration, it is important to define the SSO URL correctly. Because, based on the HTTP Binding you are going to use, the SSO URL in Salesforce differs.

Inside the SAML configuration of the Identity Provider, it has the HTTP Binding radio buttons which you can use as per your requirement.


For HTTP-Redirect Binding, the SSO URL should be,  https://<your_domain>.my.salesforce.com/idp/endpoint/HttpRedirect   

For HTTP-POST Binding, the SSO URL should be,
https://<your_domain>.my.salesforce.com/idp/endpoint/HttpPost


Now that we have created the necessary configuration, click on ‘Update’ and complete the Identity Provider configuration creation in WSO2 Identity Server.

Create the Service Provider Configuration


Next step is to create the Service Provider configuration in WSO2 Identity Server. This is how Identity Server knows how to handle requests from client applications.

Add a Service Provider. Here I give the name ‘travelocity.com’, because I use the travelocity.com sample web application for this demonstration.


In the Service Provider’s configuration, expand Inbound Authentication Configuration -> SAML2 Web SSO Configuration and click on ‘Configure’.



Then I set the Issuer name to ‘travelocity.com’ and the Assertion Consumer URL to http://localhost:8080/travelocity.com/home.jsp (here I run the travelocity sample app in Tomcat server running on port 8080 of localhost). Once this configuration is set, click on ‘Update’.


We can see that the SAML configuration is created successfully. ‘Update’ the Service Provider configuration with this.
Now, WSO2 Identity Server can accept client web application’s requests over SAML 2.0 protocol. However, we need to redirect the flow to Salesforce, because the end user has to be authenticated with Salesforce. For making this connection work, edit the Service Provider you just created and expand the Local & Outbound Authentication Configuration. Select ‘Federated Authentication’ option and from the dropdown, select the Identity Provider you created previously for Salesforce.


Now we have completed all the configuration in WSO2 Identity Server.

Setting up the Client Web App


Here I use the travelocity.com sample webapp which is a client web application for demonstrating SAML 2.0 authentication flows. You can find the pre-built .war file from

Here I deploy this application (war file) in Apache Tomcat server running on port 8080 in localhost.

I can access the application from the URL http://localhost:8080/travelocity.com/index.jsp.

Testing the Authentication Flow


In the travelocity.com sample client application, I click on the link available for SAML authentication. (You can select either Redirect Binding or POST binding).


Once you click the above link, it makes a SAML authentication Request to WSO2 Identity Server. Then, as we have configured Identity Server to forward the requests to Salesforce, Identity Server will make a SAML authentication request to Salesfofce. Then, Salesforce will prompt its login page and ask the end user to login.

Here I enter the user credentials (this user’s profile is already enabled with the Connected App Access) of the Salesforce user I created previously.


Then, Salesforce will send the SAML response to WSO2 Identity Server which contains the user’s attributes. Finally, Identity Server will generate it’s own SAML response and forward that to the client web application (Claim transformations can be done during the flow).

Finally, the client web application reads the received SAML response and get to know the logged in user and completes the authentication flow.



Written by: Tharindu Edirisinghe, Platform Security Team, WSO2