Mutual TLS is a widely-used, secure authentication technique that ensures the authenticity between a client and server using an encrypted channel established with a mutual X.509 certificate. The client certificate and certificate verification messages will be sent during the TLS handshake.
The TLS handshake is a set of steps executed to establish a secure connection between the client and server.
Mutual TLS is also used in the OAuth 2.0 Authorization Framework as a secure authentication mechanism.
Mutual TLS for OAuth client authentication can be implemented using either of the following mechanisms:
- PKI mutual TLS OAuth client authentication: This approach uses a subject Distinguished Name (DN) and validated certificate chain to identify the client.
- A self-signed certificate: In this approach, the client needs to register an X.509 certificate during the service provider configuration and import it to the truststore.
WSO2 Identity Server currently supports the approach that uses the self-signed certificates.
Let's try out configuring mutual TLS in WSO2 Identity Server and test with a sample.
Before you begin
To disable the mutual SSL authenticator:
The mutual SSL authenticator allows the OAuth client to access the WSO2 Identity Server admin services without having the required privileges.
authenticators.xmlfile in the
disabledattribute of the
<Authenticator name="MutualSSLAuthenticator">property to
- If WSO2 Identity Server is fronted by a load-balancer, enable SSL tunnelling.
Deploying and Configuring Mutual TLS Client Authenticator Artifacts
catalina-server.xmlfile in the
Locate the connector protocol tag with the
sslProtocol="TLS"entry and do the following configurations.
MutualTLS supports two-way TLS authentication that allows the server to validate the client and vice versa. Certain applications, e.g., mobile applications may not require server-side validation.
To make the server-side validation optional, set the
- Download Mutual TLS Client Authenticator v2.0.3 connector from here.
Note that an OSGI bundle (
org.wso2.carbon.identity.oauth2.token.handler.clientauth.mutualtls-<VERSION>.jar) gets downloaded.
Copy the OSGI bundle to the
identity.xmlfile in the
<IS_HOME>/repository/conf/identitydirectory and add the following configuration under the
In order for mutual TLS authentication to work, the public certificates of the client application and authorization server (WSO2 Identity Server) should be imported to each other's truststores.
For demonstration purposes, let's assume that both the authorization server's truststore (
WSO2_TRUSTSTORE) and client's truststore (
CLIENT_TRUSTSTORE) are in WSO2 Identity Server.
Navigate to the
<IS_HOME>/repository/resources/securitydirectory in a command prompt.
To generate the client's private key and public certificate, execute the following commands and enter Distinguished Name (DN) when prompted.
CLIENT_PUBLIC_CERTIFICATEwill be used to generate the access token at a later step.
To import the client's public certificate to the authorization server's truststore, execute the following command.
To export the public certificate of WSO2 Identity Server, execute the following command.
Import the public certificate of WSO2 Identity Server to the client's truststore. If the truststore is using the jks format, execute the following command.
Restart WSO2 Identity Server.
Testing the Sample
Follow the steps below to test the configurations.
Create a service provider.
- Access the WSO2 Identity Server Management Console.
- On the Main menu, click Identity > Service Providers > Add.
playground2as the Service Provider Name and click Register.
- Copy the content in your client application's certificate in PEM format into the Application Certificate text field.
- Expand Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click Configure.
http://localhost:8080/playground2/oauth2clientas the Callback URL.
- Click Add.
Note that the OAuth
client secretget generated.
To obtain an access token by invoking the OAuth token endpoint of WSO2 Identity Server, execute the following cRUL in a command prompt.
This request contains the client ID, client's public certificate and any other additional claims and is signed using the client's private key.
Note that an access token gets generated. You can use this access token to access the APIs or any other secured resources of the client application.