Using OpenSSO To Protect Java EE Applications, Part 1: Setting Up X.509 Client Authentication

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.

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.

Figure 1: Sequence Diagram Use Case

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:

• Support for multiple CAs. For example, you can easily import an existing CA based on OpenSSL.
• Support for CRL (both CRLv2 and Delta CRL) and OCSP.
• Remote API using SOAP.
• Key escrow for ciphering private keys.
• Native support for Java Key Store (JKS), the file format used by the Java Virtual Machine (JVM) to store certificates and private keys.

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:

Figure 2: EJBCA Administration Page

Begin by creating a CA. Use the CA generated during installation only for administration purposes. To create a CA:

1. In the EJBCA Administration Page, click the Edit Certificate Authorities link on the left.
   
   
2. In the text box, enter a name — for example, DemoCA — and click Create.
   
   Note: Do not make changes other than those described in the following steps unless you want to experiment.
   
   
3. Optionally, change the size of your CA's private key. If you did not install the Java Cryptographic Extension (JCE), do not make the size 4096 or greater.
   
   
4. Provide the DN of your CA. For example: cn=Asyd Dot Net Demo Root Authority,o=asyd dot net,C=FR.
   
   
5. Choose the validity time of your CA; for demonstration purposes, 365 is a good choice.
   
   
6. Scroll down to the Default CRL Distribution Point section (Figure 3) and enable CRL and OCSP by clicking the corresponding checkboxes. Verify the generated URIs to make sure they are reachable from your OpenSSO server.
   
   
7. Click Generate to generate the CA.

Figure 2a: EJBCA Administration Page: Creating the CA

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:

1. In the EJBCA Administration Page, click the Add/Edit Certificates Profiles link.
   
   
2. Select the ENDUSER (FIXED) value.
   
   
3. Enter CP_ENDUSER in the text area
   
   
4. Click Use Selected.

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:

1. In the EJBCA Administration Page, click the Edit Certificates Profiles link.
   
   
2. Select the CP_ENDUSER certificate profile.
   
   
3. Click Edit Certificate Profile.
   
   
4. Make the following changes:
1. Define the validity. A period of 365 days is typical for client certificates.
2. Enable the Use Authority Information Access feature.
3. Optionally, limit Available Bit Lengths to 1024 and 2048.
   
   
5. Save the 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:

1. In the EJBCA Administration Page, click the Add End Entity link.
   
   
2. Add the following Subject DN fields in the Subject DN Fields area of the window:
1. For the CN, Common name field, check the Required and Modifiable boxes.
2. For the UID, Unique Identifier field, check the Modifiable and Required boxes. The UID is the more important attribute. It defines the UID for OpenSSO.
3. For the O, Organization field, enter your organization name; for example, Aysd Dot Net Demo. Check the Required box; clear the Modifiable box.
4. For the C, Country field, enter the two-character ISO 3166 identifier for your country. Check the Required box; clear the Modifiable box.

Again, only the UID field is important for development.

Figure 3: Specifying Subject DN Information

Next, scroll down and make the following changes, as shown in Figure 4:

1. For Default Certificate Profile, choose CP_ENDUSER from the drop-down list.
   
   
2. For Available Certificate Profiles, select CP_ENDUSER.
   
   
3. For Default CA, choose DemoCA (or whatever name you gave your CA) from the drop-down list.
   
   
4. For Default Token, choose User Generated from the drop-down list.
   
   
5. For Available Tokens, select all available tokens.

Figure 4: Specifying End User Certificate Information

In the same way, create the EE_SERVER End Entity Profile. When you create the EE_SERVER End Entity Profile:

1. Remove the UID DN component.
   
   
2. Specify CP_SERVER as the only available certificate profile.
   
   
3. Specify all tokens as available.

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.

• The traditional mode requires a single server certificate. An HTTPS client (typically a web browser) validates the server identity by matching the certificate to a list, or truststore, of Certificate Authorities. You probably use this mode every day during typical log-in activity.
  
  
• Another mode requires both client and server certificates. The client certificate is validated by the server side, and the server certificate is validated by the client side.
  
  
• The third mode requires a server certificate, but the client certificate is optional.

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:

1. In the EJBCA Administration page, click the Add End Entity link on the left.
   
   
2. Choose EE_SERVER as profile, and enter the following values (an example is shown in Figure 5):
1. Username: opensso
2. Password (and Confirm Password): foo123
3. Email: Enter your e-mail address..
4. Subject DN Fields: Enter the FQDN name that will be presented to OpenSSO.
5. Token: JKS file
   
   

Figure 5: Adding End Entity

 

3. Click Add End Entity.
   
   
4. Click the Public Web link on the left.
   
   
5. Click the Create Server Certificate link.
   
   
6. Provide the login name opensso and password foo123. Click OK.
   
   
7. Save the file as
   $TOMCAT_HOME/conf/opensso.jks
   where $TOMCAT_HOME is your Tomcat installation directory.

In the EJBCA Administration web page, create a new End Entity, using the EE_ENDUSER profile. To create the new End Entity:

1. Click the Add End Entity link on the left, and provide the following information:
1. The name of certificate's owner.
2. The UID of the certificate owner. Note that this value must match the one used in LDAP.
3. As token, choose User Generated.
4. Click the Public Web link, then click Create Browser Certificate.
5. Log in.
   
   
2. Click OK. Your browser generates a public/private key, creates a CSR, and sends it to EJBCA. EJBCA then returns the certificate.
   
   Note: This step has been tested only with the Firefox and Internet Explorer browsers. Firefox is recommended.

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:

1. In a text editor, open the $TOMCAT_HOME/conf/server.xml file, which can be found in the conf/ directory of your Tomcat installation.
   
   
2. Add the following HTTP <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 .p12 file.

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:

1. Log in to the OpenSSO console as user amadmin
   
   
2. Click the Access Control tab, then click Top Level Realm.
   
   
3. Click the Authentication tab.
   
   
4. Click the New button in the Modules Instances frame.
   
   
5. Enter a name for the new module instance: ClientCertificate.
   
   
6. Select the Certificate module type, then click OK.
   
   
7. Select the module instance you created.
   
   
8. If the client certificate includes the OCSP server URI, check the OCSP Validation checkbox.
   
   
9. Scroll down and choose the correct value for the property Certificate Field Used to Access User Profile. For example, if the certificate uses the scheme UID=asyd,CN=Bruno Bonfils,OU=asyd dot net,C=FR, and userid (in OpenSSO) is asyd, then choose the value subject UID.

Figure 6: Creating a New Certificate Module Instance

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.

1. Log in to the OpenSSO console as amadmin.
   
   
2. Click the Access Control tab, then Top Level Realm.
   
   
3. Click the Authentication tab.
   
   
4. Click the New button in the Authentication Chaining frame.
   
   
5. Enter a name for the new chain; for example ldapOrX509. Do not use spaces in the name.
   
   
6. Add two items. It is important to add the items in the order shown:
   1. Instance: X509, Criteria: SUFFICIENT
   2. Instance: DataStore, Criteria: SUFFICIENT

   If necessary, use the drop-down list to replace the current DataStore instance with the one you are using to authenticate users.

Figure 7: Creating a New Authentication Chain

 

7. Select the new authentication chain as the default authentication chain.
   
   

Figure 8: Specifying Default Authentication Chain

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.

Keep connected!

Thanks to Sidharth Mishra, product manager for identity management, and Aravindan Ranganathan, architect for OpenSSO, for their reviews and valuable comments.

• Sun OpenSSO Enterprise 8.0 Installation and Configuration Guide
• Deploying OpenSSO on GlassFish Server
• OpenSSO Main page
• OpenSSO Resource Center
• Support: Sun OpenSSO Express
• Installing Tomcat 6.x and configuring OpenSSO – John Domenichini's Weblog
• Java EE Downloads
• Java EE Technical Articles and Tips
• Java EE Training and Support