Configure Single Sign On (SSO) for a Web App Using WSO2 Identity Cloud and Consume APIs Published in WSO2 API Cloud Using JWT Bearer Grant Type

WSO2 Cloud provides comprehensive set of cloud solutions, This includes; Identity Cloud, API Cloud, Integration Cloud and Device Cloud. Identity Cloud provides security while API Cloud provides API Management solution (In near future identity Cloud is going to provide full set of IAM solutions, where at the moment (May 2017) it has only supports Single Sign On). In real world scenarios, application security and API security goes hand in hand where most of the time these web apps need to consume secured APIs.

In this post, we  are going to  look at how we can configure security for a web app with WSO2 Identity Cloud and that application needs to consume some OAuth protected APIs published in WSO2 API Cloud.

If you need to configure SSO for a application with WSO2 identity Cloud, you need to configure a service provider in Identity Cloud representing your application. Document https://docs.wso2.com/display/IdentityCloud/Tutorials explains the services provider configuration options in detail. If you are configuring SSO for a your own application (not a pre-defined app like Salesfoce, AWS etc), there are two main options provided, that you can select. Those are "Agent based SSO" and "Proxy based SSO". Post http://dinushasblog.blogspot.com/2017/05/what-is-agent-and-proxy-based-sso-in.html explains what these two options are and when to choose which option, in detail.

Here, we are going to use Proxy based SSO option and configure SSO for a java web application. Once user is authenticated to access the application,   Identity Cloud sends a signed JSON Web Token (JWT token) to the backend application. This JWT token can be used with JWT bearer grant type to get an access token from API Cloud to consume APIs publish there.

Before that, what is JWT bearer grant type;
JWT bearer grant type provides a way for client application to request an access token from OAuth server, using an existing proof of authentication in the form of a signed claims which was done by different Identity Provider. In our case, Identity Cloud is the JWT token provider while API Cloud is the one provide OAuth acess tokens.

Step 1: Configure Service Provider in Identity Cloud

i. Login to Identity Cloud admin portal : https://identity.cloud.wso2.com/admin
ii. Add New Application (Note: Select the "Proxy" as app type)

iii. Go to user-portal of tenant. (I'm using wso2org as the tenant, hence my user-portal is https://identity.cloud.wso2.com/user-portal/t/wso2org). This will list the application there and if you click on it, you can invoke it.  Note that application URL is not the real endpoint URL of application that used to invoke it. This is because, since we used "Proxy" option, Identity Cloud acts as a proxy for this app and gives a proxy URL (also called as gateway URL).

You need to block the direct app invocations using firewall rule or nginx rule to make sure, all users can access application only through Identity Gateway with the provided proxy URL. Following diagram explains what really happens there.

That's all we have to do to get SSO configured for your web application with Identity Cloud using proxy option. In summary, you login to Identity Cloud admin portal, register a new application (service provider) there by providing your web app endpoint url and provide a new url context to get gateway url constructed. Gateway do the SAML authentication part on behalf of application. 

Step 2 : Use JWT Token sends by Identity Cloud to backend and get a access token from API Cloud to invoke APIs

Backend web app needs to consume some APIs published in API Cloud. But the user authentication for web app happened from Identity Cloud, how can it get a access token from API Cloud ? We can use JWT Bearer Grant type for that, since Identity Cloud gives a JWT token after user authentication.

This JWT token should contains API Cloud as an audience, if it need to be consumed by API Cloud. 

i. Edit the service provider (application) which was registered in Identity Cloud and add API Cloud's key manager endpoint as an audience. 

Service provider configuring UI provided in Identity Cloud admin portal does not have option to add audiences for proxy type apps (which should be fixed in UI). Until that we need to login to the carbon management console of Identity Cloud and configure it.  

NOTE : Carbon mgt UIs of WSO2 Cloud are not exposed to everyone. You need to contact wso2 cloud support by filling form https://cloudmgt.cloud.wso2.com/cloudmgt/site/pages/contact-us.jag  to get carbon mgt UI access. 

In the Carbon UI, navigate to Main -> Service Providers -> List -> Click Edit of Service provider that you created.  Inbound Authentication configuration -> SAML -> Audience URLs  -> Add "https://keymanager.api.cloudstaging.wso2.com/oauth2/token" as audience and update the SP. Refer following image.

ii. Configure Identity Cloud as a trusted IdP in API Cloud.

API Cloud should trust Identity Cloud as a trusted IdP, if it needs to issue an access token using JWT token issued by Identity Cloud.  We need to login to Carbon UI of API Cloud's Key Manager and configure Identity Cloud as a trusted IdP. 

NOTE : You need to contact wso2 cloud support by filling form https://cloudmgt.cloud.wso2.com/cloudmgt/site/pages/contact-us.jag  to get carbon mgt UI access of API Cloud's Key Manager. 

Navigate to Main -> Identity Providers -> Add -> Give the IdP details and Save

Identity Provider Name : wso2.org/products/appm

Identity Provider Public Certificate : Need to upload your tenant's public certificate here. You can get this by login to the admin portal of Identity Cloud and Click on "Download IdP Metadata" option provided in application listing page. This metadata file contains public certificate as a one metadata. You can copy and save certificate into a separate file and upload here.

Refer following image for add IdP.

Following images shows how you can download tenant's public certificate from Identity Cloud to upload above.

Downloaded metadata file will looks something similar following. Copy the certificate into a separate file and upload.

We are done with all configurations.

Step 3 : How to read the value of JWT Token and use it to request access token from API Cloud ?

JWT Token is sent to the backend in the header of "X-JWT-Assertion". Backend application can read the value of this header to get the JWT token.

Following image shows a sample JWT token printed by backend application by reading "X-JWT-Assertion" header.

Then backend application can use this JWT token and call to API Cloud token endpoint to get an access token using JWT bearer grant type. Before that you can copy this JWT token and use curl or some other REST client and test it. 

curl -i -X POST -H "Authorization:Basic <YOUR_Base64Encoded(ConcumerKey:ClientSecreat)>" -k 
-d 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<YOUR_JWT_TOKEN_HERE>' 
-H 'Content-Type: application/x-www-form-urlencoded' https://gateway.api.cloud.wso2.com:443/token

This should provide you a oauth access token from API Cloud.

That's it !

Reference to sample web application code: https://github.com/dinusha-dilrukshi/wso2-integration-scenarios

This sample web app contains whole scenario described in this post. Try it too.

What is Agent and Proxy Based SSO in WSO2 Identity Cloud ?

WSO2 Identity Cloud provides different options to easily configure Single Sign On (SSO) for your in-house enterprise applications and popular SaaS applications.

In the Service Provider configuration UI provided in Identity Cloud admin portal (https://identity.cloud.wso2.com/admin), you can see two options called "Agent" and "Proxy" that you need to select as App Type. Refer following image.

In this post we are going to look at a comparison of two options. So that it will help you to  decide which option is suitable for your app.

Agent based SSO (Agent Type)

• Authentication SSO request/response should be handled by application itself. We called this type as "Agent based" because, you can write a common separate module (agent) that can be used by all your applications to handle authentication. 

eg: If you need to configure SSO for your application with SAML 2.0, then you should implement logic in your app to initiate SAML authentication request to Identity Cloud and Identity Cloud will send the authenticated SAML Response to application. Application should process this SAML response and identity the user and extract required user claims. (Note: With Service Provider Initiated SSO (SP init SSO), there is a way Identity Cloud to initialize the authentication request and application to handle only response sent by Identity Cloud )

• Supports SAML 2.0, WS-Federation, OpenID connect standard protocols.

• If the application already written to support these protocols, agent based option is the best fit. eg: Saleforce, AWS, Concur, GotoMeeting like SaaS application provides configuration options to configure federated authentication from IdPs using these standard protocols.

• Following diagram illustrate how Agent Type app authentication works.

Proxy based SSO (Proxy Type)

• Authentication SSO request/response are handled by the Identity Gateway. Application do not have to worry about it. Once user authenticated through Identity Gateway, it sends a signed JSON Web Token (JWT Token) containing authenticated user info to the backend app.

• Application is given a proxy URL instead of real endpoint URL of app. Users should use this proxy URL instead of direct app endpoint to access it. 

• If application does not have internal logic based on authenticated user, you can simply publish the app as a Proxy app in Identity Cloud and done with it. This will ensures users cannot access this app, without authenticating from Identity Cloud.

eg: wso2.com (http://wso2.com) site does not need user authentication to see the content of it. If we need to give access only to authenticated users, we can publish (define) this as a proxy app in Identity Cloud. This will give a new proxy URL and that need authentication to access the site. 

• Most of the time applications need user information for application side session handling and execute some business logic. In this case application should process the JWT token sent by identity Gateway and extract the user information.

• If you are trying to configure SSO for a well known SaaS app like Salesforce, AWS etc, then proxy type is not the option for it. Because, these apps expect authenticated user info and they do not have a way to process JWT token to get that info. Therefore mostly, Proxy Type can be used if you have control over modifying application source code.

• Following diagram illustrate how proxy app type based app works.

• Identity Gateway (Proxy based apps) capable in providing authorization as well to the application, not only authentication. 

eg: It has capability to define rules like this, 

- Application can be accessed only if authenticated user is having a particular role. 

- Some of the resources in application should be allowed for selected roles, while other resources in app can be accessed by all authenticated users. (This can be done using role based or defining a XACML policy for that resource) 

- Define throttling limits for resources based on number of access by user

NOTE: Identity Cloud admin portal does not provide UI for some of these gateway functionalities, even though identity Gateway has capability on handling them. UI will be improved to support them in future.

• Following diagram shows the handler sequence that get executed when accessing a app as a proxy type app.

Hope this post will help you to select which app type is suitable for you from Agent and Proxy types.