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 via
```
caTokenProcedureImportCert=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

Preparations

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:
1. always:
  1. ejbca.properties (the name is fixed)
2. if using HTTPS, then also:
  1. ejbcaserver.crt (this is an example, the name can vary)
3. if using client auth, then also:
  1. officer.p12 (this is an example, the name can vary)

Configure EJBCA connector

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:
1. the shared secret, if you set useHmac=true
2. 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.

Revocation reasons

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

Limitations

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:
1. Reconfigure EJBCA and its associated software to make client auth optional on the CMP endpoints
2. Use client cert auth instead of HMAC
3. 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:
1. Configure EJBCA with a new (intermediate) cert that uses a compatible DN, OR
2. Reconfigure CM as follows: (which is not always possible, as CM does not support certain attributes like UID)
  1. 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
  2. Restart CM services for the new format to become available.
  3. 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

Useful links

Browser not supported