This documentation is for WSO2 Identity Server 5.0.0. View documentation for the latest release.
Page Comparison - Customizing the Authentication Endpoint (v.3 vs v.4) - Identity Server 5.0.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


  1. Edit the <IS_HOME>/repository/conf/tomcat/catalina-server.xml file and set the clientAuth attribute in the Connector tag to “want” as shown below. This is done to disable the certificate authentication on certain occasions (like when working on mobile apps). This makes two-way SSL authentication optional.

    Code Block
  2. Copy the org.wso2.carbon.identity.authenticator.mutualssl-4.2.0.jar file in the <IS_SP_HOME>/resources/dropins folder dropins folder to the <IS_HOME>/repository/components/dropins/ directory.
  3. Copy the following into the <IS_HOME>/repository/conf/security/authenticators.xml file under the Authenticators tag.

    Code Block
    <!-- Authenticator Configurations for MutualSSLAuthenticator-->
    <Authenticator name="MutualSSLAuthenticator" disabled="false">
            <Parameter name="UsernameHeader">UserName</Parameter>
            <Parameter name="WhiteListEnabled">false</Parameter>
            <Parameter name="WhiteList"/>
  4. If the SAML2SSOAuthenticator is enabled (disabled="false") in the <IS_HOME>/repository/conf/security/authenticators.xml file, set its priority to 0. Otherwise ignore this step.

    Code Block
    <Authenticator name="SAML2SSOAuthenticator" disabled="false">
  5. Add the following configuration into the <IS_HOME>/repository/conf/security/application-authentication.xml file under the ApplicationAuthentication tag.

    Code Block

    When configuring the TenantDataListenerURL tag, note the following.

    • In a clustered setup that has multiple authentication endpoint web applications hosted, list all of them under the TenantDataListenerURL tag.

    • For authentication endpoint web applications hosted outside the WSO2 Identity Server or in other nodes of a cluster, add the absolute URL within the TenantDataListenerURL tag.

  6. Restart the server using one of the following commands.

    • Windowswso2server.bat

    • Linux/Unixsh

  7. Once the server is restarted, the authenticationendpoint.war file is deployed. The <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint/WEB-INF/classes/ file has to be changed with the required values for properties. The following are the default values for the properties to be used in this file.

    Code Block

    Do the following updates to this configuration.

    1. Set tenantListEnabled to true in order to enable the tenants to display as a list.
    2. For the mutual.ssl.username property, set the username that is to be used for mutual SSL authentication. This user needs to have permission to list down tenants. You can add a new username here provided that you create a user with that username and grant the following permissions to the role of the user.


      Super Admin Permissions > Manage > Monitor > Tenants > List

    3. Set the Identity Server host and the port in and identity.server.port properties.
    4. Paths for client keystore and truststore can be relative paths or absolute paths. The default paths point to the keystore and truststore of the Identity Server itself. A new keystore can be created and used for the client if necessary, however, you must set the passwords for client.keyStore.password and client.trustStore.password appropriately.

  8. For mutual SSL authentication, the public certificate of the Identity Server has to be imported to the truststore of the client and the public certificate of the client has to be imported to the client-truststore of Identity Server.

    titleSample commands

    The following two commands are examples if you are using the keystore and client-truststore of the Identity Server itself for the client. This is executed from the <IS_HOME>/repository/resources/security directory.

    Code Block
    keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon
    Code Block
    keytool -import -trustcacerts -alias carbon -file carbon_public2.crt -keystore client-truststore.jks -storepass wso2carbon