Mutual TLS for OAuth Clients

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.

<!-- 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>

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

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