Configuring AM's Container 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.

1. Stop Apache Tomcat.

2. Ensure you have a keystore containing the appropriate certificates:

   1. (Optional) 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

   2. 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'

3. 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.

4. Start Tomcat.

5. 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.

   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.

6. Deploy and configure AM.

7. (Optional) To share the self-signed certificate in your container with other applications or servers, see "To Share Self-Signed Certificates".

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: {amDemoPwd}" \
--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: {amDemoPwd}" \
--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.^[1] The following steps demonstrate how to import a self-signed certificate into the Java cacerts store:

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

2. 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