Mutual SSL (X.509 Certificate) grant type for OAuth2

We have already discussed on implementing custom grant types for OAuth2 in this blog post. Today, we are going to implement a Mutual SSL (X.509 certificate) based grant type for WSO2IS/APIM

Following must be noted.

1. Mutual SSL is handled at transport level. OAuth2 Grant handler has no any idea on the mutual SSL.
2. Once mutual SSL is succeeded; Client certificate can be found from the HTTP servlet request object. If Mutual SSL is failed. it can be founded from HTTP request.
3. Full HTTP request can not be retrieved inside grant handler and only the HTTP parameters are available inside to it.

Therefore, following solution came up.

• Implement a custom servlet filer to retrieve the client certificate from the HTTP servlet request. If client certificate is present in the HTTP servlet request object , it meant that mutual SSL has been correctly happened. Then custom filter can retrieve it and set it as a parameter in to HTTP request object

Please find the implemented custom servlet filter source from here

• OAuth grant handler can retrieve the client certificate from the HTTP parameter. Then grant handler can do any additional verification related to the certificate. Such as checking the CN, DN or any.

Please find the implemented sample custom grant type source from here

Lets try out above these sample implementations in WSO2IS 5.1.0 version. Please go through below steps.

Step 1. Download the servlet filter project and build using Maven3

Step 2. Copy built jar file “org.soasecurity.mutual.ssl.filter-1.0.0.jar” in to <WSO2IS_HOME>/repository/deployment/server/webapps/oauth2/WEB-INF/lib directory

Step 3. Configure following two entries under the root element of the <WSO2IS_HOME>/repository/deployment/server/webapps/oauth2/WEB-INF/web.xml file

<filter>
 <filter-name>MutualSSLFilter</filter-name>
 <filter-class>org.soasecurity.mutual.ssl.filter.MutualSSLFilter</filter-class>
 </filter>

<filter-mapping>
 <filter-name>MutualSSLFilter</filter-name>
 <url-pattern>/token</url-pattern>
 </filter-mapping>

Now we have configured the servlet filter.
Step 4. Download the x.509 grant type project and modify the certificate validation as you like. Then you can build using Maven3

Step 5. Copy built jar file “org.soasecurity.wso2.x509.grant-1.0.0.jar” in to <WSO2IS_HOME>/repository/components/lib directory

Step 6. Configure following entries in the <WSO2IS_HOME>/repository/conf/identity/identity.xml file.

<SupportedGrantType>
<GrantTypeName>x509</GrantTypeName>
<GrantTypeHandlerImplClass>org.soasecurity.wso2.oauth2.x509.grant.X509GrantHandler</GrantTypeHandlerImplClass>
<GrantTypeValidatorImplClass>org.soasecurity.wso2.oauth2.x509.grant.X509GrantValidator</GrantTypeValidatorImplClass>
</SupportedGrantType>

More details can be found from here

Step 7. Restart the server.

Step 8 Send a /token request using a client which support mutual SSL. Client must send the following query param as well.

grant_type=x509

Please try out and let us know the feedback.

Thanks for reading…!!!