Enabling Mutual SSL for Admin Services in WSO2 IS

When there is a requirement of calling secured Web Services/Admin services without using user credentials, Mutual SSL can come in handy. What happens here is, the authentication is done using the public certificates keys. Following steps can be used to enable Mutual SSL in WSO2 Identity Server 5.0.0.

  1. Copy org.wso2.carbon.identity.authenticator.mutualssl_4.2.0.jar which is available under resources/dropins directory of the SP1 (WSO2-IS-5.0.0-SP01/resources/dropins/org.wso2.carbon.identity.authenticator.mutualssl_4.2.0.jar) to <IS_HOME>/repository/components/dropins directory.

  2. Open <IS_Home>/repository/conf/tomcat/catelina-server.xml file. Then set the connector property "clientAuth" to ”want”.

  3. To enable the Mutual SSL Authenticator, add the following to <IS_HOME>/repository/conf/security/authenticators.xml file.
    <Authenticator name="MutualSSLAuthenticator" disabled="false">
            <Parameter name="UsernameHeader">UserName</Parameter>
            <Parameter name="WhiteListEnabled">false</Parameter>
            <Parameter name="WhiteList"/>
    Note: If you have enable SAML SSO for IS, you need to set a higher priority for MutualSSLAuthenticator than to SAML2SSOAuthenticator.

  4. Extract WSO2 public certificate from <IS_Home>/repository/resources/security/wso2carbon.jks and add it to client’s trust store. Then add client’s public certificate to the carbon trust store, which can be find in <IS_Home>/repository/resources/security/client-truststore.jks.
    To extract a certificate from wso2carbon.jks
    keytool -export -alias wso2carbon -file carbon_public.crt -keystore wso2carbon.jks -storepass wso2carbon
    To import client's certificate to carbon trust store:
    keytool -import -trustcacerts -alias <client_alias> -file <client_public.crt> -keystore client-truststore.jks -storepass wso2carbon

  5. Now you can call the service by adding the username to either SOAP header or HTTP header as follows.
    Add Soap header:
        <m:UserName soapenv:mustUnderstand="0" xmlns:m="http://mutualssl.carbon.wso2.org">admin</m:UserName>
    Add HTTP Header:
    UserName : <Base4-encoded-username>
The reason for sending the username in the header is to retrieve the roles and permissions for the specific user. Also, the header key "UserName" can be changed as desired by changing the property <Parameter name="UsernameHeader">UserName</Parameter> of the MutualSSLAuthenticator added earlier.