Venidu Creations
Published in

Venidu Creations

Configuring WSO2 X509Certificate Authenticator in Identity Server

Configuring Tomcat to Support Client Certificates

Add following connector configuration in <IS_HOME>/repository/conf/tomcat/catalina-server.xml file.

<! — Keystore will be used for HTTPS SSL connection. So that, request hostname should match with the certificate CN (i.e. localhost). We can use the default wso2carbon.jks →<! — Truststore will be used for certificate based authentication, where the user certificate should be added as a trusted certificate →<Connector protocol=”HTTP/1.1" port=”8443" maxThreads=”200" scheme=”https” secure=”true” SSLEnabled=”true” keystoreFile=”/path/to/keystore.jks” keystorePass=”keystorepwd” truststoreFile=”/path/to/truststore.jks” truststorePass=”truststorespassword” clientAuth=”want” sslProtocol=”TLS”/>

Please note that this connector should come 1st in the order, otherwise when mutual SSL happens, the already existing connector (9443) will be picked up and certificate will not retrieved correctly.

clientAuth attribute is the attribute that causes Tomcat to require the client to provide a certificate which can be configured as follows.

  • true — valid client certificate required for a connection to succeed
  • want — use a certificate if available, but still connect if no certificate is available
  • false — no client certificate is required or validated

As the “truststoreFile”, specify the location of the trust store containing the certificate issuers for trusted client certificates.

Configure Authentication Endpoint

Following AuthenticatorConfig configuration should be added in <IS_HOME>/repository/conf/identity/application-authentication.xml.

<AuthenticatorConfig name=”x509CertificateAuthenticator” enabled=”true”>
<Parameter name=”AuthenticationEndpoint”>https://localhost:8443/x509-certificate-servlet</Parameter>
<Parameter name=”username”>CN</Parameter>
  • AuthenticationEndpoint: This is the URL with the port that is secured with the certificate(e.g., https://localhost:8443/x509-certificate-servlet). Change accordingly with you corresponding host name.
  • username : For this, can configure any of the certificate attributes (i.e. CN, Email). In X509 authentication, this certificate attribute value will be taken as the authenticated user subject identifier.

When X509 authentication is configured as the second step, the certificate will be validated to check whether it is associated with the authenticated user in first step. For that, this “username” parameter will be used. There the authenticated user name in first step will be validated with the certificate attribute in this property.

When X509 authentication is configured as the first step, this certificate attribute will be treated as the authenticated user subject identifier.

  • Add following parameter, if you use identity claim dialect URI to store X509 certificate.
<Parameter name=”setClaimURI”></Parameter>
  • Add following parameter, if you need to enable storing the X509 certificate as a user claim.
<Parameter name=”EnforceSelfRegistration”>true</Parameter

Add a Claim Mapping for the Certificate

If storing certificate as a user claim is enabled, X509 certificate will be stored as a user claim, and verify that with the certificate retrieved in the request. Please select a mapped attribute for this claim which supported by the underlying database type.

Database Considerations

If you use identity claim to store X509 Certificate or are working with read only user store, the certificate is getting stored in the DATA_VALUE column of IDN_IDENTITY_USER_DATA table. The default DB script has set the column size to 255 characters but in this case the certificate value is having more than 255 characters.

If you use wso2 claim to store X509 Certificate, the certificate is getting stored as a user attribute in the UM_ATTR_VALUE column of UM_USER_ATTRIBUTE table. The default DB script has set the column size to 1024 characters but in this case the certificate value is having more than 1024 characters.

So in both above cases, you need to modify the column size to a higher value (ex: 2048 or higher if you think the character count might exceed).

Application with X509 authentication

Create a service provider for the application in IS and configure the X509 authentication as follows.

Go to the Local and Outbound Authentication Configuration section of the service provider.

You have two options here. You can add X509 certificate authenticator as the first factor and also as the second factor.

  • Second factor
  1. Select the Advanced configuration radio button option.
  2. Add the basic authentication as a first step and X509Certificate authentication as the second step.
  • First factor
  1. Select Local Authentication as the Authentication Type and select X509Certificate from the drop-down list.

Afterwards, test the X509 authentication by login to the application.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Indunil Rathnayake

Indunil Rathnayake

Former Associate Technical Lead @ WSO2 | IT graduate @ University of Moratuwa