Configuring Federated Authentication with SAML SSO using two WSO2 Identity Servers

Federated Authentication Flow

Federated Authentication is a mechanism that allows authentication across different enterprises in different trust domains based on a trust factor. This facilitates the user with the advantage of using the same username and password for different platforms. For an introduction on SAML and SSO refer Let’s take a dive into the shallows of SAML.

There are various Federated Authenticators which are capable of connecting through SAML e.g. Google and Salesforce. But there were downfalls which I faced during testing. So, I’ve decided to write this article which guides you on how to use another WSO2 Identity Server as a Federated Authenticator.

As prerequisites you should have the below locally installed:

• Java Development Kit- To run the WSO2 Identity Sever you need JDK installed.
• Tomcat- Deploy the web apps and run them locally. You will most probably see the output of the process with the help of tomcat.

Before starting off, you will need two WSO2 Identity Servers installed locally.

Download and Extract

Official Site

• Download the WSO2 Identity Server from the official site here and proceed download with the Binary option from Installation Options.

Proceed to Download and then select Binary as the Installation Option (Highlighted in the picture)

• Extract the downloaded zip file to a preferred location.

GitHub Releases

• Download the WSO2 Identity Server from github releases here. After proceeding to the website select any release and download the first zip file which is usually indexed as wso2is-version-tag.zip.

Download the highlighted zip file (the first zip file under Assets)

• Extract the downloaded zip file to a preferred location.

Cloning the Repository

This method is probably the longest cause there is a set of lengthy tasks to be accomplished, since some of the users prefer this approach I thought of including this method too.

• Clone the repository to your local machine.

Enter the highlighted command to clone the repository

• Open it using a preferred IDE of yours. I’m using IntelliJ Community Edition.

Opened Project at IntelliJ

• Open a new terminal inside the IDE and type the command

mvn clean install

This command would take a bit of time to execute depending on the specifications of your machine. If any errors pop out during the execution then, run command

mvn clean install -Dmaven-test-skip=true

This command will skip the tests and do the build so, would result in a lesser execution time. If this command results in errors too then, please feel for me and try the process from any of the two methods mentioned above.

Opening a terminal and running the command “mvn clean install”

• Navigate to the PRODUCT_HOME-> modules-> distribution-> target where you will find a zip file named wso2is-version-tag-SNAPSHOT.zip and extract the zip file to a preferred location.

Setup Servers

As I’ve said that two identity servers are required but we only downloaded one identity server. What we can do is:

• Copy the extracted folder to another location or
• Extract the zip file again to another location (preferred) or same location and change the name of the folder.

Identity Server Version 5.9.0-m1 and below

Then, open one of folders from the two identity servers and locate the file carbon.xml at PRODUCT_HOME->repository-> conf and change the tag

<Offset>0</Offset> to <Offset>1</Offset>

Changed Offset value highlighted in yellow (location and file name highlighted in red)

Identity Server Version 5.9.0-m2 and above

Then, open one of folders from the two identity servers and locate the file deployment.toml at PRODUCT_HOME->repository-> conf and add the line

offset = 1 under [server]

Added offset value highlighted in yellow (location and file name highlighted in red)

And then save the changed file. What this would do is change the port of one of the identity servers from 9443 to 9444 cause if both the servers start running on the same port (9443) then there would be a conflict between the two servers. For more information refer Official Documentation.

From now on the server for which the Offset was not changed is Primary-Identity-Server and the changed one is the Secondary-Identity-Server.

Repeat the two steps mentioned below to start the primary and secondary servers:

• Navigate to PRODUCT_HOME-> bin.
• Open a terminal inside the directory and type the command

./wso2server.sh(on Linux/Mac OS) or wso2server.bat(on Windows)

Running the command ”./wso2server.sh” at directory PRODUCT_HOME-> bin

Primary-Identity-Server accessible through: https://localhost:9443/carbon

Secondary-Identity-Server accessible through: https://localhost:9444/carbon

Type admin as the username and password to gain access to the management console.

Process

Diagram representing the process mentioned below

The process can be explained using four basic steps:

1. Append a web application to Tomcat.
2. Configure a Service Provider in the Primary-Identity-Server.
3. Configure a Federated Identity Provider (Secondary-Identity-Server) in the Primary-Identity-Server.
4. Configure a Service Provider (Primary-Identity-Server) in the Secondary-Identity-Server.

Append a web application to Tomcat

Copy the web application folder or the war file to TOMCAT_HOME-> webapps

War file copied at directory TOMCAT_HOME-> webapps

Go to TOMCAT_HOME->bin and open a terminal inside the directory and type the command

sh catalina.sh start

to deploy the web application and start the server.

Tomcat server started with the command “sh catalina.sh start” at directory TOMCAT_HOME-> bin

Configure a Service Provider in the Primary-Identity-Server

Login to Primary-Identity-Server accessible through: https://localhost:9443/carbon. Use admin as the username and password and log in to the management console.

Click on the Main tab at the left corner of the screen. Then from the Identity Tab navigate to Service Providers-> Add, enter a Service Provider Name (I have entered it as saml2-web-app-pickup-manager.com) and click Register.

Appending a new Service Provider at Primary-Identity-Server

After the redirection to Service Providers window, expand the Inbound Authentication Configuration and then further expand the SAML2 Web SSO Configuration and click on Configure.

Locating SAML2 Web SSO Configuration

After the redirection to Register New Service Provider window,

1. Provide the Issuer (I have provided it as saml2-web-app-pickup-manager.com).
2. Provide the Assertion Consumer URLs (I have provided it as http://localhost.com:8080/saml2-web-app-pickup-manager.com/home.jsp) and Add the ACS URL.
3. Tick- Enable Response Signing, Enable Signature Validation in Authentication Requests and Logout Requests.
4. Keep other fields as default and click Update button located at the bottom.

Configuring SAML2 Web SSO for the Service Provider at the Primary-Identity-Server

Configure a Federated Identity Provider (Secondary-Identity-Server) in the Primary-Identity-Server

Continue with the Primary-Identity-Provider.

Click on the Main tab at the left corner of the screen. Then from the Identity Tab navigate to Identity Providers-> Add, enter a Identity Provider Name (I have provided it as Secondary for convenience, please put this in cause it will make your life easier).

Appending a new Identity Provider at Primary-Identity-Server

Expand the Federated Authenticators and then select SAML2 Web SSO Configuration.

1. Tick on- Enable SAML2 Web SSO and Default at the top.
2. Provide the Service Provider Entity ID as Primary.
3. Provide the Identity Provider Entity ID as Secondary.
4. Provide the SSO URL as https://localhost:9444/samlsso.
5. Tick on- Enable Logout.
6. Keep other fields as default and click Register button located at the bottom.

Configuring Federated Authentication using SAML2 Web SSO for the Identity Provider at Primary-Identity-Server

Go back to the created service provider at the Primary-Identity-Server by clicking on the Main tab at the left corner of the screen. Then from the Identity Tab navigate to Service Providers-> List. Search for the Service Provider you created and click Edit. Expand the Local & Outbound Authentication Configuration.

1. Select Authentication Type as Federated Authentication.
2. Select Secondary from the drop down list and click Update button located at the bottom.

Configuring Local & Outbound Authentication for the Service Provider at Primary-Identity-Server to use Federated Authentication using the recently created Identity Provider

Configure a Service Provider (Primary-Identity-Server) in the Secondary-Identity-Server

Login to Secondary-Identity-Server accessible through: https://localhost:9444/carbon. Use admin as the username and password and log in to the management console.

Click on the Main tab at the left corner of the screen. Then from the Identity Tab navigate to Service Providers-> Add, enter a Service Provider Name (I have entered it as Primary) and click Register.

Appending a new Service Provider at Secondary-Identity-Server

After the redirection to Service Providers window, expand the Inbound Authentication Configuration and then further expand the SAML2 Web SSO Configuration and click on Configure.

Locating SAML2 Web SSO Configuration

After the redirection to Register New Service Provider window,

1. Provide the Issuer as Primary. (This should be same as the Service Provider Entity Id of the IDP in the Primary IS)
2. Provide the Assertion Consumer URLs as https://localhost:9443/commonauth and click Add.
3. Tick- Enable Single Logout, Enable Idp Initiated SSO and Enable Idp Initiated SLO.
4. Keep other fields as default and click Update.

Configuring SAML2 Web SSO for the Service Provider at the Secondary-Identity-Server

Now you have successfully configured the process. To test the process what you can do is access the Service Provider Assertion Consumer URL of the Service Provider which you have created in the Primary-Identity-Server (for me it is http://localhost.com:8080/saml2-web-app-pickup-manager.com/home.jsp).

View after accessing the Assertion Consumer URL

View after login button is clicked

View after successful authentication

If you have another web-app deployed you could access it straight away without providing credentials, this is what Single-Sign-On is and this occurs because you already have a session created inside the browser. Also if you logout from one you will be logged out from both the web apps and redirected to the default logout page.

Hope this would help you in the process of creating a federated authenticator using SAML SSO if there is a downfall on Google or Salesforce while using the WSO2 Identity Server.

More on WSO2 Identity Server concepts and implementations to be released later so, till then it’s a goodbye from me!!

References:

• WSO2 Documentation