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,
<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.
If WSO2 Identity Server is fronted by a load-balancer, SSL tunnelling should be enabled.
Deploying and Configuring Mutual TLS client authenticator artifacts
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.
- Download the connector from here and place the corresponding osgi bundle in the
<IS_HOME>/repository/conf/tomcat/catalina-server.xmlfile 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.
Add the following configuration in <IS_HOME>/repository/conf/identity/identity.xml file under the
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.
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
Add a service provider.
Select “Add” under “Service Providers” menu in the Main menu.
Fill in the Service Provider Name and provide a brief Description of the service provider.
Copy the content in your client application’s .pem certificate and paste it as the value for Application Certificate.
Expand the OAuth/OpenID Connect Configuration and click Configure.
Enter a callback URL. E.g. http://localhost:8080/playground2/oauth2client and click Add.
The OAuth Client Key and OAuth Client Secret will be visible when application is updated.
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.