Managing Certificates and Keystores

This chapter shows how to work with certificates and keystores used to protect network communication and to sign and encrypt information.

About Certificates in OpenAM

Digital signatures are constructed and verified as follows:

The signer computes a hash of the data to sign, and encrypts the hash using a private key to get the signature.
The signer then attaches the signature to the data, and sends the message with the recipient.
To validate the digital signature on the message, the recipient decrypts the signature using the public key certificate that corresponds to the private key of the signer.
The recipient computes the hash of the data, then checks that the decrypted signature (the decrypted hash) matches the computed hash.

Parties signing requests, responses, or assertions must share the public key certificates for signing keys. The certificates can either be shared in advance and imported into the trusted partners' trust stores, then referenced in the configuration by their trust store aliases, or shared in each signed message.

You should not have to concern yourself with certificates when working with OpenAM. OpenAM’s core services and Java EE 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. 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.

However, you may want to configure OpenAM advanced features such as SAML v2.0, OpenID Connect 1.0, and others, which require certificates and key aliases to be maintained in a keystore whose location is configured in OpenAM.

You can use either CA or self-signed certificates with OpenAM, although you should have in mind that you will need to configure your applications to trust your self-signed certificates. For more information about installing OpenAM in a secure container with a self-signed certificate, see "To Set Up OpenAM With HTTPS and Self-Signed Certificates". For more information about sharing self-signed certificates among applications, see "To Share Self-Signed Certificates".

To Set Up OpenAM With HTTPS and Self-Signed Certificates

The container in which you install OpenAM requires a certificate in order to set up secure connections. Perform the following steps to set up Apache Tomcat 8.0 (Tomcat) with an HTTPS connector, using the Java keytool command to create a self-signed key pair:

Stop Tomcat.

Create a certificate and store it in a new keystore:

$ cd /path/to/tomcat/conf/
$ keytool -genkey -alias openam.example.com -storetype JCEKS
  -keyalg RSA -keystore keystore.jceks
  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):

Uncomment the SSL connector configuration in Tomcat’s conf/server.xml, and specify your keystore file, type, 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="org.apache.coyote.http11.Http11NioProtocol"
 SSLEnabled="true" maxThreads="150" scheme="https" secure="true"
 keystoreFile="/path/to/tomcat/conf/keystore.jceks"
 keystorePass="changeit"
 keystoreType="JCEKS"
 clientAuth="false" sslProtocol="TLS" />

You may need different settings depending on your configuration and version of Apache Tomcat. See the documentation for your version for more information.

Start Tomcat.
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 and not signed by any of the CAs stored in your browser.

You recognize the subject and issuer of your certificate, and so can choose to trust the certificate, saving it into your browser’s trust store.

Deploy and configure OpenAM.
To share the self-signed certificate in your container with other applications or servers, see "To Share Self-Signed Certificates".

To Share Self-Signed Certificates

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. The following 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’s certificate. Generally, this means that clients recognize the container’s 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 isnt 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.*

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.^[1] The steps that follow demonstrate how to import a self-signed certificate into the Java cacerts store:

Export the certificate from the keystore:

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

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

Configuring Keystores in OpenAM

OpenAM supports two possible keystore types to store certificates and keys: JCEKS, configured by default, and JKS.

During installation, OpenAM deploys a keystore of each type with several self-signed key aliases for demo and test purposes only. For production deployments, you should generate your own key aliases and configure OpenAM to use them.

Most OpenAM features that require storing key aliases for signing or encryption use the default keystore configuration. However, some features may require or support different configurations:

The Forgerock Authenticator (OATH) module and the Forgerock Authenticator (PUSH) module support configuring a specific keystore to encrypt device profiles instead of using the default keystore.
The Security Token Service supports configuring separate keystores for encrypting issued SAML v2.0 and OpenID Connect tokens.
The Audit Logging Service requires configuring a JKS keystore for tamper proofing.
SAML v2.0 identity providers support setting up a specific file to store the password of the key pair used for signing or encryption, instead of using the password file for the default keystore.

For a comparison between the default configuration of the JCEKS and the JKS keystores in OpenAM, see the following table:

JCEKS and JKS Keystore Comparison
	JCEKS	JKS
By default in OpenAM?	Yes	No
In which path is it?	`$HOME/openam/openam/keystore.jceks`	`$HOME/openam/openam/keystore.jks`
Where is its password stored?	`$HOME/openam/openam/.storepass`	`$HOME/openam/openam/.storepass`
Which test aliases does it contain?	`test` (asymmetric) `selfserviceenctest` (asymmetric) `selfservicesigntest` (symmetric)	`test` (asymmetric)
Where is the private key password file?	`$HOME/openam/openam/.keypass`	`$HOME/openam/openam/.keypass`

To Configure Keystore Properties

OpenAM provides the JCEKS keystore by default on new installations. If you have upgraded from OpenAM 13 or previous versions, OpenAM would use the JKS keystore by default, unless you reconfigured OpenAM to use the JCEKS keystore.

This procedure assumes that your keystore is configured with the key aliases that you need, and that the password for the keystore and for the key aliases have been encrypted. For more information about replacing the test key alias, see "To Change OpenAM Default test Signing Key ", and for more information about encrypting passwords for your already created keystore and key aliases, see "To Encrypt Keystore Passwords".

To configure OpenAM to use a JCEKS or a JKS keystore, or to modify OpenAM’s keystore configuration, perform the following steps:

Determine whether you want to configure the keystore for all your servers, or configure the keystore on a per-server basis:

If you want to configure the keystore for all your servers, navigate to Configure > Server Defaults > Security > Key Store.

If you want to configure the keystore on a per-server basis, nagivate to Deployment > Servers > Server Name > Security > Key Store.

For more information about inherited properties, see "Configuring Servers" in the Reference.
Enter the keystore file name in the Keystore File field. For example, keystore.jceks.
Set the Keystore Type to JKS or JCEKS.
In the Keystore Password File field, enter the location of the keystore password file.
In the Private Key Password File field, enter the location of the private key password file.
In the Certificate Alias field, enter the alias of the private key to sign SAML v1.x XML files. If you do not require SAML v1.x functionality, you can leave the default test alias.
Save your changes, and restart the OpenAM server or servers affected by the configuration changes.

To Encrypt Keystore Passwords

The steps in this procedure describe how to encrypt keystore and key alias passwords after you have changed them. The procedure assumes you have a keystore with your required key aliases already created and that all the key aliases have the same password. However, you can modify this procedure to encrypt passwords for SAML v2.0 keys if you want to keep them different from those already in the keystore.

To encrypt keystore and key alias passwords, perform the following steps:

Back up your original files, for example, the $HOME/openam/openam/.storepass and the $HOME/openam/openam/.keypass files.
Change the passwords of your keystore and key aliases as required.
Create two files, each containing only a password in cleartext. You can create the files in a temporary location:
- storepass.cleartext contains the cleartext keystore password.
- keypass.cleartext contains the cleartext key password for the key aliases that reside in the keystore.
(Optional) If you have not already done so, install the administration tools as described in "To Set Up Administration Tools" in the Installation Guide.
Prepare encrypted password files for use by OpenAM:
```
$ ./ampassword --encrypt storepass.cleartext > .storepass
$ ./ampassword --encrypt keypass.cleartext > .keypass
```
Remove the *.cleartext files after preparing the encrypted versions.
Replace the password files with the ones that you have created. For example:
```
$ cp .storepass .keypass ~/openam/openam/
```
(Optional) In a multi-server environment, every server has its own keystore file. Make sure key aliases and certificates are maintained in every server by doing the same changes in all, or copying over the keystore and the .keypass and .storepass files.
(Optional) (Optional) If the password files created have different names than the default .storepass and .keypass, perform the following steps to change the keystore configuration:
1. Log in to the OpenAM console as an administrative user, for example, amadmin.
2. Determine whether you want to configure the keystore for all your servers, or configure the keystore on a per-server basis:
  
  If you want to configure the keystore for all your servers, navigate to Configure > Server Defaults > Security > Key Store.
  
  If you want to configure the keystore on a per-server basis, nagivate to Deployment > Servers > Server Name > Security > Key Store.
  
  For more information about inherited properties, see "Configuring Servers" in the Reference.
3. In the Keystore Password File field, enter the location of the keystore password file.
4. In the Private Key Password File field, enter the location of the private key password file.
5. Save your changes.
(Optional)If you created a password file specifically for signing SAML assertions, navigate to Federation > Entity Providers > Provider Name and insert the name of the password file in the Key Pass property. Save your changes.
Restart the OpenAM server or servers affected by the configuration changes.

Managing Key Aliases in OpenAM

When deleting or adding key aliases, you should consider the following points:

By default, OpenAM uses the test key alias as follows:
- To sign persistent cookies: in Realms > Realm Name > Authentication > Settings > Security > Persistent Cookie Encryption Certificate Alias.
- To sign SAML v1.x XML files: in Configure > Server Defaults > Security > Key Store > Certificate Alias.
- To sign and encrypt stateless sessions: in Configure > Global Configuration > Session.
  
  For more information about replacing the test key alias, see "To Change OpenAM Default test Signing Key ".
There may be more than one key alias in the keystore. For instance, you may have one key alias for SAML 2.0 configuration, and two more key aliases for the user self-service features, and others.
The key aliases' passwords must be encrypted in a file, and configured in OpenAM:
- For SAML v2.0 identity providers, you can create a password file for the key aliases used to sign assertions. For more information, see "Modifying an Identity Provider’s Configuration".
- For the Forgerock Authenticator (OATH) and the Forgerock Authenticator (PUSH) modules, you can create a password file for the key aliases used to encrypt device profiles. For more information, see "Implementing Multi-Factor Authentication".
- For other purposes (SAML v1.x, user self-service, stateless sessions, and others), the key aliases in the keystore must have the same password. This password must be then encrypted in a file and configured in OpenAM.
For more information about encrypting the password file, see "To Encrypt Keystore Passwords".
The password for the keystore and the password of the key aliases do not need to match.
In a multi-server environment, every server has its own keystore file. Make sure key aliases and certificates are maintained in every server.
You must restart OpenAM if you make any changes to the keystore, for example, adding or removing keys, changing key passwords, or changing the keystore password.

For recommendations on which algorithm to use for different OpenAM features, see the following table:

Recommended Algorithms to Create Key Aliases for OpenAM Features
Usage	Recommended Algorithm
User self-service encryption key	RSA with SHA-256, minimum 2048-bit
User self-service signing secret	HMAC with SHA-256
SAML v1.x	RSA with SHA-256, minimum 2048-bit
SAML v2.0	RSA with SHA-256, minimum 2048-bit
Persistent Cookie Encryption	RSA with SHA-256, minimum 2048-bit
Stateless Sessions	See "Configuring the JWT Signature"

To Change OpenAM Default test Signing Key

The steps in this procedure cover how to change the test key alias that is configured by default in OpenAM, for another key:

Back up the $HOME/openam/openam/keystore.jceks, $HOME/openam/openam/.storepass, and $HOME/openam/openam/.keypass files.

Acquire a new key from your certificate authority, or generate new self-signed keys.

You can generate a new key (self-signed or not) and add it to the existing keystore configured in OpenAM, you can generate a new key and a new keystore, or you can import a key to a keystore. When you create or import a new key, the keytool command adds the new alias to the specified keystore if it exists, or creates a new keystore if it does not exist.

For this example, the step uses self-signed keys for example purposes, and creates a new keystore keystore.jceks file in a temporary location with a new asymmetric key alias called newkey.

The passwords entered in this step are encrypted manually in the next step, keep track of them:

$ cd /tmp
$ keytool \
  -genkeypair \
  -alias newkey \
  -keyalg RSA \
  -keysize 2048 \
  -validity 730 \
  -storetype JCEKS \
  -keystore keystore.jceks
  Enter keystore password:
  Reenter 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):
  Reenter new password:

Create two files, each containing only a password in cleartext:
- storepass.cleartext contains the cleartext keystore password.
- keypass.cleartext contains the cleartext key password for the key aliases that reside in the keystore.
(Optional) If you have not already done so, install the administration tools as described in "To Set Up Administration Tools" in the Installation Guide.
Prepare encrypted password files for use by OpenAM:
```
$ ./ampassword --encrypt storepass.cleartext > .storepass
$ ./ampassword --encrypt keypass.cleartext > .keypass
```
Remove the *.cleartext files after preparing the encrypted versions.
Replace the default OpenAM keystore and password files with the ones that you have created. For example:
```
$ cp keystore.jceks .storepass .keypass ~/openam/openam/
```
(Optional) If you have an authentication chain configured with the Persistent Cookie module, perform the following steps:
1. Log in to the OpenAM console as an administrative user, for example, amadmin.
2. Navigate to Realms > Realm Name > Authentication > Settings > Security.
3. Change the value in the Persistent Cookie Encryption Certificate Alias field from test to newkey.
4. Save your changes.
(Optional) In a multi-server environment, every server has its own keystore file. Make sure key aliases and certificates are maintained in every server by doing the same changes in all, or copying over the keystore and the .keypass and .storepass files.
Restart the OpenAM server or servers affected by the configuration changes to use the new keystore and encrypted password files.
Log in to the OpenAM console as administrator, for example, amadmin.
Replace the test key alias in the features in use, for example:
1. If you have already configured a SAML v2.0 identity provider, navigate to Federation > Provider Name > Assertion Content > Signing and Encryption, and then edit the signing key certificate alias.
  
  Save your changes.
2. Navigate to Configure > Server Defaults > Security > Key Store and replace the test key alias in the Certificate Alias property for SAML v1.x usage.
(Optional) (Optional) Self-signed keys are not automatically recognized by other entities. If you created new self-signed key aliases, you must share them as described in "To Share Self-Signed Certificates".
(Optional) (Optional) Share updated metadata with other entities in your circle of trust as described in "Configuring Identity Providers, Service Providers, and Circles of Trust".

To Change OpenAM Default User Self-Service Key Aliases

User self-service requires a key pair for encryption and a signing secret key to be available before configuring any of its features.

OpenAM provides the demo selfserviceenctest key alias for encrypting, and the demo selfservicesigntest signing secret key alias.

The steps in this procedure cover how to change the demo key aliases for different keys. This procedure assumes that you will not create a new keystore. If you need to create a new keystore and replace the default test key alias as well, see "To Change OpenAM Default test Signing Key " before continuing with this procedure.

Perform the following steps:

Back up the $HOME/openam/openam/keystore.jceks file.

Acquire a new key from your certificate authority, or generate new self-signed keys. The password of the new keys for the user self-service features must match the passwords of those keys already present in the keystore and configured in Configure > Server Defaults > Security > Key Store > Private Key Password File.

For this example, the step generates a self-signed key for encryption for example purposes, and a new signing secret key to an existing keystore, but you could also import the keys to the keystore.

Create the new self-signed encryption key alias:

$ cd ~/openam/openam/
$ keytool \
  -genkeypair \
  -alias newenckey \
  -keyalg RSA \
  -keysize 2048 \
  -validity 730 \
  -storetype JCEKS \
  -keystore keystore.jceks
  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 <newenckey>
  (RETURN if same as keystore password):
  Re-enter new password:

Create the new signing secret key alias:

$ cd ~/openam/openam/
$ keytool \
  -genseckey \
  -alias newsigkey \
  -keyalg HmacSHA256 \
  -keysize 256 \
  -storetype JCEKS \
  -keystore keystore.jceks
  Enter keystore password:
  Enter key password for <newsigkey>
  (RETURN if same as keystore password):
  Re-enter new password:

(Optional) In a multi-server environment, every server has its own keystore file. Make sure key aliases and certificates are maintained in every server by doing the same changes in all, or copying over the keystore and the .keypass and .storepass files.
Restart the OpenAM server or servers affected by the configuration changes.
Configure user self-service to use the new keys. For more information, see "To Configure Self Service Key Aliases".
(Optional) (Optional) The passwords for the user self-service key aliases must match the password of those key aliases already present in the keystore. If you only have SAML v2.0 keys with their own password files, you need to generate an encrypted password file for the user self-service keys. For more information, see "To Encrypt Keystore Passwords".

1. 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`.