OpenWGA 7.4 - OpenWGA Concepts and Features

Authentication » Special features

Authentication via client certificate

As mentioned earlier the authentication via client certificate is an alternative mechanism that is much safer and also more convenient for the user than using a username/password combination. It utilizes an asymmetric encryption key which every user owns and which can not only be used to validate his identity but also to encrypt data that is send to him. This key is like a very complicated password which a) itself does not need to be sent over the network to be used for authentication and b) which the users browser can use automatically for authentication when a website requests it. If you want to learn more about the way this works lookup Public-key cryptography on Wikipedia.

The downside of this is that those client certificates must be created for and distributed to all users and then finally installed to their browsers. And as the browser holds and manages the authentication functionality it lets everyone benefit from this authentication that uses it, no matter if it is actually the user that the certificate was issued to. So client access/user session security is an issue.

You can use certificate authentication in OpenWGA in combination with the following built-in authentication sources:

Creating a Certificate Authority (CA)

You first need a certificate called "Certificate Authority" (short CA) that is used as base certificate for all client certificates. Such a certificate can be created by yourself, or optionally by a "Trust center" which is a service provider for certificates that are already "trusted" by certificate validating functionalities. While this is of little use when using the CA for client certificates only you may already have a "trusted" certificate for other purposes which you can use as base certificate for your clients.

Certificates normally are distributed as "PEM encoded" files with suffix ".pem". A different format is "PKCS" that is often used to distribute client certificates for web browsers. Your certificate tool of choice should work with both formats.

A popular tool for creating certificates is the open source solution OpenSSL which later can also be used for creating the client certificates.

Preparing the J2EE server

For using certificate authentication your HTTP server must use SSL encryption for communication. Your clients therefor will need to access it via "https". If you not already have established secure communication you will additionally need a SSL server certificate. Lookup the documentation of your J2EE or HTTP server how to create and install such a certificate.

When your HTTP server is able to use SSL you must configure your J2EE server to use client certificates. It therefor needs the CA certificate file to validate client certificates. Be aware that only users owning client certificates will be able to use this SSL port. If you have other users which will not own a certificate but which still need access to your site you might want to consider having an two ports using SSL, one for certificate only users and one for other users.

Here is an example configuration from the "server.xml" configuration file of Apache Tomcat configuring client authentication:

<Connector port="443" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="true" disableUploadTimeout="true" acceptCount="100" 

               SSLEnabled="true" scheme="https" secure="true" sslProtocol="TLS"
               keystoreFile="<path to the tomcat keystore containing the server-certificate>"
               keystorePass="<keystore password>"

               truststoreFile="<path to the truststore file containing the public ca-certificates used for verifing client-certificates>"
               truststorePass="<truststore password>"/>

About the used attributes:

  • The italic attributes in the first block are mandatory attributes of the Connector tag which are not related to client certificates
  • The attributes in the second block "SSLEnabled", "scheme", "secure", "sslProtocol", "keystoreFile" and "keystorePass" are for enabling SSL communication
  • The attributes in the third block finally are for configuring client authentication
    • "clientAuth" enables this feature
    • "truststoreFile" contains the path of a "Java Keystore" file containing the CA certificate(s) that your server regards "trusted". You base certificate for clients will need to be in here.You can use the command line tool "keytool" (contained in each Java JDK distribution) to create such a Java Keystore and add certificates to it. See the JDK documentation on how to do this.
    • "truststorePass" is a password for reading this "Java Keystore" file. This password was issued on creation of the keystore.

Configuration in OpenWGA

As the J2EE application server and its SSL connector is responsible for validating client certificates (i.e. determine if they are signed by a trusted CA) OpenWGA just needs to configured for using these certificates, that are provided by the J2EE server, for authentication.

For this OpenWGA needs access to two files:

  • The CA file as a "PEM encoded" file
  • A file called "Certificate Revocation List" (short CRL) which may contain a list of client certificates that should NOT be granted access although they are signed by a trusted CA. You should add certificates to this list of people that once had access to the system but now should have no more (like ex-employees). This list is the only way to revoke a certificate that once was valid. It is a "PEM or DER encoded" file that should be editable by your certificate tool of choice (like OpenSSL).
Enter OpenWGA admin client in expert mode (checkbox to the top right) and configure:
    • On the domain that should use certificate authentication:
      • Add the option "Enable client certificate authentication" and enable it
      • Add the option "CA for certificate authentication" and enter the path to your CA file
      • Add the option "CRL for certificate authentication" and enter the path to your Certificate Revocation List file
    • On OpenWGA applications that MUST be accessed via certificate authentication (other databases will allow regular authentication on ports not configured for client certificates):
      • Add the publishing option "Force TCP/IP port" and set it to the port where your server requests client authentication
      • Add the publishing option "Force HTTP protocol" and set it to "https"

    Creating and distributing client certificates

    Client certificates can again be created by your certificate tool of choice, which may be OpenSSL. They must match the following conditions:

    • They must be signed against the CA file that you just configured on OpenWGA, either directly or indirectly via an intermediate certificate
    • Their fully distinguished name must match the fully distinguished name that the user has in the OpenWGA authentication source to use (like FDN on directory server, Primary name on Content Store). Otherwise those certificates will still be valid but OpenWGA will not be able to connect them with any known user and therefor reject the login.

    Each user will need an individual client certificate that he receives via file. If available use the PKCS format for this file as it is the most widely accepted format for that task,. He then must import it to his web browser to be able to use it. Here some common examples how to do this:

    • On Mozilla Firefox
      • Open the options dialog under menu "Tools->Options"
      • Open tab "Advanced", sub tab "Security"
      • Click the button "View Certificates"
      • Click the button "Import" and in the following file dialog choose the PKCS certificate file
      • If you certificate file is password protected you will now be prompted to enter this password
    • On Microsoft Internet Explorer
      • Open the options dialog under menu "Extras->Internet options" (or similar)
      • Open the tab "Contents" and click the button "Certificates"
      • There click the button "Import" and follow the instructions of the import assistant, which will ask you for your certificate file and eventually a password by which it is protected
    After that the browser should be able to access a site with certificate authentication and be instantly logged in. Some browsers ask the user which certificate to use on the first time after which the "seamless mode" of certificate authentication will be active.

    Using with content store authentication

    As already stated the fully distinguished name of a client certificate must match the fully distinguished name of the corresponding user in the authentication source. This is also in effect when using a content store as authentication source. User documents to be used with client authentication should match the following compiled requirements

    • The contents of the field "UserName" represents the fully distinguished name in a user document. It should match the FDN of the certificate.
    • The field "Password" may be empty as it is never used. However the item should still exist so the document is correctly interpreted as user document

    Using with directory server authentication

    There is one special condition that must be met when using client certificates together with directly server authentication: A master login for the directory server must be configured.

    This is because OpenWGA will never really login to the Directory Server with the users account as it does not know his password. Instead it always uses the master login to login to the directory server and find the users definition node.

    The "User for master login" is an option that can be added to the directory server configuration. Fill it with the name of a directory server login that has the neccessary privileges to query the directory for user data. You will of course need to enter his password as well.