Integrate Identity Manager with EJBCA connector
- Ann Base (Deactivated)
- Ylva Andersson
- Josefin Klang (Deactivated)
- Karolin Hemmingsson (Unlicensed)
This article is valid for Smart ID 20.11 and later.
This article describes how to connect to the EJBCA certificate authority from Smart ID Identity Manager. For the supported certificate authorities, see IDM 23.10.3 - Requirements and interoperability.
Required files and details
- Address of the Certificate Management Protocol (CMP) alias' endpoint (for example, https://my.ejbca.server/ejbca/publicweb/cmp/myCmpAlias)
- Names of all the certificate profiles configured in EJBCA
- When using HMAC: Shared secret from CA config (if configured globally) or CMP config (if customized for alias)
- When using client auth: P12 file containing admin keypair and its password (for example, officer.p12)
- When using HTTPS endpoint (this is recommended and may require client cert auth): server certificate of EJBCA (for example, ejbcaserver.crt)
Plain requests
If you need plain requests, you must also configure Certificate Manager (CM) and the CM connector for key archival and recovery. The following details are required:
- Name of Identity Manager CA configuration for CM
- Name of CM recovery token procedure
- CM must have key archival token procedures with key generation supported by the the respective EJBCA profiles (for example, RSA 4096 bit)
CM must have an import CA with configured P10 import token procedure for import of EJBCA certificates
Set this in the CM connector configuration file nexus_cm.properties viacaTokenProcedureImportCert=NameOfTheImportProcedure
This import CA must have a dummy self-signed keypair and have the same subject DN as the EJBCA issuing CA.
Multiple different issuers
If there are multiple issuers, you need the following per issuer:
Import CA config in CM
You might have to create a new certificate format file for CM, which allows you to match the subject DN of the issuing EJBCA cert in attributes and order, in case the CM's default config does not fit. See "HTTPS works with client auth but fails with HMAC" under Troubleshooting below for details.
CM connector configuration, specifying the import token procedure
EJBCA connector configuration, referencing the CM configuration as key archive
Step-by-step instruction
Create a file called ejbca.properties. There are two options:
In case of HMAC, specify like this (do not specify absolute or relative paths, just the filenames):
ejbca.properties (with HMAC)useHmac = true # optional when using http #serverCert = ejbcaserver.crt # add profiles as needed certProfiles = SOME_KEY_ARCHIVAL_PROFILE,SOME_P10_PROFILE,ANOTHER_P10_PROFILE,EJBCA_Recovery # these are optional if we don't use key archival/recovery keyArchive=NameOfCMConfigInPrimeForEJBCAKeyArchivalAndRecovery ejbcaToCMCertTemplateMapping=EJBCA_Recovery=RecoveryTokenProcInCM;SOME_KEY_ARCHIVAL_PROFILE=KeyArchivalTokenProcInCM
Or in case of client auth, specify like this:
ejbca.properties (with client auth)# optional, as false is default # useHmac = false clientCert = officer.p12 serverCert = ejbcaserver.crt # add profiles as needed certProfiles = SOME_KEY_ARCHIVAL_PROFILE,SOME_P10_PROFILE,ANOTHER_P10_PROFILE,EJBCA_Recovery # these are optional if we don't use key archival/recovery keyArchive=NameOfCMConfigInPrimeForEJBCAKeyArchivalAndRecovery ejbcaToCMCertTemplateMapping=EJBCA_Recovery=RecoveryTokenProcInCM;SOME_KEY_ARCHIVAL_PROFILE=KeyArchivalTokenProcInCM
- Create a ZIP file containing in its root the following files:
- always:
ejbca.properties (the name is fixed)
if using HTTPS, then also:
ejbcaserver.crt (this is an example, the name can vary)
if using client auth, then also:
officer.p12 (this is an example, the name can vary)
- always:
To configure the EJBCA connector into Identity Manager Admin:
- Log in to Identity Manager Admin.
- Go to Home > Certification Authorities (CA) and click New.
Enter Name of the EJBCA connector. Click Save+Edit.
- Select Connection type EJBCA.
Click Upload and upload the zip file created under "Preparations" above.
Set the desired CMP endpoint as CA host, as mentioned under "Preparations" above.
Set the Signing password to:
the shared secret, if you set useHmac=true
otherwise set it to the client auth P12 password.
- Click Save to save the configuration and go to the Details tab.
- Click Search on the right hand side. All EJBCA CA certificate types are fetched and all configurable certificate types are shown. Click Apply.
- Click Testing. All connections should be green.
- Click Save.
If you want to use plain requests or recovery, you also need to set up the CM connector, see Integrate Identity Manager with Smart ID Certificate Manager.
The following certificate states for revocation requests are supported:
Identity Manager cert status (case-insensitive) | Status type | RFC-5280 reason for CMP |
---|---|---|
unspecified | RFC-5280 | unspecified |
keyCompromise | RFC-5280 | keyCompromise |
aACompromise | RFC-5280 | aACompromise |
cACompromise | RFC-5280 | cACompromise |
superseded | RFC-5280 | superseded |
removeFromCRL | RFC-5280 | removeFromCRL |
certificateHold | RFC-5280 | certificateHold |
affiliationChanged | RFC-5280 | affiliationChanged |
privilegeWithdrawn | RFC-5280 | privilegeWithdrawn |
cessationOfOperation | RFC-5280 | cessationOfOperation |
locked | Identity Manager only | unspecified |
inactive | Identity Manager only | unspecified |
temporary.inactive | Identity Manager only | certificateHold |
active | Identity Manager only | removeFromCRL |
valid | Identity Manager only | removeFromCRL |
These are the limitations:
- Verification of the PKCS#10 self-signature ("proof of possession") works only within the connector and for RSA keys only.
- Make sure to allow skipping proof of possession validation in the CMP alias config.
- Let EJBCA provide the CA certs, that is, do not add external root certificates from a file, since this is deprecated.
- All credentials have to be configured in the CA config itself. There are no means to override them within the request.
- Nexus CM is used for key archival and recovery, since an externally hosted EJBCA service may not offer these.
- Certain certificate attributes do not work with EJBCA:
- Avoid having multiple RDNs of the same type (for example, OU=this, OU=that) in the DNs of your certificate requests as EJBCA rejects these.
- POSTALADDRESS is not compatible with EJBCA as it expect a different encoding format.
- See https://doc.primekey.com/ejbca/ejbca-operations/ejbca-ca-concept-guide/end-entities-overview/end-entity-profiles-overview/end-entity-profiles-fields
Troubleshooting
I cannot view all EJBCA profiles to find out how they are configured
- Reason: You are likely using an older version of EJBCA which does not have the "View" option in addition to "Edit", which does not work on built-in profiles.
- Workaround: Clone the profile you are interested in into a temporary copy and click "Edit" on the clone to view its settings.
- Solution: Update to a newer version.
HTTPS works with client auth but fails with HMAC
- Reason: Your EJBCA instance might have its HTTPS endpoints configured to require client auth on the CMP endpoints (ejbca/publicweb/cmp/*) (this might have been done via application server and/or embedded Tomcat and/or reverse proxy)
- Solution: You have the following options:
- Reconfigure EJBCA and its associated software to make client auth optional on the CMP endpoints
- Use client cert auth instead of HMAC
- Use HTTP (not recommended)
Failed import during key archival
Reason: If key archival fails with a message like this...
Aug 09, 2019 8:25:47 AM com.smarttrust.cm.sdk.Request logError SEVERE: ImportCertificateRequest Server error: 7, Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE Aug 09, 2019 8:25:47 AM com.smarttrust.cm.sdk.Request logException SEVERE: ImportCertificateRequest.execute() Server error: 7, Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE com.smarttrust.cm.sdk.RequestException: Certificate not issued by CA: cn=ManagementCA,o=EJBCA Sample,c=SE at com.smarttrust.cm.sdk.ProcedureRequest.createResponseError(ProcedureRequest.java:58)
... then most likely the DN attribute order of the key archival CA cert differs from the order in the issuing EJBCA cert.
- Solution: Either you:
- Configure EJBCA with a new (intermediate) cert that uses a compatible DN, OR
- Reconfigure CM as follows: (which is not always possible, as CM does not support certain attributes like UID)
First you have to create a new certificate format from which you are allowed to match the subject DN of the EJBCA cert properly (adjust SubjectNameSpaceOrder and IssuerNameSpaceOrder as needed), for example:
C:\Program Files\Nexus\Certificate Manager\server\config\certformats\SELF-SIGNED CA-CERT EJBCA.conf[Info] FileFormatVersion=1 Description=For EJBCA. Self signed CA certificate format. Creates a PKIX compatible CA certificate with the extensions BasicConstraints (critical, CA=true, no pathLength) and SubjectKeyIdentifier. The subject and issuer fields are encoded as either PrintableString or UTF8String. It's recommended to avoid national characters. A SubjectAltName extension with an email address is optionally created. Type=ca Visible=true include = rfc5280CA.conf [FormatDefinitionFields] SubjectNameSpaceOrder=cn,dmd,o,organisationidentifier,ou,c IssuerNameSpaceOrder=cn,dmd,o,organisationidentifier,ou,c
- Restart CM services for the new format to become available.
- Create EJBCA Key Archive CA in CM which uses the new format.
Using certificate templates EncHardCodedValues(P10) fail with EJBCA
- Reason: The cert attributes in these templates are partially incompatible with EJBCA. For example, the e-mail address is incorrectly formatted, multiple OU attributes are not supported, etc.
- Solution: Check the log messages and adjust the attributes accordingly.
Additional information
Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions