SECURITY INTERNAL . COM: Tenant Domains Dropdown Feature in WSO2 Identity Server 5.1.0

In WSO2 Identity Server, when you have a Service Provider where you allow users from different tenants to get authenticated (SAAS enabled Service Provider), The users have to enter their fully qualified username in the login page so that Identity Server can recognize from which tenant this user should get authenticated. For example, if there is a user in wso2.com tenant with the username tharindu, in the login page, that user should enter the username as [email protected]. However Identity Server has a feature where it can display all active tenants in a dropdown in the login page where the user can select the tenant he/she belongs and just enter the username without the @tenant-domain in the username textbox in the login page. For Identity Server 5.0.0, I have previously written the blog post [1] that provides step by step guide for setting up this feature. If you are new to this feature, you can follow it and get the basic idea about the feature.

In this blog post, I will provide the steps needed for setting up this feature in Identity Server 5.1.0 version. Here I am providing the steps comparing how it was done in 5.0.0 version so that if you have already configured this previously in 5.0.0, you can see what has been changed when comes to 5.1.0.

Configuration Steps

This feature uses Mutual SSL (Certificate Based Authentication) and for that, we need to set the clientAuth property to want in <IS_5.1.0_HOME>/repository/conf/tomcat/catalina-server.xml file. In IS 5.1.0, this is by default set (clientAuth="want") so you do not need to make any change when you use a fresh 5.1.0 pack.

In order to use Mutual SSL, in IS 5.0.0, we had to copy the org.wso2.carbon.identity.authenticator.mutualssl jar file to the dropins directory of IS. However with IS 5.1.0, org.wso2.carbon.identity.authenticator.mutualssl_5.0.7.jar file is by default shipped in <IS_5.1.0_HOME>/repository/components/plugins so you do not need to manually copy this.

Next step is to enable the Mutual SSL Authenticator. For that you need to add following configuration in <IS_5.1.0_HOME>/repository/conf/security/authenticators.xml file. This configuration is there by default in 5.1.0, but you have to enable this by adding disabled=”false” attribute.

<Parameter name="UsernameHeader">UserName</Parameter>

<Parameter name="WhiteListEnabled">false</Parameter>

</Config>

</Authenticator>

Next step is to add following configuration to the application-authentication.xml file. In IS 5.0.0, this file was in <IS_5.0.0_HOME>/repository/conf/security/ but in 5.1.0, it is in <IS_5.1.0_HOME>/repository/conf/identity/ .

<TenantDataListenerURLs> <TenantDataListenerURL>/authenticationendpoint/tenantlistrefresher.do</TenantDataListenerURL>

</TenantDataListenerURLs>

If you are hosting the authenticationendpoint.war webapp outside Identity Server (i.e in a different tomcat or in WSO2 application server), then you can add the full URL to TenantDataListenerURL value. If you have a cluster of IS nodes, then for each node you can repeat the TenantDataListenerURL tag and provide the full URL to other nodes.

In 5.0.0 pack, the properties file related to this feature was TenantConfig.properties, but in 5.1.0 pack it is EndpointConfig.properties which is by default there in <IS_5.1.0_HOME>/repository/conf/identity/EndpointConfig.properties location.

tenantListEnabled=true	This property controls whether this feature is enabled or not. Set this to true for enabling the feature.
mutual.ssl.username=admin	When mutual ssl authentication happens, Identity Server needs to know whether this request (retrieving tenants from TenantMgtAdminService) is authorized. For that we need to put a name of a user who has the permission Super Admin Permissions > Manage > Monitor > Tenants > List
identity.server.serviceURL=/services/	This property is there for building the URL for TenantMgtAdminService. You can keep the value as /services/ and let Identity Server build the URL.
client.keyStore=./repository/resources/security/wso2carbon.jks	This is the keystore used in this feature. If you host authenticationendpoint.war within IS itself, you can provide the relative path to the keystore of IS itself.
Carbon.Security.KeyStore.Password=wso2carbon	This is the password for the keystore.
client.trustStore=./repository/resources/security/client-truststore.jks	This is the path of the truststore used for this feature.
Carbon.Security.TrustStore.Password=wso2carbon	This is the password of the truststore.

If your authenticationendpoint webapp is hosted within Identity Server (IS_HOME/repository/deployment/server/webapps), then you can enable secure vault to secure the keystore and truststore passwords in this property file so it does not store the plain text password in this file. It needs some additional steps and I will cover them in a separate post.

If you are hosting the autheticationendpoint.war webapp outside the Identity Server (i.e in a different tomcat or WSO2 Application Server), then you cannot use the <IS_5.1.0_HOME>/repository/conf/identity/EndpointConfig.properties file as the webapp does not have access to this file. In such case, the same property file is available inside the webapp (authenticationendpoint/WEB-INF/classes/EndpointConfig.properties) Where you can set the properties in that file. In that case you have to provide the full URL to Identity Server’s admin services endpoint in identity.server.serviceURL property (i.e identity.server.serviceURL=https://<ip>:<port>/services ).

However If you are hosting the authenticationendpoint.war webapp outside the Identity Server, then you need to copy the org.wso2.carbon.identity.application.authentication.endpoint.util-5.0.7.jar file into authenticationendpoint/WEB-INF/lib . You can find this jar file in <IS_5.1.0_HOME>/repository/components/plugins folder, or else can download from [2].

For Identity Server 5.1.0, the security patch WSO2-CARBON-PATCH-4.4.0-0073 is issued for this feature and if you are using IS 5.1.0, make sure you apply this patch to your environment. You can download this patch from [3].

Note :

If you are applying the WSO2-CARBON-PATCH-4.4.0-0073 security patch and hosting the authenticationendpont.war (war file is taken from the patch) outside Identity Server (i.e external tomcat or WSO2 Application Server), then the org.wso2.carbon.identity.application.authentication.endpoint.util-5.0.7.jar file should be taken from the patch0073 folder of the patch and copy to authenticationendpoint/WEB-INF/lib folder. The reason is authenticationendpont.war and org.wso2.carbon.identity.application.authentication.endpoint component are dependent on each other. Both should contain the latest fixes (after applying a patch).

Once you have followed above steps you should be able to get this feature working. Once your client application is trying to authenticate with Identity Server, you should see the active tenants in the dropdown.