Configure WSO2 Identity Server as SAML2 SSO IDP

WSO2 Identity Server is one of the powerful open source identity management solution. It can act as an SAML2 SSO IDP.  You can use Identity Server to integrate with different applications to achieve seamless user login in your enterprise. You can easily register your service provider applications using WSO2 Identity Server management console. Lets tryout SAML2 SSO sample that is shipped with WSO2 Identity Sever.

Setup SAML2 SSO Web Application.

Step 1. Check out the source from the repository location which contains the samples. You can find the latest sample from here

svn co https://svn.wso2.org/repos/wso2/carbon/platform/branches/turing/products/is/5.0.0/modules/samples/sso/

Step 2. Go to <HOME>/sso/SSOAgentSample directory

Step 3. Replace the exiting pom.xml file with this pom.xml file.  Because you can not build the sample with existing pom.xml file available in the WSO2 SVN until you build the whole platform.

Step 4. Build the project using Maven  3.0.X.

After successfully building the sample, A .war file named travelocity.com can be found inside the <HOME>/sso/SSOAgentSample/target folder.

Step 5. Deploy this sample web app on a web container. To do this, use the Apache Tomcat server.

Since sample web application is written based on Servlet 3.0 it needs to be deployed on Tomcat 7.x.

Use the following steps to deploy the web app in the web container:

a) Stop Apache Tomcat server if it is already running.

b) Copy  travelocity.war file to the <TOMCAT_HOME>/webapps folder.

c) Start Apache Tomcat server.

Step 6.  Configure SAML2 SSO parameters in the web application

The travelocity.properties file, which can be found inside the travelocity.com/WEB-INF/classes folder, can be used to change the properties like issuerID, consumer url and IdP url. This sample web application uses default values and you can override them by using the property file.  As an example,

  • A unique identifier for this SAML 2.0 Service Provider application :
SAML.IssuerID=travelocity.com
  • The URL of the SAML 2.0 Assertion Consumer :
 SAML.ConsumerUrl=http://localhost:8080/travelocity.com/samlsso-home.jsp
  • The URL of the SAML 2.0 Identity Provider :
SAML.IdPUrl=https://localhost:9443/samlsso

Once you do any edit to this file, You may need to restart the Tomcat server.  Now Sample web application is successfully deployed in the web container;  The next step is to configure WSO2 Identity Server as an identity provider.

Configuring SAML2 SSO IDP

Step 1. Login to management console and Add new  service provider

Step 2. Configure inbound  authentication for service provider.    Web application is going to communicate with Identity Server using SAML2 SSO web browser profile.  Therefore we need to register web application as SAML2 SSO service provider.

Step 3. Following are the service provider configuration options

 

Issuer :  This is the entity id for SAML2 service provider.

Assertion Consumer URL:  ACS url of the service provider. IDP redirects the SAML2 response to this ACS url.  But If SAML2 request is signed and SAML2 request contains ACS url,  Identity Server would honor to ACS url of SAML2 request. This value should be same as the SAML.ConsumerUrl value mentioned inside the travelocity.com/WEB-INF/classes/travelocity.properties file.

NameID format:  SP and IdP usually communicate each other about a subject. That subject should be identified through a Name-Identifier (NameID) , which should be in some format so that It is easy for the other party to identify it based on the format.  There are some formats that are defined by SAML2 specification. Default format is used by IDP is urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Use fully qualified username in the NameID :   Fully qualified username means that the user name with user store domain or tenant domain.

If authenticated user is from secondary user store username would be set as  {user store domain}/{user name}.

If authenticated user is from tenant then username would be set as  {user name}@{tenant domain}

If authenticated user is from secondary user store and from tenant username would be set as  {user store domain}/{user name}@{tenant domain}

If you do not enable this,  it would be just the authenticating username would be returned.

Define Claim Uri for NameID :  If you want to define an any other user attribute as the NameID. You want to select the check box and define the claim uri that you need to use for it.

Enable Response Signing :  SAML2 Response must be signed or not

Enable Assertion Signing : SAML2 Assertion must be signed or not

Enable Signature Validation in Authentication Requests and Logout Requests : Whether to IDP must validate the signature of SAML2 auth request and SAML2 logout request that are sent by service provider.

Enable Assertion Encryption : SAML2 Assertion must be encrypted or not

Certificate Alias :  Select the certificate that is used to validate signature of SAML2 requests and cretificate that is used to generate encryption. Basically the Service provider’s certificate must be selected.

Enable Single Logout : Whether single logout must be enabled or not. Once single logout is enabled, IDP would send logout requests to all service providers. Basically,  IDP acts according to the single logout profile. If service provider supports a different url for logout, You can define different url for logout  If not,  IDP uses the ACS url.  More details, can be found here

Enable Attribute Profile :  Identity Server supports for basic attribute profile that IDP can include user’s attributes in the SAML Assertions as attribute statement.  We can define the claims that must be included under service provider claim configurations… I will go through it later…  Also, Once you select the check box of  “Include Attributes in the Response Always”, IDP always includes the attribute values related to selected claims in to the SAML Attribute statement.

Enable Audience Restriction : You can define multiple audience in the SAML Assertion.  Configured audiences would be added in to the SAML2 Assertion.

Enable IdP Initiated SSO  : Enable IDP initiated SSO.  When this is enabled,  service provider does not want to send SAML2 request.

Once IDP is registered, Consumer index is generate for service provider.   If you do not select to include attribute in SAML2 assertion always, Then service provider must send this index in the SAML request that is sent by the service provider.  You can find more details from here

 

Service Provider Claim Mapping

 

Following steps are not required.  But it is needed, if you want to send the authenticated users attributes in the SAML2 Assertion.

Step 4. Configure claim mapping for service provider.

You can select the claims that must be sent to the service provider.   If you just want to sent them as claim uris  (as WSO2 uris), Then please select  “Use Local Claim dialect“.  You can add them by clicking on  “Add Claim URI”

Please note that these claims would be added in to the SAML2 Assertion, only if you tick on “Enable Attribute Profile” in SAML2 Issuer configurations.

 

 

 

If you trace the SAML2 Assertion, you would found as these claims in attribute statement as following.

<saml2:AttributeStatement>
 <saml2:Attribute Name="http://wso2.org/claims/role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
 <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" >admin,Internal/everyone</saml2:AttributeValue>
 </saml2:Attribute>
 <saml2:Attribute Name="http://wso2.org/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
 <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">[email protected]</saml2:AttributeValue>
 </saml2:Attribute>
 </saml2:AttributeStatement>

 

If you want to define new uris for the attributes that are sent (Actually for the “Name” value in the “Attribute” element), You can define any values for them and map these values with WSO2 Claim uris.  Say, you want to sent email address of the user  as “http://soasecurity.org/claims/emailaddress”  claim uri…   you can define it and  map it in to “http://wso2.org/claims/emailaddress” .   Uri may be depend on how your SP is reading it. Therefore,  you may need to map claims uris in to what SP is preferred.

You need to select “Define Custom Claim Dialect” and define the claim mapping.  Please make sure to mark them as “Requested Claim”

 

 

Then your attribute statement would be changed as following..

<saml2:AttributeStatement>
 <saml2:Attribute Name="http://soasecurity.org/claims/role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
 <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string" >admin,Internal/everyone</saml2:AttributeValue>
 </saml2:Attribute>
 <saml2:Attribute Name="http://soasecurity.org/claims/emailaddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
 <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">[email protected]</saml2:AttributeValue>
 </saml2:Attribute>
 </saml2:AttributeStatement>

 

 User Name for SAML2 Assertion

 

You can trace username for NameID value of the SAML2 Assertion.

<saml2:Subject>
	<saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">admin</saml2:NameID>
</saml2:Subject>

By default,  Username would be the value that you are providing for authentication.  However,  username would be changed in multiple user store and tenant scenarios as explained in “Use fully qualified username in the NameID :”  config.

  • If authenticated user is from secondary user store username would be set as  {user store domain}/{user name}.
  • If authenticated user is from tenant then username would be set as  {user name}@{tenant domain}
  • If authenticated user is from secondary user store and from tenant username would be set as  {user store domain}/{user name}@{tenant domain}

However,  if you like to select any other user’s attribute to add in to the NameID, you can do it as well.  Under claim configuration, you can find a configuration called “Subject Claim URI:”.  Here you can select a desired claim uri that you need to select.  Then user’s attribute value of selected claim uri would be added as NameID.

Note: please make sure, WSO2IS may complain some error,  if you configure email value as “Subject Claim URI:”. If you found such issue,  you need to configure “EnableEmailUserName”  property  as described in here

Authentication for end users

 

By default,  end users can provide the username/password and authenticated with WSO2IS.  If you need to extend that capabilities,  you can do it as well.  More details can be found on my federated authentication blogs

Step 5. Configure outbound authentication.  Here we just keep it as default configuration. It means IDP authenticate the users with username/password by validating with IDP’s user store.

Step 6. Update service provider details.

Step 7.  Now you are done.  When you try to login to web application.  You would be directed to Identity Server SAML2 SSO login page.  Once you provide the valid credentials, You would be login to the web application.  You can see the attribute values that are received via SAML token.   You can trace the SAML request and SAML respose messages.

Thanks for reading….!!!