Easy way to Customize the SAML2 federated authenticator in WSO2IS
SAML2 federated authenticator provides an extension point called “SAML2SSOManager” that you can customize the implementation of it. This is a simple guide that helps you to understand how to customize it.
First of all before customizing federated WSO2IS SAML2SSOManager let me explain the real idea behind the Identity federation.Identity federation is a mechanism that allows authentication across different enterprises in different trust domains based on a trust factor.WSO2IS can federate the user authentication to another external identity provider where a service provider initiate the communication by sending an authentication request (i.e SAML request) to WSO2IS so WSO2IS can redirect the user to an external identity provider so the user would login to the external identity provider with an existing user account by entering user credentials .The external identity provider validate and authenticate the user and notify the WSO2IS with the logged in user’s claims, then the WSO2IS can respond to the service provider with the authentication response (i.e SAML response) along with user claims that are requested by the service provider.Finally service provider can authorize the user after reviewing the user claims which was sent by the identity provider.
In this article I will select another WSO2 Identity server as the federated identity provider.You can easily register another WSO2IS in a WSO2IS as a federated identity provider with SAML SSO and a sample web application called travelocity app as the service provider by referring this article.
Here we’ll develop a custom SAML2SSOManager to customize the authentication request(saml request) which will be sent from the Identity provider to Federated identity provider by adding default authentication context under <RequestedAuthnContext> element if authentication context not present in the service provider saml request but if Authentication Context is present in the SAML request as a query parameter value, we will extract it from that and set it as an authentication context.
Not clear what authentication context is ? Authentication context indicates how a user authenticated at an Identity Provider. The Identity Provider includes the authentication context in an assertion at the request of a Service Provider or based on a configuration at the Identity Provider. A Service Provider can get the required information about the authentication process.
The following steps explain how you can write a custom SAML2SSOManager by extending the DefaultSAML2SSOManager class and how this custom SAML2SSOManager can be registered.
Let’s get our hands on creating a new maven project.
- Create a new maven project by including the below repositories and dependencies.
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.wso2.carbon.identity</groupId>
<artifactId>org.wso2.carbon.identity.custom.samlsso.manager</artifactId>
<version>1.0.0</version>
<name>Outbound SAML manager to support default authentication context classes</name>
<packaging>jar</packaging>
<repositories>
<repository>
<id>wso2-nexus</id>
<name>WSO2 internal Repository</name>
<url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
<releases>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>ignore</checksumPolicy>
</releases>
</repository>
<repository>
<id>wso2.releases</id>
<name>WSO2 internal Repository</name>
<url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
<releases>
<enabled>true</enabled>
<updatePolicy>daily</updatePolicy>
<checksumPolicy>ignore</checksumPolicy>
</releases>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.wso2.carbon.identity.outbound.auth.saml2</groupId>
<artifactId>org.wso2.carbon.identity.application.authenticator.samlsso</artifactId>
<version>5.1.5</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>8</source>
<target>8</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
2.Write a custom SAML2SSOManager by extending DefaultSAML2SSOManager
Click to see the sample custom SAML2SSOManager class here.
3.This custom SAML2SSOManager class can be registered in the application-authentication.xml file located in the <IS_HOME>/repository/conf/identity/ directory under the SAMLSSOAuthenticator config .Default authentication contexts and query parameter key value can be added as Parameter tags as shown below.
<AuthenticatorConfig name="SAMLSSOAuthenticator" enabled="true">
<!--Parameter name="SignAuth2SAMLUsingSuperTenant">true</Parameter-->
<Parameter name="SAML2SSOManager">org.wso2.carbon.identity.custom.samlsso.manager.AuthContextSAMLSSOManager</Parameter>
<Parameter name="SAMLSSOParamKey">authContextClass</Parameter>
<Parameter name="SAMLSSODefaultAuthnContextClasses">urn:be:fedict:iam:fas:citizen:Level400,urn:be:fedict:iam:fas:enterprise:Level400</Parameter>
</AuthenticatorConfig>
4.Build the project using maven.
5.Copy the .jar file org.wso2.carbon.identity.custom.samlsso.manager-1.0.0.jar
inside <IS_HOME>/repository/components/lib
folder
6.Start WSO2 Identity Server.
Now you know how to customize the WSO2 SAML2SSOManager :)
Want to learn more ?
Refer Authentication Context for the OASISSecurity Assertion Markup Language(SAML) V2.0 where they have explained everything you want to know about Authentication Context and If you are interested in reading more about identity federation make sure to check out the WSO2 documentation about Identity Federation and leave your feedback about this blog.