Friday, August 11, 2017

Amazon Web Services (AWS) integration with WSO2 Identity Server (WSO2 IS)


Amazon Web Services (AWS) supports federated authentication with SAML2 and OpenId Connect standards. This gives capability to login to AWS Management console or call the AWS APIs without having to create an IAM user in AWS for everyone in your organization.

Benefits of using federated single sign on login for AWS access 

  • No need to create IAM users in AWS side
    • If organization having existing user store, we can use it as the user base for AWS 
  • You can use single identity for user,  all over the systems used by your organization
    • This makes administrator life easier when user onboarding or offboarding to the organization

In this tutorial we are going to look at following integration scenarios;
  1. Connect WSO2 Identity Server (WSO2 IS) to single AWS account
  2. Connect WSO2 Identity Server to multiple AWS accounts

1. Connect WSO2 Identity Server to single AWS account

Business Use case : Your organization owns a AWS account and need to give different level of privilege access to AWS console to organization users.

How to configure WSO2 IS to support this: This tutorial explains the required steps for this including Multi Factor Authentication (MFA)   

2. Connect WSO2 Identity Server to multiple AWS accounts

Business Use case :  Your organization can owns multiple AWS accounts (eg: Development, Production), you need to assign different level of permissions in these accounts using the existing identity used for users in organization user store (ldap, jdbc etc).

How to configure WSO2 IS to support this:
Following tutorial explains required configurations for this.

We assume a user Alex in organization ldap, which need to give EC2 Admin permissions in development AWS account and need to have only EC2 read only access to the production AWS.

Business Requirements:
  • Organization use WSO2 IS as the Identity Provider (IdP). Use same IdP to authenticate users to AWS Management console as well
  • User Alex in organization should be able to log into development AWS account as an EC2 admin user
  • Alex should be able to log into production AWS account using the same identity,  but only with EC2 read only access
  • Alex should be able to switch role from  development account to production account

Configuration Guide

1. Configure AWS

1.1.  Configure AWS Development Account

Step 1: Configure WSO2 IS as an Identity Provider in Development Account

 a. Log into AWS console using development account, navigate to Services, then click on IAM

b. Click on "Identity Provider" from left menu and then click on "Create Provider"

c. On the prompt window provide following info and click on "Create"

Provider Type : SAML
Provider Name: Any preferred name as identifier (eg:wso2is)
Metadata Document: Need to download WSO2 IS IdP metadata file and upload here.  Following is the instructions to download IdP metadata file from WSO2 IS.

Login to WSO2 IS management console as admin user. Navigate to "Resident" under "Identity Providers" left menu.  In the prompt window, expand the "Inbound Authentication Configuration", then expand the "SAML". There you can find the "Download SAML Metadata" option. Click on it, this will give option to save IdP medata in medata.xml file. Save it to local file system and upload it in AWS IdP configure UI as the Metadata Document.

AWS IdP configuring UI

d. Locate the Identity Provider that we created and make a copy of Provider ARN value. We need this value later in the configurations.

Step 2: Add AWS IAM roles and configure WSO2 IS Identity provider as trusted source in these roles

a. We need to create a AWS IAM role with EC2 Admin permissions since Alex should have EC2 Admin privileges in  development AWS account.

Option 1 : If you have an existing role.
If you have an existing role with EC2Admin permissions, then we can edit the trust relationship of role by giving SSO access to WSO2 IS identity provider. If you do not have an exiting role, move to the option 2 which describes with adding a new role.

Click on the desired role -> Go to "Trust Relationships" tab and click on "Edit trust relationship"

If your current trust relationship policy is empty for this role, you can copy and replace following policy configuration there after replacing the <Provider ARN Value of IdP> value (i.e the Provider ARN value that you taken in step1)

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<Provider ARN Value of IdP>:saml-provider/local-is"
      "Action": "sts:AssumeRoleWithSAML",
      "Condition": {
        "StringEquals": {
          "SAML:aud": ""

If you have a current policy in place, then you need to edit existing policy and include SSO access for WSO2 IS.

Option 2 : Create and assign permissions to a new role.

Go to "Roles" and Click on "Create new role". Select the role type as "Role for identity provider access" since we need to allow SSO access using WSO2 IS.

Select wso2is as the SAML provider and click Next.

On the next step just verify the trust policy and click on Next.

Select your preferred policy to be assigned to the role that you are creating. As per our sample scenario, we need to assign "AmazonEC2FullAccess" policy to give EC2 Admin permissions to this role.

Give a preferred role name and click on "Create".  (eg: Dev_EC2_Admin)

b. Locate the Role ARN value in role summary page and make a copy of the value. We need this value later in the configurations.

Now we have configured WSO2 IS as a SAML Identity Provider for development AWS account and also created a role with EC2 full access permissions allowing sts:AssumeRoleWithSAML capability to WSO2IS saml-provider.

1.2.  Configure AWS Production Account

Step 1 : We need to repeat the same step we did for development account previously with the step 1 and configure WSO2 IS as an Identity Provider for production account as well.

Step 2 : Similar to we created Dev_EC2_Admin role in development account, we need to create EC2ReadOnly role in production AWS account. (As per our sample scenario, Alex should have EC2 read only access to the production AWS account). Only difference is you need to select the appropriate policy (AmazonEC2ReadOnlyAccess) for this role. Refer following which highlights only this step.

Once the role is created, make a copy of Role ARN value of this role as well.  We need this value later in the configurations.

1.3. Configure account switch capability from AWS development account's Dev_EC2_Admin role to production account's Prod_EC2_ReadOnly role

a. Login to the AWS development account and configure an IAM policy that grants privilege to call sts:AssumeRole for the role that you want to assume (i.e we need to assume Prod_EC2_ReadOnly role in production account).  To do this,

1. Select "Policies" in the left menu and click on "Create Policy" option. Pick the "Create Your Own Policy" option there.

2. Give a relevant name for policy name and copy the following policy configuration after replacing <Prod_AWS_Account_Id> and <Prod_AWS_EC2_ReadOnly_Role> values as the content.

    "Version": "2012-10-17",
    "Statement": [
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::Prod_AWS_Account_Id:role/Prod_AWS_EC2_ReadOnly_Role"

3. Attach the policy that we created in previous step to Dev_EC2_Admin role in development account. For this, click on the role name and click on "Attach Policy" in resulting window.

Now we have given permissions to Dev_EC2_Admin role in development AWS account to to assume the role Prod_EC2_ReadOnly in production account.

b.  Login to the production AWS account and edit the trust relationship of role Prod_EC2_ReadOnly, by adding development account as a trust entry. To do this,

1. Click on the role name "Prod_EC2_ReadOnly" and navigate to "Trust relationships" tab and click on "Edit trust relationship" option.

2. In the resulting policy editor, copy following configuration and update the trust policy after updating your development account id for <Dev_Account_Id>.

  "Version": "2012-10-17",
  "Statement": [
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::222222222222:saml-provider/wso2is-local"
      "Action": "sts:AssumeRoleWithSAML",
      "Condition": {
        "StringEquals": {
          "SAML:aud": ""
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<Dev_Account_Id>:root"
      "Action": "sts:AssumeRole"

We are done with the AWS configurations. We need to configure WSO2 IS to SSO with these two accounts now.

2. Configure AWS app in WSO2 IS

1. Login to the WSO2 IS Management console, then navigate to Main -> Service Providers -> Add from the left menu. Provide any proffered name to "Service provider name" (eg: AWS) and click on register.

2. In the resulting window, expand the "Claim Configuration" section, then select the "Define Custom Claim Dialect" option and do following claim mapping. -> ->

3. Expand the "Role/Permission Configuration", then "Role Mapping" and add following role mappings.
What we do here is, map local roles in wso2is to AWS roles. We have two ldap roles called "dev_aws_ec2_admin" and "prod_aws_ec2_readonly"  which assigned to organization users to give required access to AWS developer and production account.

When you do the mapping pick relevant role in your organization user store instead of dev_aws_ec2_admin and prod_aws_ec2_readonly. Also relevant Role ARN and Provider ARN values from each account.

dev_aws_ec2_admin ->

prod_aws_ec2_readonly ->
dev_aws_ec2_admin -> arn:aws:iam::222222222222:role/Dev_EC2_Admin,arn:aws:iam::222222222222:saml-provider/local-is
prod_aws_ec2_readonly -> arn:aws:iam::111111111111:role/Prod_EC2_ReadOnly,arn:aws:iam::111111111111:saml-provider/wso2is-local

4. Expand the "Inbound Authentication Configuration", under that "SAML2 Web SSO Configuration" and select "Configure".

In the configuration UI, provide following fields and click update.

Issuer : urn:amazon:webservices
Default Assertion Consumer URL :
Enable Attribute Profile: Checked
Include Attributes in the Response Always: Checked
Enable IdP Initiated SSO: Checked

5.  Open the IS_HOME/repository/conf/user-mgt.xml and find the active user store configuration there. Change the MultiAttributeSeparator value to something different from comma (,) and restart the server.

<Property name="MultiAttributeSeparator">$$</Property>

Why we need to change this MultiAttributeSeparator value is, this property is used to separate the multiple attributes. By default this is set to a comma (,). But since we need to use AWS Role ARN, Provider ARN as a single value, we need to change it's value to something different from comma.

We are done with all configurations.

3.  Testing

1. Before access AWS console, login to the WSO2 IS Management console and confirm whether user Alex is having required roles assigned. Also Alex's user profile has been updated with his email address which mapped as RoleSessionName claim in AWS.

2.  Access the AWS console using following url. (Replace the <WSO2IS-HOST>:<PORT> as relevant).

3. Previous step will redirect you to WSO2 IS login page and once user Alex provided credentials and authenticated, AWS will provide it's role selection page where user can pick the role for current session and continue.

4. Alex can switch role from development account to production role using either switch role option provided in AWS console or the Switch Role URL associated to AWS role.

AWS switch role url can be found in the role detail. Usually this is in the format of;<AWS_ACCOUNT_ID>&roleName=<AWS_ROLE_NAME>

If you provide production account id and role as "Prod_EC2_ReadOnly" in the above URL, you can see that Alex can switch to production account's  Prod_EC2_ReadOnly role from development account where he was logged in.

Monday, May 29, 2017

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 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 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 :
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 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  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 "" 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  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 :

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'

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

That's it !

Reference to sample web application code:
This sample web app contains whole scenario described in this post. Try it too.

Sunday, May 28, 2017

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 (, 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: ( 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.

Saturday, February 25, 2017

WSO2 Identity Cloud in nutshell

WSO2 Identity Cloud is the latest addition to  WSO2 public Cloud services.  Identity Cloud is hosted using WSO2 Identity Server which provides Identity and Access Management (IAM) solution. Initial launching of Identity Cloud has been focused on providing Single Sign On (SSO) solutions for organizations.

All most all the organizations use different applications. This cloud be in-house developed and hosted applications or Salesforce, Councur, AWS like SaaS applications. Having centralized authentication system for all the applications will increase the efficiency of maintaining systems, centralize monitoring and company security from system administrative perspective while it makes application users life easy. WSO2 Identity Cloud provides solution to configure SSO for these applications.

What are the features offered by WSO2 Identity Cloud ?

  • Single Sign On support with authentication standards - SAML-2.0, OpenID Connect, WS-Federation
     Single Sign On configurations for applications can be done using   SAML-2.0, OpenID Connect, WS-Federation protocols.   
  • Admin portal
    Portal provided for organization administrators to login and configure security for applications. Simplified UI is provided with minimum configurations. Pre-defined templates of security configurations are available by default for most popular SaaS apps. This list includes Salesforce, Concur, Zuora, GotoMeeting, Netsuite, AWS.
  • On-premise-user-store agent
    Organizations can connect local LDAP with Identity Cloud without sharing LDAP credentials with Identity Cloud and let users in organization LDAP to access applications with SSO.
  • Identity Gateway
    Act as a simple application proxy that intercepts application requests and applies security checks.
  • User portal
    User Portal provides a central location for the users of an organization to log in and discover applications in a central place, while applications can be accessed with single sign-on.

Why you should go for a Cloud solution ?

Depending on organization policies and requirements, you can either go for a on-premise deployment or Cloud Identity solution. If you have following concerns then selecting Cloud solution is the best fit for you.

  • Facilitating infrastructure - You don't have to spend money on additional infrastructure with the Cloud solution.
  • System Maintenance difficulties - If you do a on-premise deployment, then there should be a dedicated team allocated to ensure the availability of system and troubleshoot issues etc. But with the Cloud solution WSO2 Cloud team will take care of system availability. 
  • Timelines - Identity Cloud is a already tested, up and running solution. This will cut off the deployment finalizing and testing times that you should spend on a on-premise deployment.   
  • Cost - No cost involve for infrastructure or maintenance with the Cloud solution.

We hope WSO2 Identity Cloud can help building a Identity Management solution for your organization. Register and tryout for free - and give us your feedback on or