Document toolboxDocument toolbox

Integrate Identity Manager with EJBCA connector

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

 Prerequisites

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
  1. Create a file called ejbca.properties. There are two options:

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

       

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

  1. Log in to Identity Manager Admin.
  2. Go to Home > Certification Authorities (CA) and click New.
  3. Enter Name of the EJBCA connector. Click Save+Edit.

  4. Select Connection type EJBCA.
  5. Click Upload and upload the zip file created under "Preparations" above.

  6. Set the desired CMP endpoint as CA host, as mentioned under "Preparations" above.

  7. Set the Signing password to:

    1. the shared secret, if you set useHmac=true

    2. otherwise set it to the client auth P12 password.

  8. Click Save to save the configuration and go to the Details tab.
  9. Click Search on the right hand side. All EJBCA CA certificate types are fetched and all configurable certificate types are shown. Click Apply.
  10. Click Testing. All connections should be green.
  11. 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 typeRFC-5280 reason for CMP
unspecifiedRFC-5280unspecified
keyCompromiseRFC-5280keyCompromise
aACompromiseRFC-5280aACompromise
cACompromiseRFC-5280cACompromise
supersededRFC-5280superseded
removeFromCRLRFC-5280removeFromCRL
certificateHoldRFC-5280certificateHold
affiliationChangedRFC-5280affiliationChanged
privilegeWithdrawnRFC-5280privilegeWithdrawn
cessationOfOperationRFC-5280cessationOfOperation
lockedIdentity Manager onlyunspecified
inactiveIdentity Manager onlyunspecified
temporary.inactiveIdentity Manager onlycertificateHold
activeIdentity Manager onlyremoveFromCRL
validIdentity Manager onlyremoveFromCRL
 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:

Troubleshooting

 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



Copyright 2024 Technology Nexus Secured Business Solutions AB. All rights reserved.
Contact Nexus | https://www.nexusgroup.com | Disclaimer | Terms & Conditions