|By Bruno Bonfils, with contributions from Rick Palkovic, March 2009|
This article is the first of two parts of a tutorial that explains how to use OpenSSO to protect a Java EE application. The example it illustrates grants access to part of an application. In order to be granted access, a user must be authenticated by a certificate.
The first part of the article describes how to set up the authentication in OpenSSO with client certificates.
This article assumes you already have deployed OpenSSO on GlassFish, JBoss or another application server. The choice of application server makes a difference, as described later in this article.Contents
|-||About Client Certificates|
|-||Using EJBCA to Issue Certificates|
|-||About HTTPS and Client Authentication|
The following sequence diagram illustrates the use case addressed in this article. By logging in with a password, a user can access the private area of the application. However, only users authenticated by a client certificate can access the administrative area.
Achieving user authentication with the HTTPS protocol under the X.509 specification requires both a server certificate and client certificates, issued by a Certificate Authority (CA).
The life cycle of a client certificate is more difficult to manage than that of a server certificate. By design, both server and client certificates are valid until their expiration dates. For a server certificate, a fixed validity time is usually acceptable. In contrast, you may want to revoke a client certificate before the time allowed by general policy. Consider, for example, the certificate used by a consultant who works for an indeterminate few months. Such a certificate needs to be revoked before its normal expiration date. Managing client certificates requires more care and oversight than server certificates.
Certificate Revocation List ( CRL) is the traditional way to manage revoked certificates. At the heart of the CRL approach is a file with the list of revoked certificates' serial numbers. With CRL, all software dealing with client certificates must download an updated list periodically. But by design, there is a delay between client certificate revocation (for example, Monday) and the next CRL update (Tuesday). During this time, the client certificate is still valid.
In contrast, the newer Online Certificate Status Protocol ( OCSP) enables software to check the status of a certificate in real time. With OCSP, if you revoke a client certificate at 8:00 a.m., it will be invalid at 8:01 a.m.
Managing client certificates is aided by high-performance public key infrastructure (PKI) software such as the Enterprise Java Bean Certificate Authority ( EJBCA) PKI software package. EJBCA is an enterprise-class PKI certificate authority (CA) built with Java EE technology. It is open source and free to use under the terms of the Lesser GNU General Public License.
The EJBCA certificate authority is robust, high performance, platform independent, and component based. It can be used stand-alone or can be integrated with other Java EE applications.
EJBCA's many features include:
Install EJBCA with the instructions in the EJBCA installation guide.
Good installation choices are the GlassFish application server with the Derby relational database management system (RDBMS) or the JBoss application server and either the MySQL or PostgreSQL RDBMS.
The CA you define in your properties files is only used for EJBCA purposes. However, the fully qualified domain name (FQDN) you specify is used by the EJBCA to compute default CRL and OCSP URLs. For this reason, you must be especially careful when specifying FQDN in the
web.properties file. Use the FQDN
ejbca.example.com. This hostname must be resolved from your OpenSSO server. If you have no DNS server, use your
/etc/hosts files (or equivalent) to resolve the FQDN.
After you log in as superadministrator in EJBCA, you are presented with a browser window like the one shown in the following figure:
Begin by creating a CA. Use the CA generated during installation only for administration purposes. To create a CA:
cn=Asyd Dot Net Demo Root Authority,o=asyd dot net,C=FR.
You have created a CA, but before you use it, you must create two certificate profiles: one for the certificate that will be used to configure your Tomcat server, and one to issue the client certificates. To create the certificate profiles:
CP_ENDUSERin the text area
In the same way, create a CP_SERVER certificate profile, based on the SERVER (FIXED) profile. The Certificate Profile defines the technical part of a certificate, while the End Entity Profile defines user attributes that describe the owner of the certificate. To create a CP_SERVER certificate profile:
The default profile for SERVER is suitable, so you do not need to edit the CP_ENDUSER certificate profile.
Now, create a first End Entity Profile, named EE_USER. To create an end entity profile:
Demo. Check the Required box; clear the Modifiable box.
Again, only the UID field is important for development.
Next, scroll down and make the following changes, as shown in Figure 4:
In the same way, create the EE_SERVER End Entity Profile. When you create the EE_SERVER End Entity Profile:
When you deal with client certificates in HTTPS, keep in mind your HTTPS listener configurations. The SSLv3/TLS protocol allows three modes for an HTTPS socket.
In the real world, you want to use the same HTTPS URL whether a user is authenticated by password or certificate. This approach requires a server that supports the third, optional client certificate mode. At this writing, the GlassFish application server does not support this mode. Fortunately, the Apache Tomcat web server, supported by OpenSSO, is available as an alternative.
Next, you create the certificates.
To use the Tomcat web server, you must create a keystore for it to use. To create the keystore:
foo123. Click OK.
In the EJBCA Administration web page, create a new End Entity, using the EE_ENDUSER profile. To create the new End Entity:
You now need to configure the Tomcat application server used by OpenSSO. Configuration involves creating a new HTTPS connector and enabling client certificates for the connection. To configure Tomcat:
$TOMCAT_HOME/conf/server.xmlfile, which can be found in the
conf/directory of your Tomcat installation.
<Connector>element, on the same level as the
<Connector>that uses the 8080 port. The
<Connector>element defines the component that manages requests and responses to and from a calling client.
<Connector port="8001" maxThreads="150" strategy="ms" maxHttpHeaderSize="8192" emptySessionPath="true" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true" clientAuth="want" keystoreFile="/home/opensso/apache-tomcat-6.0.18/conf/opensso.jks" keystorePass="foo123" sslProtocol="TLS" truststoreFile="/home/opensso/apache-tomcat-6.0.18/conf/opensso.jks" truststorePass="foo123" truststoreType="JKS" URIEncoding="UTF-8" />
At this point, you should have a working OpenSSO in which users can log in to OpenSSO with an HTTPS listener and optional client authentication. The ability to log in implies that the browser used to access OpenSSO has a certificate (and private key) for the user. Current popular browsers (for example, Firefox, Safari, and Internet Explorer) support the import mechanism specified by the PKCS #12: Personal Information Exchange Syntax Standard. The mechanism enables these browsers to import a certificate and private key from a
Note that if you use Firefox, you can monitor HTTPS negotiation by choosing "Ask me every time" in the Preferences > Advanced > Encryption window. Then, when a server requests your personal certificate, you are prompted to choose a certificate in a dialog box.
There is no certificate authentication module instance by default. To create a new Certificate module instance:
UID=asyd,CN=Bruno Bonfils,OU=asyd dot net,C=FR, and userid (in OpenSSO) is
asyd, then choose the value
You now must create a new authentication chain. Such chains define the behavior that authenticates users. The classic way is to authenticate users is through an LDAP directory, using a login and its associated password. However, to perform certificate authentication, this step must be optional. Therefore, you will use the UID value of the client certificate to look up attributes from the data store.
ldapOrX509. Do not use spaces in the name.
If necessary, use the drop-down list to replace the current DataStore instance with the one you are using to authenticate users.
You have now set up X.509 client authentication in OpenSSO. At this point, it is a good idea to open a different browser, attempt to authenticate as
amadmin, and confirm that the authentication is working.
In Part 2 of this article (coming soon), you will learn how to protect a Java EE application using different profiles, according to the mechanisms used to authenticate with OpenSSO.
Thanks to Sidharth Mishra, product manager for identity management, and Aravindan Ranganathan, architect for OpenSSO, for their reviews and valuable comments.