Use of certificates with Entuity
To get certificates into Entuity
Introduction:
The certtool utility in Entuity stops the default Java keystore and the certificates within it (entuity_home/install/JRE/lib/security/cacerts) from being lost when the JRE is upgraded in a patch or upgrade. The certtool utility creates a second store that is not deleted by JRE upgrades. Running configure after a patch or upgrade will automatically merge back in the certificates into the new version of Entuity.
certtool should be used alongside keytool when patching and upgrading:
- use keytool to export existing certificates before patching Entuity.
- use certtool to reimport the certificates into the new version of Entuity.
Entuity recommends that you always use certtool when required to import certificates for LDAP integrations (and RESTful API integrations that are called via Groovy scripts). certtool is only used to import certificates for LDAP authentication and when an SSL connection is required for TSOM integration. It is not required for SSL client connections to the Entuity web server.
Use of certificates with Entuity:
Certificates are widely used to pass trust between various applications. In Java, the JRE manages a set of certificates - in Entuity, these are installed in entuity_home/install/JRE/lib/cacerts.
For Entuity users, the core use cases are:
- if you are using LDAP over SSL (LDAPs)
- if you are using SSO with BMC TrueSight
In these cases, Entuity is expected to 'share trust' with an external application without requiring that the user enters a password. The certificate is necessary, to ensure the Entuity server can verify that a given token supplied by the user's browser has been generated by a system that we can trust.
The certificates need to be exported by the LDAP/SSO administrator and copied on to the Entuity server. This is a manual process.
To get certificates into Entuity:
Use certtool to import your certificates into Entuity, because it will ensure that certificates are imported into both the Entuity trust store and the default JRE trust store.
To implement LDAPS on Entuity:
- Export your certificate file from the LDAP server.
- Copy the certificate file onto the Entuity server.
- Run certtool.
- Verify that certtool has added the cert to both keystores.
- In the Entuity web UI, log in as an admin user. Click Main Menu, then Administration. Click Account Management.
- In the LDAP section, add a new LDAP server. You will need to map at least one LDAP user (or group) to be in the Administrators' group. Once you have specified the parameters, click Apply LDAP Settings.
- The system will run a test connection to the LDAP server, and, if successful, restart the Entuity server.
- Refresh the page.
- Log in using a valid LDAP username/password.
Note: when configured for external authentication via LDAPs, ENA v18.0 upwards enforces hostname verification between certificates and the LDAP server. If your LDAP TLS certificates are non-compliant with hostname verification, then the LDAPs integrations will stop working after installing ENA v18.0.
Entuity recommend that users plan for new certificates before upgrading to ENA v18.0. If you are unable to rebuild certificates, Entuity recommend that you contact Entuity Support for details of how to handle non-compliant certifications.
When patching and upgrading:
When running ENA v17.0 and above:
- Upon patching, configure will merge your existing keys from the /etc/entuity_cacerts keystore into the new Java keystore without any user intervention.
When upgrading from an earlier version of Entuity to ENA v17.0:
- Export your keys using keytool.
- Upgrade and configure.
- Re-import your keys, using certtool instead of keytool.
- Restart Tomcat.
Actions allowed with certtool:
Usage: certtool <actions>, where allowed actions are:
-import -file <certificate file> -alias <certificate alias> [-entuityStorePass <password>] [-defaultStorePass <password>]
- Import the certificate file to both the Entuity trust store and the default JRE trust store. The Entuity trust store is located at entuity_home/etc/entuity_cacerts. The default JRE trust store is located at entuity_home/install/JRE/lib/security/cacerts.
- Specify an alias that is unique in both trust stores. The prefix entuity_ will be added to the alias. Passwords are optional - if missing, then the default password changeit will be used for both stores.
-delete -alias <certificate alias> [-entuityStorePass <password>] [-defaultStorePass <password>]
- Delete a certificate by its alias from both the Entuity trust store and the default JRE trust store. The specified alias shall not contain the prefix entuity_. Passwords are optional - if missing, then the default password changeit will be used for both stores.
-merge
- Merge the default JRE trust store with the Entuity trust store (which will run every time that configure runs).
- If the Entuity trust store does not exist, then exit immediately.
- If all certificates in the Entuity trust store already exist in the default JRE trust store, then do nothing.
- Otherwise, the Entuity trust store will be merged into the default JRE trust store, and the default JRE trust strore's password will be reset.
Comments
0 comments
Please sign in to leave a comment.