Authentication based on Certificates

Although Mistral-IdM allows authentication based on login/password, that could be inadequate or insufficient in some advanced scenarios. That is because Mistral-IdM also allows authentication based on certificates, where each end user holds a private key.

To perform this authentication mode, Mistral-IdM makes use the XKMS standard through OpenXKMS software. This tutorial explains how configure Mistral-IdM and associated tools in order to enable authentication based on certificates.

OpenXKMS

OpenXKMS is an open source implementation of the XKMS standard (XML Key Management Specification). It provides a server side webservice managing an access point to a PKI. You can download it from http://xkms.sourceforge.net/.

Each kind of PKI needs a connector in order to be managed by the OpenXKMS tool. In this guide we use the dummy connector, used in the implementation by default, which simulates a deployed PKI, showing the basic functionallity and configuration.

To enable OpenXKMS just download the last version of the OpenXKMS Web Service package and deploy it on a application container, such as tomcat, copying the xkms.war file in the webapps folder. It is already configured to use the dummy connector. However, you have to change the Service Name to work with Mistral_IdM. To do that, edit the "xkmsService.xml" file under the [TOMCAT_WEBAPPS]/xkms/WEB-INF/config folder, changing the XKMS_SERVICE_NAME entry setting http://mistral-pki.inf.um.es/xkms:

<entry key="XKMS_SERVICE_NAME">http://mistral-pki.inf.um.es/xkms</entry>

Tomcat configuration

Note: Although this guide explain how to configure tomcat, Mistral-IdM could be used on others application containers.

To enable authentication based on certificates you have to enable Client Authentication on the application container. That makes use of SSL, so ensure you have activated it (see preparing your computer section).

Then, you have to configure a port where end users will be asked for their certificates. To do that, edit the file server.xml under the [TOMCAT_PATH]/conf folder.

Enable the ARP Listener adding inside the server entry:

<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />

Configure the port adding a new connector, making use of ARP. It should appears similar as follows:

<Connector port="8444" protocol="org.apache.coyote.http11.Http11AprProtocol" SSLEnabled="true" maxHttpHeaderSize="8192"
maxThreads="500" scheme="https" secure="true" acceptCount="100"
SSLCertificateFile="/path/to/your/certificate/ServerCertificate.pem"
SSLCertificateKeyFile="/Path/to/yout/ceritifcate/ServerCertificateKey.pem"
SSLVerifyClient="require"
SSLPassword="[Server_private_key_password]"
SSLCACertificateFile="/usr/share/tomcat/webapps/xkms/WEB-INF/conf/pki/ca-x509.cer"
/>

Chose a port number, in this case the 8444 to set the client authentication.

SSLCertificateFile indicates the path to the server certificate file. If you do not have one you have to generate it. (see SSL Configuration HOW-TO).

SSLCertificateKeyFile indicates the path to the server private key file.

SSLPassword is the password of the previous private key.

SSLCACertificateFile is the Certificate Authority (CA) which issues the client certificates. In this case we set the dummy CA which provides the OpenXKMS implementation, because it issues the certificates the end users will use to authentication.

Mistral-IdM Configuration

Mistral-IdM uses the XKMS Client to ask the OpenXKMS service for certificate validation. To configure the client you have to set the following in the mistral_config.xml file:

In the XKMS_SERVER you have to set the URL of the XKMS service, in a basic configuration it is: http://your_server_url/xkms/XKMSService12/. For instance:

<entry key="XKMS_SERVER">http://localhost:8080/xkms/XKMSService12</entry>

Additionally, you have to set the URL which ask the user for certificates, previously defined, in the MISTRAL_IDP_CERT_URL entry. In this case you indicate the port you have configured. For instance:

<entry key="MISTRAL_IDP_CERT_URL">http://localhost:8444/mistral/mistral_idP_cert</entry>

 

Issue Client Certificates

Certificates used by end users to perform the authentication process are managed and issued by the PKI. Each PKI should provide a mechanism to allow end users to get a certificate. XKMS abstract this process in such a way any user are allow to get a new Certicate, sending an XKMS Register Message through a XKMS Client.

If you are using Windows

There exist a tool to perform XKMS client operation, that is, the OpenXKMS Oxien Client, also available from http://xkms.sourceforge.net/. You need to configure this application with your service provider parameters.

Oxien_conf

After that, you can perform a Register operation. As result of this operation, a private and a public key will be generated. Notice that the dummy PKI only allows to generate certificates linked to [whatever]@example.com

Oxien_register

The public and private key should be imported on your web browser. To do this, you have to insert them in a PKCS12 structure. There are several ways to do this, the easy one is through the openssl tool. Run the command:

openssl pkcs12 -export -in [whatever]@example.com_Certificate.cer -inkey [whatever]@example.com_mykey.pem -out myCert.p12 -name "My Certificate".

For instance:

openssl pkcs12 -export -in alice@example.com_Certificate.cer -inkey alice@example.com_mykey.pem -out myCert.p12 -name "My Certificate".

Finally, you have to import in your web browser the myCert.p12 file. In the authentication process, you can make use of this certificate.

If you are using Linux

You can make use of this tool which makes use of the OpenXKMS Client to send a XKMS Register message, generating a public and private key.

Run the command:

java -jar XKMSRegister.jar [XKMS_SERVICE_URL] [email] [Certificate] [PrivateKey] [PrivateKeyPassPhrase]

For instance:

java -jar XKMSRegister.jar http://localhost:8080/xkms/XKMSService12 alice@example.com myCert.cer myCertKey.pem secret

The public and private key should be imported on your web browser. To do this, you have to insert them in a PKCS12 structure. There are several ways to do this, the easy one is through the openssl tool. Run the command:

openssl pkcs12 -export -in [Certificate] -inkey [PrivateKey] -out myCert.p12 -name "My Certificate".

For instance:

openssl pkcs12 -export -in myCert.cer -inkey myCertKey.pem -out myCert.p12 -name "My Certificate".

Finally, you have to import in your web browser the myCert.p12 file. In the authentication process, you can make use of this certificate.