Page Comparison

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

Mutual TLS is also used in 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 as a secure authentication mechanism.  

Mutual 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 prerequisitecan 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. 

Deploying and Configuring Mutual

...

TLS Client Authenticator Artifacts

1. Open the catalina-server.xml file in the <IS_HOME>/repository/conf/tomcat directory. 

2. Locate the connector protocol tag with the sslProtocol="TLS" entry and do the following configurations. 

   Code Block
   <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="9443" bindOnInit="false" sslProtocol="TLS" --- --- URIEncoding="UTF-8"/>

   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. 

   1. .  

      Code Block
      <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="9443" bindOnInit="false" sslProtocol="TLS" --- --- trustManagerClassName="org.wso2.carbon.identity.core.util.ClientAuthX509TrustManager" URIEncoding="UTF-8"/>

   Download the connector from here and place the corresponding osgi bundle in the
   2. 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 clientAuth attribute to want.  

      Code Block
      <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="9443" bindOnInit="false" sslProtocol="TLS" --- --- clientAuth="want" --- --- URIEncoding="UTF-8"/>

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

4. Copy the OSGI bundle to the <IS_HOME>/repository/

   component

   components/dropins

   directory

    directory. 

5. Open the identity.xml file in the <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.Add the following configuration in <IS_HOME>/repository/conf/identity/identity.xml file under the <EventListners> property.identity directory and add the following configuration under the <EventListners> property . 

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

6. For In order for mutual TLS authentication to work, the public certificate certificates of the client application and authorization server (WSO2 Identity Server has to ) should be imported to each other's truststores. 

   For demonstration purposes, let's assume that both 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.

...

1. authorization server's truststore (WSO2_TRUSTSTORE) and client's truststore (CLIENT_TRUSTSTORE) are in WSO2 Identity Server.  

   1. Navigate to the <IS_HOME>/repository/resources/security directory in a command prompt. 

      Code Block
      cd <IS_HOME>/repository/resources/security

   2. To generate the client's private key and public certificate, execute the following commands and enter Distinguished Name (DN) when prompted. 

      Code Block
      title Format
      openssl req -newkey rsa:2048 -x509 -keyout <CLIENT_PRIVATE_KEY> -out <CLIENT_PUBLIC_CERTIFICATE> -days <VALIDITY_PERIOD> -nodes

      Code Block
      title Example
      openssl req -newkey rsa:2048 -x509 -keyout key.pem -out client-certificate.pem -days 3650 -nodes

      Note
      The CLIENT_PRIVATE_KEY and CLIENT_PUBLIC_CERTIFICATE will be used to generate the access token at a later step.

   3. To import the client's public certificate to the authorization server's truststore, execute the following command.

      Code Block
      title Format
      keytool -import -trustcacerts -alias <CLIENT_PUBLIC_CERTIFICATE_ALIAS> -file <CLIENT_PUBLIC_CERTIFICATE> -keystore <WSO2_TRUSTSTORE> -storepass <WSO2_TRUSTSTORE_PASSWORD>

      Code Block
      title Example
      keytool -import -trustcacerts -alias client -file client-certificate.pem -keystore client-truststore.jks -storepass wso2carbon

   4. To export the public certificate of WSO2 Identity Server, execute the following command. 

      Format:

      Code Block
      title Format
      keytool -export -alias <WSO2_CERTIFICATE_ALIAS> -file <WSO2_CERTIFICATE> -keystore <WSO2_KEYSTORE> -storepass <WSO2_KEYSTORE_PASSOWRD>

      Example:

      Code Block
      title Example
      keytool -export -alias wso2carbon -file

...

1. 1. wso2-certificate.crt -keystore wso2carbon.jks -storepass wso2carbon

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

      Code Block
      title Format
      keytool -import -trustcacerts -alias <WSO2_PUBLIC_CERTIFICATE_ALIAS> -file <WSO2_PUBLIC_CERTIFICATE> -keystore <CLIENT_TRUSTSTORE> -storepass <CLIENT_TRUSTSTORE_PASSWORD>

      Code Block
      title Example
      keytool -import -trustcacerts -alias

...

1. 1. wso2carbon -file

...

1. 1. wso2-certificate.crt -keystore

...

1. 1. truststore.jks -storepass

...

1. Add

   1. client-password

   2. Click Update.

2. Restart WSO2 Identity Server.

Testing the Sample

Follow the steps below to test the configurations.

1. Create a service provider.

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

 

1. Access the WSO2 Identity Server Management Console. 
2. On the Main menu, click Identity > Service Providers > Add.
   Image Added
3. Enter playground2 as the Service Provider Name and click Register.
   Image Added
4. Copy the content in your client
application’s .pem certificate and paste it as the value for Application Certificate.Expand the
5. application's certificate in PEM format into the Application Certificate text field.
   Image Added
6. Expand Inbound Authentication Configuration > OAuth/OpenID Connect
Configuration and click
7. Configuration and click Configure.
Enter a callback URL. E.g.
8. 
   Image Added
9. Enter  http://localhost:8080/playground2/oauth2client
 and click Add.

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

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

...

1. 1.   as the Callback URL.
      Image Added
   2. Click Add.
      Note that the OAuth client key and client secret get generated. 
      Image Added

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

   Code Block
   title Format
   curl -k -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>&client_id=<CLIENT_KEY>" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:9443/oauth2/token -i --cert <CLIENT_PUBLIC_CERTIFICATE> --key <CLIENT_PRIVATE_KEY>

   Code Block
   title 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

   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.
   Sample response:
   Image Added