Using SSO with Web Applications

Single Sign On or SSO is a popular way of managing a log-in session throughout several applications or programs. It allows users to access multiple applications through a single log-in session, without having to enter credentials multiple times. WSO2 provides the capability of enabling SSO for user applications via WSO2 Identity Server.

From the WSO2 Application Server perspective, SSO can be configured within multiple applications deployed in WSO2 AS, using WSO2 IS. According to normal practice, application developers need to include certain code in the application in order to enable SSO. The use of the SSO Valve reduces this complexity and allows application developers to easily enable SSO for a web application deployed in WSO2 AS. With the SSO Valve, SSO can be enabled for applications with minimal configuration changes.

Configuring the servers (WSO2 AS and WSO2 IS)

The following configurations should be done in WSO2 AS:

Open the sso-sp-config.properties file, which is stored in the <AS_HOME>/repository/conf/security/ directory and update the "IdPEntityId". By default, this value is set to the localhost as shown below.
```
#IdPEntityId
SAML2.IdPEntityId=localhost
```
The sso-sp-config.properties file is the global configuration file for generic SSO configurations in WSO2 AS. See the descriptions of all the properties that you can configure in this file from here.
Register the SSO valve in WSO2 AS by appending the following in the <AS_HOME>/repository/conf/tomcat/catalina-server.xml file. Be sure to add this entry just after "CarbonStuckThreadDetectionValve".
```
<Valve className="org.wso2.carbon.webapp.mgt.sso.SAMLSSOValve"/>
```
The SSO valve is capable of handling Single Log Out redirections to the Assertion Consumer URL of the web application by redirecting to the root context of the web app. This capability can be turned on/off using the "handleConsumerURLAfterSLO" property in the sso-sp-config.properties file:
```
#Enable this if needed to automatically redirect from acs page after SLO
handleConsumerURLAfterSLO=true
```

The following configurations should be done in WSO2 IS:

The respective SSO Service Providers need to be registered in WSO2 Identity Server for each web application.

Note that the parameters/values defined in the sso-sp-config.properties file of WSO2 AS should correspond to the parameters defined for the service providers registered in WSO2 IS.
1. Since the valve automatically determines the SSO issuer-id, the service provider issuer-id needs to be in the following format:
  For super tenant web applications: issuer-id = webapp-name
  For tenant web applications: issuer-id = t_tenant-name_webapp-name
  
  Examples:
2. The 'Assertion Consumer URL' for the service providers should be set to the same value specified in the sso-sp-config.properties file. Shown below is the URL given in the default sso-sp-config.properties file. The format of the URL should be as follows: https://{ip}:{port}/{app-name}/acs
```
#The URL of the SAML 2.0 Assertion Consumer
#SAML.ConsumerUrl=http://localhost:8080/avis.com/home.jsp
```
Update "IdentityProviderURL" and “EntityId” in <IS_HOME>/repository/conf/identity.xml with the correct IS hostname.

Note that the “EntityId” in <IS_HOME>/repository/conf/identity.xml should be the same as the “SAML2.IdPEntityId” defined in <AS_HOME>/repository/conf/security/sso-sp-config.properties.
In WSO2 IS, update the resident IDP "Entity Id" with the same value as the "EntityId". Shown below is the default configuration.

Configuring the web applications

You must enable SSO for web applications by adding the following context parameter to the web application's web.xml:

<context-param>
        <param-name>enable.saml2.sso</param-name>
        <param-value>true</param-value>
</context-param>

Configuring SSO valve to access web applications in multiple tenants

When the SSO valve is engaged, you can allow tenants to log in to web applications that are deployed for other tenants. For example, consider that there are two tenants: "a.com" and "b.com". Tenant a.com deploys an application named foo.war, which needs to be accessed by tenant b.com. In order to allow this, the following configurations should be in place:

Tenant b.com needs to create an SP (service provider) in WSO2 IS similar to the SP created by a.com. Note that the SP configurations for b.com should have the same issuer id, etc. In this case issuer id for b.com would be: t_a.com_foo.
If SSO request validation is required (this is optional), tenant b.com needs to import tenant a.com's public key into tenant a.com's keystore. Then in the aforementioned SP configuration for the foo app, you can enable the "Enable Signature Validation in Authentication Requests and Logout Requests" option and select the certificate of a.com. See the topic on setting up keystores for more information on keystores.

Log in to web applications using SSO

Once you have the above configurations in place, you can simply deploy your web applications in WSO2 AS. Note that WSO2 IS should be started and running in parallel to AS for this feature to work. You will now be able to log in to the web application deployed on WSO2 AS using SSO. Try this sample for a demonstration.