This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Current »

This content is a work in progress.

Mutual TLS is a widely used, secure, authentication technique in enterprise environments to ensure the authenticity of the clients to server and vice versa. It facilitates authentication via certificates followed by the establishment of an encrypted channel between the parties.

The OAuth 2.0 Authorization Framework allows the use of additional client authentication mechanisms. One such is the mechanism of client authentication utilizing mutual TLS certificate-based authentication.

In order to utilize TLS for OAuth client authentication, the TLS connection between the client and the authorization server must have been established with mutual X.509 certificate authentication (i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake).

The initial version of this feature supports Self-Signed Certificate Mutual TLS OAuth Client Authentication. It supports client authentication using self-signed certificates. As a prerequisite, the client needs to register an X.509 certificate during service provider configuration. In addition, this certificate should be imported to client-truststore.jks.

Before you begin

Disable the MutualSSLAuthenticator if it is already enabled. To do this,

Open the <IS_HOME>/repository/conf/security/authenticators.xml file and add the disabled="true" attribute within the <Authenticator> tag of the MutualSSLAuthenticator to disable the Mutual SSL Authenticator.

<!-- Authenticator Configurations for MutualSSLAuthenticator-->
<Authenticator name="MutualSSLAuthenticator" disabled="true">
    <Priority>5</Priority>
    <Config>
        <Parameter name="UsernameHeader">UserName</Parameter>
        <Parameter name="WhiteListEnabled">false</Parameter>
        <Parameter name="WhiteList"/>
    </Config>
</Authenticator>

If WSO2 Identity Server is fronted by a load-balancer, SSL tunnelling should be enabled.

Deploying and Configuring Mutual TLS client authenticator artifacts

  1. Add trustManagerClassName="org.wso2.carbon.identity.core.util.ClientAuthX509TrustManager" entry to tomcat connector in  <TOMCAT_HOME>/repository/conf/tomcat/catalina-server.xml. A sample configuration is shown below. 

    <Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
                   port="9443"
                   bindOnInit="false"
                   sslProtocol="TLS"
                   ---
                   ---
trustManagerClassName="org.wso2.carbon.identity.core.util.ClientAuthX509TrustManager" URIEncoding="UTF-8"/>
  2. Download the connector from here and place the corresponding osgi bundle in the <IS_HOME>/repository/component/dropins directory.

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

  4. Add the following configuration in <IS_HOME>/repository/conf/identity/identity.xml file under the <EventListners> property.

    <EventListener type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler" name="org.wso2.carbon.identity.oauth2.token.handler.clientauth.mutualtls.MutualTLSClientAuthenticator" orderId="158" enable="true" />

  5. For mutual TLS authentication, the public certificate of the WSO2 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 WSO2 Identity Server.

Sample 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.

keytool -export -alias wso2carbon -file carbon_public2.crt -keystore wso2carbon.jks -storepass wso2carbon

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

  1. Add a service provider.

    1. Select “Add” under “Service Providers” menu in the Main menu.

    2. Fill in the Service Provider Name and provide a brief Description of the service provider.

    3. Copy the content in your client application’s .pem certificate and paste it as the value for Application Certificate.

    4. Expand the OAuth/OpenID Connect Configuration and click Configure.

    5. Enter a callback URL. E.g. http://localhost:8080/playground2/oauth2client and click Add.

    6. The OAuth Client Key and OAuth Client Secret will be visible when application is updated.

  2. Client sends the certificate to the IS server when invoking the Oauth token endpoint. The request should contain the following required claim values and any other additional claim values.

    • Public Certificate

    • Client Id


Sample token request using mutual TLS client authentication
curl -k -d "grant_type=password&username=admin&password=admin&client_id=qiB6avlILBqnJLSxOfadoJYwOnQa" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token -i  --cert certificate.pem --key key.pem
  • No labels