Secure connections to the AM container

There are many ways to deploy and configure your environment for AM, but we recommend that you enforce HTTPS connections to AM. For more information about securing AM, see Security.

The container where AM runs requires a certificate to set up secure connections. You can install either CA-signed or self-signed certificates in the container where AM runs, although you should have in mind that you will need to configure your applications to trust your self-signed certificates.

The following is an example about how to configure Apache Tomcat for HTTPS:

Configure Apache Tomcat for HTTPS

There are several ways of completing the tasks ahead, and it is beyond the scope of this document to explore them all. If this procedure does not suit your environment, refer to your CA vendor documentation, the keytool command documentation, or Java container documentation for more information.

Stop Apache Tomcat.

Ensure you have a keystore containing the appropriate certificates:

If you have CA certificates, import them in a new keystore using the keytool command. For example, if you have root, intermediate, and primary certificates, import them in the same keystore you used when generating your certificate signing request (CSR):

$ keytool -importcert -alias root -file myrootCA.cert \
-keystore /path/to/tomcat_keystore.pfx -storetype PKCS12
$ keytool -importcert -alias intermediate -file myintCA.cert \
-keystore /path/to/tomcat_keystore.pfx -storetype PKCS12
$ keytool -importcert -alias mysite.example.com -file mypriCA.cert \
-keystore /path/to/tomcat_keystore.pfx -storetype PKCS12

If you need a self-signed certificate, create a new self-signed key pair with the keytool command.

For example:

$ cd /path/to/tomcat/conf/
$ keytool -genkey -alias openam.example.com -storetype PKCS12 -keyalg RSA -validity 730 \
  -keysize 2048 -keystore tomcat_keystore.pfx -dname 'CN=openam.example.com' -ext 'san=dns:openam.example.com'

Create an SSL connector configuration in Apache Tomcat’s conf/server.xml configuration file, and specify your keystore file, type, and password.

Note that there are different types of SSL connectors, and that implementation details may change across Tomcat versions. This example creates a JSSE connector in Tomcat as provided as part of the Java runtime:
```
<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
 maxThreads="200" SSLEnabled="true" scheme="https" secure="true"
 keystoreFile="/path/to/tomcat_keystore.pfx"
 keystoreType="PKCS12" keystorePass="keystore_password"
 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 Apache Tomcat on port 8443 over HTTPS.

If you used self-signed certificates, your browser would not trust the certificate, because the certificate is self-signed and not signed by any of the CAs stored in your browser.

Figure 1. Unknown Certificate

If you recognize the subject and issuer of your certificate, and so can choose to trust the certificate, save it into your browser’s trust store.
Deploy and configure AM.
To share the self-signed certificate in your container with other applications or servers, see Share self-signed certificates.

How you configure the containers where AM 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 AM, AM 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 AM.

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 AM RESTful API without having the client recognize the self-signed server certificate:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
    curl: (60) Peer certificate cannot be authenticated with known CA certificates
}

The curl command performs SSL certificate verification by default, using a "bundle" of CA-signed public keys. If the default bundle file is not 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 would like to turn off curl’s verification of the certificate for test purposes only, use the --insecure option.

$ curl \
--request POST \
--insecure \
--header "Content-Type: application/json" \
--header "X-OpenAM-Username: demo" \
--header "X-OpenAM-Password: Ch4ng31t" \
--header "Accept-API-Version: resource=2.0, protocol=1.0" \
'https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate'
{
  "tokenId":"rMLhJjWVo…MAAlMxAAA.*",
  "successUrl":"/openam/console",
  "realm":"/alpha"
}

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 truststore used by the client. By default, Java applications can use the $JAVA_HOME/lib/security/cacerts store. The default password is changeit.⁽¹⁾

The following steps 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 \
-storetype JCEKS
-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/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

⁽¹⁾ 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.

Access Management 7.3.1

Secure connections to the AM container

Configure Apache Tomcat for HTTPS

Share self-signed certificates