How to Configure X509 Certificate Support

Anne Ramey
Platform Admins


The X509/CAC support requires some configuration outside of the Kinetic Core application. For example if you are using Tomcat you will need to configure Tomcat's SSL like this:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" SSLEnabled="true" scheme="https" secure="true" clientAuth="want" sslProtocol="TLS" keystoreFile="keystores/kineticcore.jks" keystoreType="JKS" keystorePass="keypass1" truststoreFile="keystores/cacerts.jks" truststoreType="JKS" truststorePass="cacerts1" />
The important part of this configuring is the clientAuth="want" parameter. This indicates to Tomcat to ask the browser for a user certificate but not reject the request if one is not provided. If it is set to "true" it will enforce the need for a certificate. If set to "false" it will never ask for a certificate but if one is provided it will still pass it through to Kinetic Core. Tomcat does not allow you to apply this requirement to URL patterns, to achieve this you will need a third party appliance or reverse proxy in front of your J2EE container. Please note that if you have also enabled SAML support you may already have a keystore configured.

Enabling the Strategy

Add to the global file. This strategy only has one configurable property: security.x509.matchPattern. This property takes a regular expression which is used to extract the subject information from the certificate. This affects the user search filter defined in the provider configuration.

If not specified it will extract the value of the first CN in the subject and your user search filter will have to be (cn={0}) for example.

Configuring the Space

Here is an example of the rest of the configurable parameters. Add these to space security properties file as well:

security.x509.enabled=true security.x509.context.url=ldap:// security.x509.context.baseDN=DC=acme,DC=com security.x509.context.bindDN=CN=Administrator,CN=Users,DC=acme,DC=com security.x509.context.bindPswd=adminpass1 security.x509.user_search_base=CN=Users security.x509.user_search_filter={0} security.x509.attributes.username=sAMAccountName security.x509.attributes.displayName=displayName

Many of these parameters are the same as the ones used for the LDAP provider. The X509 provider functions similarly to the LDAP provider in that it uses LDAP to perform its authentication but what differentiates it is that it has its own filter which pre-authenticates the user using a certificate. The certificate typically will contain the "subject" of the certificate which is the LDAP DN of the user and not the username.

In the case of the X509 provider the usersearchbase is how to find the user by DN, not username. The other additional parameter not on the LDAP provider is the security.x509.attributes.username configuration. This identities the attribute on the user object that represents the username - the system will then use the LDAP object and this username to look up (and optionally update or create) the local user record.

See the LDAP Provider configuration section for details on the shared configuration properties.