Chapter 16. Managing Certificates

This chapter shows you how to handle certificates used to protect network communication and for authentication.

In theory, you should not have to concern yourself with certificates when working with OpenAM. OpenAM core services and J2EE policy agents depend on the certificates installed for use with the web application container in which they run. OpenAM web policy agents depend on the certificates installed for use with the web server. Theoretically, each certificate has been signed by a well-known Certificate Authority (CA), whose certificate is already installed in the Java CA certificates trust store ($JAVA_HOME/jre/lib/security/cacerts, default password changeit) and in browsers, and so is recognized by other software used without you having to configure anything.

In practice, you might not have the budget for CA signed certificates in your lab or test environment, where you might constantly be installing new configurations, using and throwing away certificates for experiments and repeated tests. In the lab, therefore, you set up OpenAM to use self-signed certificates that you generate at no cost, but that are not recognized, and therefore not trusted out of the box.

How you configure the containers where OpenAM and your applications run to use self-signed certificates depends on your web application server or web server software. Yet, the basic principles apply.

  • First, your container requires its own certificate for setting up secure connections.

  • Second, the clients connecting must be able to trust the container certificate. Generally this means that clients must recognize the container certificate because they have a copy of the public certificate stored somewhere the client trusts.

  • Third, if you use certificate authentication in OpenAM, OpenAM must also be able to find a copy of the client's public certificate to trust the client, most likely by finding a match with the certificate stored in the client profile from the identity repository. How you include client certificates in their identity repository entries depends on your identity repository more than it depends on OpenAM.

Some client applications let you trust certificates blindly. This can be helpful when working in your lab or test environment with self-signed certificates. For example, you might want to use HTTPS with the OpenAM RESTful API without having the client recognize the self-signed server certificate. 

$ curl "https://openam.example.com:8443/openam/identity/authenticate?
 username=bjensen&password=hifalutin"
curl: (60) Peer certificate cannot be authenticated with known CA certificates
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
 of Certificate Authority (CA) public keys (CA certs). If the default
 bundle file isn't adequate, you can specify an alternate file
 using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
 the bundle, the certificate verification probably failed due to a
 problem with the certificate (it might be expired, or the name might
 not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
 the -k (or --insecure) option.
$ curl --insecure "https://openam.example.com:8443/openam/identity/authenticate?
 username=bjensen&password=hifalutin"
token.id=AQIC5wM2LY4SfczMax8jegpSiaigB96NOWylLilsd0PUMjY.*AAJTSQACMDE.*

Procedure 16.1. To Set Up OpenAM With HTTPS on Tomcat

The container where you install OpenAM requires a certificate in order to set up secure connections. The following steps demonstrate one way to set up Tomcat with an HTTPS connector, using the Java keytool command to manage the certificate and key stores. Once Tomcat can do HTTPS, you deploy OpenAM as you normally would, over HTTPS.

  1. Stop Tomcat.

  2. Create a certificate and store it in a new key store.

    $ cd /path/to/tomcat/conf/
$ keytool -genkey -alias openam.example.com -keyalg RSA -keystore keystore.jks
Enter keystore password:  
What is your first and last name?
  [Unknown]:  openam.example.com
What is the name of your organizational unit?
  [Unknown]:  Eng
What is the name of your organization?
  [Unknown]:  ForgeRock.com
What is the name of your City or Locality?
  [Unknown]:  Grenoble
What is the name of your State or Province?
  [Unknown]:  Isere
What is the two-letter country code for this unit?
  [Unknown]:  FR
Is CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
 C=FR correct?
  [no]:  yes

Enter key password for <openam.example.com>
 (RETURN if same as keystore password):

  3. Uncomment the SSL connector configuration in Tomcat's conf/server.xml, specifying your key store file and password. 

    <!-- Define a SSL HTTP/1.1 Connector on port 8443
     This connector uses the JSSE configuration, when using APR, the 
     connector should be using the OpenSSL style configuration
     described in the APR documentation -->
<!--
-->
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
           maxThreads="150" scheme="https" secure="true"
           keystoreFile="/path/to/tomcat/conf/keystore.jks"
           keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS" />

  4. Start Tomcat.

  5. Verify that you can connect to Tomcat on port 8443 over HTTPS.

    Your browser does not trust the certificate, because the certificate is self-signed, not signed by any of the CAs your browser knows.

    Your browser does not trust your self-signed certificate.

    [D]

    You recognize the Subject and Issuer of your certificate, and so can choose to trust the certificate, effectively saving it into your browser's trust store.

  6. Deploy and configure OpenAM as you normally would.

Procedure 16.2. To Share Self-Signed Certificates

When you use a self-signed certificate for your container, clients connecting must be able to trust the container certificate. Your browser makes this an easy, but manual process. For other client applications, you must import the certificate into the trust store used by the client. By default, Java applications can use the $JAVA_HOME/jre/lib/security/cacerts store. The default password is changeit.[9] The steps that follow demonstrate how to import a self-signed certificate into the Java cacerts store.

  1. Export the certificate from the key store.

    $ cd /path/to/tomcat/conf/
$ keytool -exportcert -alias openam.example.com -file openam.crt -keystore
 keystore.jks
Enter keystore password:
Certificate stored in file <openam.crt>

  2. Import the certificate into the trust store.

    $ keytool -importcert -alias openam.example.com -file openam.crt
 -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts
Enter keystore password:  
Owner: CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
 C=FR
Issuer: CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
 C=FR
Serial number: 4e789e40
Valid from: Tue Sep 20 16:08:00 CEST 2011 until: Mon Dec 19 15:08:00 CET 2011
Certificate fingerprints:
  MD5:  31:08:11:3B:15:75:87:C2:12:08:E9:66:00:81:61:8D
  SHA1: AA:90:2F:42:0A:F4:A9:A5:0C:90:A9:FC:69:FD:64:65:D9:78:BA:1D
  Signature algorithm name: SHA1withRSA
  Version: 3
Trust this certificate? [no]:  yes
Certificate was added to keystore

Procedure 16.3. To Change the Signing Key for Federation

The following steps cover how to change the signing key for an identity provider. This procedure involves creating a self-signed certificate in a new key store file, and also preparing encrypted password files so that OpenAM can access the key store and the private key.

  1. If you do not already have the new signing key in your key store, generate a new key and key store.

    The following example starts an interactive keytool session that requests information needed to generate a new key valid for two years, and puts it in a key store named keystore.jks. You can perform this step in a temporary location, and then move the files generated once you have completed your work.

    Keep track of the passwords you enter here, as you use them in the next step. 

    $ cd /tmp
$ keytool -genkeypair -alias newkey -keyalg RSA -keysize 1024 -validity 730
 -storetype JKS -keystore keystore.jks
Enter keystore password:  
Re-enter new password: 
What is your first and last name?
  [Unknown]:  openam.example.com
What is the name of your organizational unit?
  [Unknown]:  Eng
What is the name of your organization?
  [Unknown]:  ForgeRock.com
What is the name of your City or Locality?
  [Unknown]:  Grenoble
What is the name of your State or Province?
  [Unknown]:  Isere
What is the two-letter country code for this unit?
  [Unknown]:  FR
Is CN=openam.example.com, OU=Eng, O=ForgeRock.com, L=Grenoble, ST=Isere,
 C=FR correct?
  [no]:  yes

Enter key password for <newkey>
 (RETURN if same as keystore password):
Re-enter new password:

    Self-signed keys are not automatically recognized by other entities. You must also share the self-signed key as described in Procedure 16.2, “To Share Self-Signed Certificates”.

  2. Using the passwords you entered in the previous step, prepare the password files to encrypt.

    Create two files, each containing only a password in clear text. You can create the files in the same directory as the key store.

    • keypass.cleartext contains the clear text key password for the private key you generated.

    • storepass.cleartext contains the clear text key store password.

  3. If you have not already done so, install the administration tools as described in To Set Up Administration Tools.

  4. Prepare encrypted password files for use by OpenAM.

    $ ./ampassword --encrypt keypass.cleartext > .keypass
$ ./ampassword --encrypt storepass.cleartext > .storepass

    Remove the *.cleartext files after preparing the encrypted versions.

  5. Replace the default OpenAM key store and password files with the ones that you have created.

    The following example works with an installation of OpenAM where the deployment URI is /openam. 

    $ cp keystore.jks .keypass .storepass ~/openam/openam/

  6. Restart OpenAM, or the container where it runs, so that OpenAM can use the new key store and encrypted password files.

  7. Login to OpenAM console as administrator, and then set the new signing key in one of two ways.

    1. If you have not yet configured your identity provider, select Common Tasks > Create Hosted Identity Provider, and then follow the instructions, selecting your key from the Signing Key drop-down list.

    2. If you have already configured your identity provider, browse to Federation > provider-name > Assertion Content > Signing and Encryption, and then edit the signing key certificate alias.

      Save your work.

  8. Share updated metadata with other entities in your circle of trust as described in Setting Up SAML 2.0 SSO.


[9] Alternatively, you can specify the trust store for a Java application, such as -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit.