Certificate Configuration for the Identity Applications

  • 7024998
  • 01-Feb-2021
  • 19-Jul-2021

Environment

Identity Applications 4.7.x
Identity Applications 4.8.x
Tomcat web applications using HTTPS in single-server, clustered or high-availability configurations
User Application / Role Based Provisioning Module (RBPM)
One SSO Provider (OSP)
Certificate signed by internal eDirectory CA or 3rd party CA

Situation

The installation process for the IDApps will configure certificates using the Identity Vault server's IP address, by default. The default certificates will work in a distributed setup for most environments, but will need to be re-configured after the configure.sh script completes in most cases. The osp.jks and tomcat keystores should be recreated using the DNS name of the IDApps server rather than the IP address of the IDVault.

There are common mistakes made and misconceptions about what certificates are needed in each of the keystores.

The following certificates & key / trust stores are used by the Identity Applications and Tomcat:
  • IDM truststore (default idm.jks)
  • Tomcat keystore (default tomcat.ks)
  • OSP / OAuth keystore (default osp.jks)

Resolution

Obtain Public Certificates of Trusted Applications

There are many different types of Applications / Services that IDM can integrate with.. Examples of common Applications or Services that would need to be imported into our Certificate Stores: the eDirectory LDAP server, eDirectory CA, load balancer / switch and any other public certificates for web applications that will access our services.

Repeat the following to obtain the public certificates of all trusted applications that need to be later imported into our certificate stores:

echo | openssl s_client -connect <ADDRESS>:<PORT> | openssl x509 -outform PEM > <FILENAME/APPLICATION-NAME>.der

Example:

echo | openssl s_client -connect abc.xyz.com:443 | openssl x509 -outform PEM > example.der

Import Public Certificates into Our Certificate Stores

With the above retrieved public certificates from trusted applications, please proceed to import into Our Certificate Stores.

IDM truststore

default idm.jks

This truststore is a replacement for the JRE's cacerts. The cacerts truststore ships with over 100 default certificates imported for reference to trusted Certificate Authorities. The idm.jks is a replacement for this truststore to make administration easier and needs to have all signed certificates imported that will be in communication with the IDApps Tomcat service. The eDirectory LDAP server, eDirectory CA, load balancer / switch and any other public certificates for web applications that will access the UA provisioning services need to be imported (i.e. Reporting Module, Identity Governance, SSPR , etc)

  1. Discover the path to where the truststore is configured by finding the following configuration parameters in ./tomcat/conf/ism-configuration.properties:

    DirectoryService/realms/jndi/params/KEYSTORE_PATH = /opt/netiq/idm/apps/tomcat/conf/idm.jks com.netiq.idm.audit.cef.tls-keystore = /opt/netiq/idm/apps/tomcat/conf/idm.jks
  2. Please import ALL the Trusted Application Public Certificates, below is an example for importing a single certificate:

    /opt/netiq/common/jre/bin/keytool -import -alias applicationName -file application.der -keystore idm.jks

    Note: Repeat the above for ALL Trusted App Public Certificates.

  3. Generating new idm.jks
    Note: Requires exported Org CA / root signing cert.
    /opt/netiq/common/jre/bin/keytool -import -trustcacerts -alias <ALIAS> -file <ROOT_CA>.der -keystore idm.jks
    Example:
    /opt/netiq/common/jre/bin/keytool -import -trustcacerts -alias eDir_CA -file idvault.der -keystore idm.jks

Tomcat keystore

default tomcat.ks

This keystore is used to enable SSL / HTTPS for the Tomcat web service and allow secure connections from the end-user browsers to IDApps. This keystore needs to be configured in both server.xml and ism-configuration.properties. The tomcat.ks needs to include the Tomcat private key and signing CA cert in a chain, as well as the signing CA public cert itself. The Tomcat keystore needs to be created with the -genkey command and then CSR created from the PrivateKeyEntry that is present. Once the CSR is signed by eDir or 3rd party CA, the public CA cert (followed by any public intermediate CA certs) needs to be imported first, and finally the signed tomcat.der using the same alias ("tomcat" in my examples) in order to create the certificate chain properly. After the Tomcat web cert is chained and all CA certs are present, the load balancer certificate can also be imported to tomcat.ks and idm.jks.

  1. Discover the path to where the keystore is configured by finding the following configuration parameters in ./tomcat/conf/ism-configuration.properties:

    com.netiq.idm.osp.ssl-keystore.file = /opt/netiq/idm/apps/tomcat/conf/tomcat.ks
    And additionally, verify the same keystore path in the server.xml ‘Connector’ parameter:
    <Connector port="8543" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" maxHttpHeaderSize="65536" SSLEnabled="true" scheme="https" secure="true" clientAuth="false" sslProtocol="TLSv1.2" keystoreFile="conf/tomcat.ks" keystorePass="novell" sslEnabledProtocols="TLSv1.2" />

  2. Generating new key and keystore. Please select one of the following options:

    1. Self-signed Certificate:
      • (conditional) With IDM 4.8.x (Without SAN)
        • Generate the new tomcat.ks:
          keytool -genkey -alias tomcat -keyalg RSA -keystore tomcat.ks -validity 3650 -keysize 2048 -dname "CN=abc.xyz.com" -keypass changeit -storepass changeit -storetype PKCS12
        • Create CSR from private key:
          keytool -certreq -alias tomcat -file tomcat.csr -dname "CN=abc.xyz.com" -keystore tomcat.ks -keypass changeit -storepass changeit
      • (conditional) With IDM 4.6.x and 4.7.x(With SAN)
        • Generate the new tomcat.ks:
          keytool -genkey -alias tomcat -keyalg RSA -keystore tomcat.ks -validity 3650 -keysize 2048 -dname "CN=ua.edavis.lab" -ext san=ip:10.1.1.4,dns:ua.edavis.lab -keypass novell -storepass novell -storetype PKCS12
        • Create CSR from private key:
          keytool -certreq -alias tomcat -file tomcat.csr -dname "CN=ua.edavis.lab" -ext san=ip:10.1.1.4,dns:ua.edavis.lab -keystore tomcat.ks -keypass novell -storepass novell
      • With the desired Organization Certificate Authority (CA), sign the CSR to generate the public certificate. For example, the following steps are provided to sign the CSR with the eDirectory CA:
        • Copy the CSR generated above to the workstation where signing will occur.
        • iManager > Roles and Tasks > NetIQ Certificate Server > Issue Certificate
        • Select the CSR > Select 'Custom' for all options, no other selections > Set Validity period > Save
        • Copy the signed public certificate (e.g. tomcat.der) to the IDApps server.
      • Obtain the CA Certificate and any intermediate certificate files that form the chain. The following steps are provided for the eDirectory CA:
        • iManager > Roles and Tasks > NetIQ Certificate Access > Server Certificates
        • Select radio next to LDAP certificate > Export
        • Drop down to CA cert and Save as a .der file
        • Copy the Exported CA Certificate to the IDApps server.
    2. Wildcard Certificate:

      With the following provided by CA:
        * server.key - your certificate's private key
        * server.crt - your certificate
        * inter.crt - the intermediate CA that signed your certificate
        * root.crt - the root CA that signed the intermediate CA

      • First, concatenate the CA certs, make sure the intermediate CA goes first:
        $ cat inter.crt root.crt > chain.crt
      • Next, export the pkcs12 file:
        $ openssl pkcs12 -export -chain -inkey server.key -in server.crt -name "server" -CAfile chain.crt -out server.p12
      • Now, use keytool to verify:
        $ keytool -list -v -storetype pkcs12 -keystore server.p12
      • When cacerts.cer (chained certificate) is available, extract keys to obtain individual certs shown above, in order to create .p12 keystore:
        $ openssl pkcs12 -in <filename.pfx> -cacerts -nokeys -chain | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > <cacerts.cer>

    Extract Private / Public keys from PFX file (PFX files are in PKCS#12 format - they include certificate and private key both):
    • Copy your.pfx to system with OpenSSL.
    • Export the private key: openssl pkcs12 -in your.pfx -nocerts -out key.pem -nodes
    • Export CA chain: openssl pkcs12 -in your.pfx -cacerts -nokeys -chain -out ca_cert_chain.cer
    • Export the certificate: openssl pkcs12 -in your.pfx -nokeys -out server.crt
    • Remove the passphrase from the private key: openssl rsa -in key.pem -out server.key

  3. Importing Signed Public Certificate and any CA / Intermediate Certificates:
    Note: The order of import is critical to form a proper certificate chain.
    • Import the CA Certificate:
      keytool -import -trustcacerts -alias idvca -keystore tomcat.ks -file rootCA.der -storepass changeit -noprompt
    • (conditional) Import any Intermediate Certificates in the proper chain order:
      keytool -import -trustcacerts -alias idvca -keystore tomcat.ks -file intermediate.der -storepass changeit -noprompt
    • Import the Signed Tomcat Public Key:
      keytool -import -alias tomcat -keystore tomcat.ks -file tomcat.der -storepass changeit -noprompt
  4. (conditional) If a load balancer / switch is being used and is issuing a separate web certificate to the end-users, it is required to import the load balancer's public certificate:

    /opt/netiq/common/jre/bin/keytool -import -alias loadbalancer -file loadbalancer.der -keystore tomcat.ks

OSP / OAuth keystore

default osp.jks

This keystore should have a single, PrivateKeyEntry present and is used as key-signing material for the SAML sessions created by the SAML method in eDirectory. When Tomcat is running in a cluster configuration, the OSP keystore needs to be created on the 1st node and then copied over to each of the others in the same cluster.

ism-configuration.properties parameter(s) for osp.jks:

com.netiq.idm.osp.oauth-keystore.file
  1. Do not import Trusted Application Publicate Certificates to OSP / OAuth keystore.

  2. Generate the new osp.jks:
    keytool -genkey -keyalg RSA -keysize 2048 -keystore osp.jks -storepass changeit -keypass changeit -alias osp -validity 3650 -dname "cn=mydnsname" -storetype PKCS12
    Note: If you are upgrading, changing your keystore type from what it was in the previous version will require an update in the ism-configuration.properties or configupdate.sh. The configupdate.sh utility will not save unless the Authentication Keys section of the Auth tab is updated with the correct keystore type. 

  3. (conditional) If SSPR is integrated with OSP, Bypass SSO/OSP and Clear / Import SSPR OAuth Certificate:

    Configuration Editor -> Settings -> Single Sign On (SSO) Client -> OAuth
    E.g. https://www.example.com/sspr/private/Login?sso=false

     See Screenshot

    'Clear' and then 'Import From Server' to update SSPR configuration - OAuth Server Certificate

Additional Information

Cluster Information

**After the first node is working properly and the cluster is ready to be configured, copy the ism-configuration.properties and osp.jks from node 1 to all other nodes**

CONFIGURE TOMCAT CLUSTER IN SERVER.XML (The following is commented out by default):

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"/>

UPDATE OSP HOST ADDRESS IN TOMCAT/BIN/SETENV.<SH/BAT>:

-Dcom.netiq.idm.osp.client.host=abc.xyz.com

Additional Commands & Options

EXPORT JAVA PATH (add to /etc/profile or .bashrc for permanent export - run 'source /etc/profile' for current terminal session to load)

export JAVA_HOME="/opt/netiq/common/jre"
export PATH=$JAVA_HOME/bin:$PATH

CREATE NEW IDM.JKS WITH IDV.DER (Will createidm.jks - Need to import contents of tomcat.ks after using -importkeystore command)

keytool -import -trustcacerts -keystore idm.jks -storetype JKS -alias idvca -file idv.der -storepass changeit -noprompt

SSPR setting 'Root Certificate Only' - Cert Validation Mode
https://imgur.com/k9O0Yn8

Documentation Resources

Tomcat 9 Documentation - Clustering/Session Replication How-To
https://tomcat.apache.org/tomcat-9.0-doc/cluster-howto.html

Identity Applications 4.8 Documentation - Configuring OSP and SSPR for Clustering
https://www.netiq.com/documentation/identity-manager-48/setup_linux/data/t46ib9n6933s.html

External Resources - Extracting Keys

StackExchange - Extracting CA certificate chain from PFX
https://unix.stackexchange.com/questions/367220/how-to-export-ca-certificate-chain-from-pfx-in-pem-format-without-bag-attributes

DigiCert TID - Tomcat configurations
https://www.digicert.com/kb/csr-ssl-installation/tomcat-keytool.htm#ssl_certificate_install

OpenSSL Doc
http://chadstechnoworks.com/wptech/os/how_to_extract_root_and_intermediate_certificates_from_client_certificate.html

Feedback service temporarily unavailable. For content questions or problems, please contact Support.