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.

Overview




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.

Pre-requisites

WSO2 Identity Server -5.0.0 - http://wso2.com/products/identity-server
WSO2 API Manager 1.7.0 - http://wso2.com/products/api-manager
                             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 - lanka.com
2. WSO2 Identity Server -5.0.0 - Internal IDP - Offset 1 - Port 9444 
                 Tenant - lux.org
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(lanka.com) to the keystore of webapp 'travelocity.jks'. 
Please note the following configurations done in travelocity.properties file found inside webapp at '/travelocity.com/WEB-INF/classes/travelocity.properties'.


EnableSAML2Grant=true

#A unique identifier for this SAML 2.0 Service Provider application
SAML.IssuerID=travelocity.com@lanka.com

#The URL of the SAML 2.0 Identity Provider
SAML.IdPUrl=https://localhost:9443/samlsso

#Password of the KeyStore for SAML and OpenID
KeyStorePassword=travelocity

#Alias of the IdP's public certificate
SAML.IdPCertAlias=lanka.com

#Alias of the SP's private key 
SAML.PrivateKeyAlias=travelocity

#Private key password to retrieve the private key used to sign 
#AuthnRequest and LogoutRequest messages
SAML.PrivateKeyPassword=travelocity

#OAuth2 token endpoint URL
SAML.OAuth2TokenEndpoint=https://localhost:9445/oauth2/token

#OAuth2 Client ID
SAML.OAuth2ClientID=FxuhFBEcX5P1wjtqPqigJ0OVP5ca

#OAuth2 Client Secret
SAML.OAuth2ClientSecret=2eqfI11Y9dRZaiijbAK3dfJFNRMa

1. SSO Setup with Internal IDP

  • Login as tenant admin - <admin>@lanka.com
  • 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.
keystore1.png













  • 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.

keystore1.png


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 lanka.com> -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 lux.org) in the external IDP(idp.lanka.com).

Configuring another IS instance to act as an external IDP (idp.lanka.com)

  • Create a tenant named ‘lux.org’ 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/travelocity.com/index.jsp’, 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 (idp.lanka.com), 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 travelocity.properties 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 ‘SAML.IdPCertAlias=lanka.com’ in travelocity.properties 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.

Cheers!

Popular posts from this blog

Signing SOAP Messages - Generation of Enveloped XML Signatures

Image
Digital signing is a widely used mechanism to make digital contents authentic. By producing a digital signature for some content, we can let another party capable of validating that content. It can provide a guarantee that, is not altered after we signed it, with this validation. With this sample I am to share how to generate the a signature for SOAP envelope. But of course this is valid for any other content signing as well. Here, I will sign The SOAP envelope itself An attachment  Place the signature inside SOAP header  With the placement of signature inside the SOAP header which is also signed by the signature, this becomes a demonstration of enveloped signature. I am using Apache Santuario library for signing. Following is the code segment I used. I have shared the complete sample here to to be downloaded . public static void main(String unused[]) throws Exception {         String keystoreType = "JKS";         Stri...
Read more

Tomcat JDBC Pool - Connection Leak - Catch the Culprit

Database connection leaks are something that can stay hidden unless paid specific attention and would come to the surface at the most critical stages at a peak time of the system. We would manually check if all the open connections have been closed properly. Then we have various code quality plugins that would scan and check for that. Still when the connections are passed through a complex structure of program both of these can miss a possible connection leak. Then at unit test or integration test levels, we can have checks to validate the counts in the connection pool to avoid this unfortunate situation, that would keep engineers busy at year-end, black Friday, etc. :) In the unfortunate case of hitting with a performance degrade or a total crash of the system which can be propagated via a JDBC connection leak, when we suspect a connection leak, how easily and quickly isolate the culprit. In the Tomcat connection pool, we can do this using 3 properties. removeAbandoned If a...
Read more

How to convert WSDL to Java

Image
Background Basically WSDL (Web Services Development Language) is an XML document used to describe or locate web services. WSDL stands for Web Services Description Language. The document describes a Web service. It specifies the location of the service and the operations that can be taken.  WSDL2Java is distributed with Axis2 package of Apache and need to set-up Axis2 to use this service. A  guide to set-up Axis2  can be found in apache organization documents .WSDL 2.0 is the currently using version. Obviously JDK should be properly installed too. Note: For the 3rd method you are not needed to set these things by yourself. The WSDL document includes server Java programs for Web services and generated classes using WSDL2Java feature includes client stubs, server skeletons and data types that can help in writing client side. The generated stub classes play a great role in distributed computing and if you are interested can read on  what are...
Read more