Sunday, September 21, 2014

Leveraging federation capabilities of Identity Server for API gateway - Configuration Details

With this post I am to share the steps of a popular solution using WSO2 Identity Server and WSO2 API Manager. Following diagram will give an initial insight on this solution.


1.  Webapp that requires single sign on(SSO) facility with some other applications. 
                - To achieve this we are using WSO2 Identity Server(IS) as the Identity Provider(IDP). 

2.  Webapp needs to consume some APIs secured with OAuth tokens. 
                - To expose the APIs secured with OAuth tokens we are using WSO2 API Manager(AM) here.
                - Since we already have the SAML Response received at SSO step, SAML2 Bearer grant type is ideal to use at this scenario to request an OAuth token to access the required APIs.
                - Allowing AM to properly issue an OAuth token in this scenario, we add IS as a trusted IDP in AM.

3.  Webapp requires to allow users registered in another IDP like Facebook or Google to be able to login with SSO functionality. 
                - With minimum configurations to internal IS and external IDP side, we need to achieve this.
Rest of this post will deal with how we can configure the above, without sharing any databases underneath. Will setup this in multi-tenancy mode, to make it a more general scenario. Another instance of WSO2 Identity Server will be used in the place of external IDP. This can be replaced with Facebook, Google etc. according the requirement.


WSO2 Identity Server -5.0.0 -
WSO2 API Manager 1.7.0 -
                             The compiled webapp ready to deploy in a servelet container, can be found here.
As we are to run several instances of WSO2 servers we need to configure port offsets, if all are configured in one machine. Following are the port offsets and ports I am to use. I will be using two tenants in the two Identity servers and API manager will be run of super tenant mode.

1. WSO2 Identity Server -5.0.0 - Internal IDP - Offset 0 - Port 9443 
                 Tenant -
2. WSO2 Identity Server -5.0.0 - Internal IDP - Offset 1 - Port 9444 
                 Tenant -
3. WSO2 API Manager 1.7.0 - API Gateway - Offset 2 - Port 9445
                 Tenant - carbon.super

Webapp Configurations 

If you download the webapp from the above link, the keystore configurations are already done. You will only need to import the public certificate of the tenant in internal IDP( to the keystore of webapp 'travelocity.jks'. 
Please note the following configurations done in file found inside webapp at '/'.


#A unique identifier for this SAML 2.0 Service Provider application

#The URL of the SAML 2.0 Identity Provider

#Password of the KeyStore for SAML and OpenID

#Alias of the IdP's public certificate

#Alias of the SP's private key 

#Private key password to retrieve the private key used to sign 
#AuthnRequest and LogoutRequest messages

#OAuth2 token endpoint URL

#OAuth2 Client ID

#OAuth2 Client Secret

1. SSO Setup with Internal IDP

  • Login as tenant admin - <admin>
  • Export the public certificate of the private key used at webapp side to sign the SAML Authentication Request. Following command can be used to export it.
keytool -export -alias travelocity -file travelocity -keystore <path to travelocity.jks(which ever keystore used at webapp side)>
  • Import the above exported public certificate to the tenant key store of the internal IDP, identity server as below.

  • After the import it will listed as below.

  • Create a new Service Provider for Travelocity webapp as following.
  • Then we needs to configure it as below.    
- By enabling SaaS application, we are removing the tenant boundary for this service provider.
- Enable response and assertion signing according to your requirement.
- Enable signature verification for SAML Authentication Request

The configurations are mostly done to get the SSO scenario work with the webapp. We need to export the tenant public certificate to be imported to the trust store at webapp side. This is in order to verify the SAML Response/Assertion signed signature at the webapp side. We can export the certificate as below from the UI, using public key link.


The exported key needs to be imported to webapp truststore(in this case travelocity.jks we located inside the webapp).

keytool -import -alias <The given alias name. Here> -file <path to downloaded public certificate> -keystore <path to trust store of webapp. Here the travelocity.jks file>

Now if you try to login to travelocity web app as a tenant user, it should succeed.

2. External federation

Following configuration will demonstrate how to configure an external identity provider in Identity Server. Here we will use another instance of identity server as the external IDP. The scenario will be extended from the previous scenario. 

At internal federation, we had 'Travelocity' webapp registered as a Service Provider in the IDP which decided the authenticity of user. Now we will federate the decision on the authenticity of the user to an external IDP. For the demonstration purposes I am using a tenant(named in the external IDP(

Configuring another IS instance to act as an external IDP (

  • Create a tenant named ‘’ and login with this tenant.
  • First we need to import the public certificate of the internal IS into tenant key store, which is paired with the private key used to sign the SAML Request. This time it is 'wso2carbon'.
  • Configure the internal IS as a service provider here. This is because now the SAML request is to be sent to this IS by the internal IS, we configured before.
  • Note that ‘Assertion Consumer URL’ is pointed to ‘https://localhost:9443/commonauth’ of the internal IS. Also note the certificate alias we have selected to use at SAML Request signature validation. This is the one that we imported here.

Configure Internal IS to federate SSO requests from Travelocity webapp to the external IDP

In the internal IS, we need to configure it to make use of the external IDP we just configured.
  • Create a Identity Provider as below. 
  • Upload the public certificate we can download from the external IDP, tenant keystore. This is to validate the signatures of SAML Response and Assertions that will be sent to this internal IS from the external IS.

We have to make some additional changes in the service provider configuration for Travelocity webapp as well. 
  • In the drop down list of federated authenticators select the identity provider we just configured.

There is one more addition we have to do as following to meet the requirement of audience restriction validation in SAML SSO scenario. This is not a requirement for federation, but for API access. The value we give here for audience is the OAuth token endpoint, which we will consume to exchange the SAML token for an OAuth token.

Now we are in a position to test the external federation scenario with Travelocity webapp sample. After hosting it in a tomcat server, hit the URL, ‘http://localhost:8080/’, which will take us to a page as below. Click on the link to login with SAML.

This will take us to following screen. Note the page is from our external IDP (, where we can enter credentials of a user in this IDP to get successfully authenticated. If our external authenticator was Google this will be a page from Google, submitted to enter the credentials.

After successful authentication, following screen will be shown.

Now the external federated SAML scenario is completed.

3. API Access leveraging the federation

To achieve this we need following configurations present at Webapp side.
  • Register an application in API-M store, subscribe to some APIs, provide the generated client id and client secret values in file of the sample webapp.
  • Point SAML.OAuth2TokenEndpoint=https://localhost:9445/oauth2/token to OAuthtoken endpoint of API-M.
  • Import the public certificate of internal IS, to the  keystore used by webapp. The given alias value should be provided at ‘’ in file.

IDP Configuration at API-M

  • Configure ‘host name’ and ‘mgt host name’ in APIM_HOME/repository/conf/carbon.xml 
  • Login as super admin and add an identity provider as following.

  • Following fields needs to be filled. Note that we have imported the public certificate of the internal IS here, so that we can validate it’s SAML token.
  • API-M is not aware of the federation happening at the internal IS node.

  • When configuring the federated authenticator, we should note that Identity Provider entity id should be as same as the issuer of the SAML Response coming to API-M, to exchange for an OAuth token. SSO URL, is the redirect URL for internal IS.

  • Once these configurations are done, we can test the end-to-end scenario. Now from the page we left at ‘Travelocity’ webapp, if we click on the link ‘Request OAuth2 Access Token’ following page will appear. It is showing the details of the OAuth token, it received in exchange to the provided SAML token.

Now we can use this access token at webapp side to consume any APIs we got subscribed to.

Hope this helps. We can expand and customize this scenario in several ways according to requirements, with options provided with federation, provisioning and extension points. Will discuss those in a latter post.


Wednesday, September 10, 2014

How to write a Custom SAML SSO Assertion Signer for WSO2 Identity Server

This is the 3rd post I am writing to explain the use of extension points in WSO2 Identity Server. WSO2 Identity Server has so many such extension points which are easily configurable and arm the server with lot of flexibility. With this, we can support so many domain specific requirements with minimum efforts.
  • Now this third post deals with writing a custom SAML SSO Assertion signer.

What we can customize?

  • Credentials used to sign the SAML Assertion (The private key)
  • Signing Algorithm
  • This sample can be extended to customize how we sign the SAML Response and validate the signature as well.


We have to write a class extending 
  • The class '' or
  • The interface ''
Needs to override the following method in our case to customize how we sign the assertion,


    public Assertion doSetSignature(Assertion assertion, String signatureAlgorithm, X509Credential cred) throws IdentityException {

        try {
            //override the credentials with our desired one
            cred = getRequiredCredentials();
            Signature signature = (Signature) buildXMLObject(Signature.DEFAULT_ELEMENT_NAME);

            try {
                KeyInfo keyInfo = (KeyInfo) buildXMLObject(KeyInfo.DEFAULT_ELEMENT_NAME);
                X509Data data = (X509Data) buildXMLObject(X509Data.DEFAULT_ELEMENT_NAME);
                X509Certificate cert = (X509Certificate) buildXMLObject(X509Certificate.DEFAULT_ELEMENT_NAME);

                String value =
            } catch (CertificateEncodingException e) {
                throw new IdentityException("errorGettingCert");


            List<Signature> signatureList = new ArrayList<Signature>();

            // Marshall and Sign
            MarshallerFactory marshallerFactory = org.opensaml.xml.Configuration
            Marshaller marshaller = marshallerFactory.getMarshaller(assertion);


            return assertion;
        } catch (Exception e) {
            throw new IdentityException("Error while signing the SAML Response message.", e);

Finally we have to update the identity.xml() as below with the above custom class we write overriding the methods.

and place the compiled package with the above class at 'IS_HOME/repository/components/lib' 

Now if we restart the server and run the SAML SSO scenario, the SAML SSO Assertion will be signed in the way we defined at the custom class we wrote.

Here you can find a complete sample code to customize the assertion signing procedure.

Hope this helps..