Skip to main content
Skip table of contents

Push CRL from Certificate Manager to Identity Manager

This article includes updates for Smart ID 22.10.

This article describes how to configure Smart ID Certificate Manager to push certificate revocation lists (CRLs) via REST endpoints to Smart ID Identity Manager.

Certificates issued via Identity Manager can be revoked directly by Certificate Manager without involving Identity Manager. In this case, Identity Manager shall be informed about the revoked certificates, so it can update their states.

This is done by pushing a CRL from Certificate Manager via a Distribution Rule to an HTTPS endpoint of Identity Manager. This will contain the CRL data and the tenant ID of the receiving Identity Manager tenant.

Identity Manager can handle both full CRLs and delta CRLs. So-called indirect CRLs, which are created on behalf of another CA, (that is, if the certificate issuer and the CRL issuer do not match) are also supported.

  • Identity Manager is installed
  • Certificate Manager is installed
  • Certificate Manager can reach the Identity Manager endpoint via an outgoing HTTPS connection

Step-by-step instruction

In Certificate Manager

Configure Certificate Manager
  1. Create a distribution rule - Create distribution rule in Certificate Manager with the following parameters:
    • Protocol: HTTP

    • User / Password: Leave both blank for client certificate authentication, otherwise enter credentials of an internal Identity Manager user.
    • URL: https://<idm_operator>:<port>/<webapp_path>/ws/certificate/crl?tenantId=<tenantId>

      If the application is deployed at the server root, <webapp_path> and the following '/' are absent.

      If you want to authenticate to Identity Manager using HTTP basic authentication (not recommended), use a port that does not require client certificate authentication, otherwise use a port that supports client certificate authentication.
    • Payload: CRL

    • Encoding: binary or Base64

      The Identity Manager endpoint also accepts PEM in addition to the two above encoding formats currently offered by Certificate Manager.

  2. Create a CRL procedure - Create CRL procedure in Certificate Manager
    • Add the distribution rule you created previously
Authenticate Certificate Manager

Certificate Manager must authenticate itself. There are two ways to do this: use a keypair or use HTTP Basic authentication. The keypair is recommended, as username/password is less secure.

Optionally, but strongly recommended, Certificate Manager will also check if it trusts Identity Manager's TLS certificate.

If you change anything in the configuration or in the key-/truststore, you must restart Certificate Manager.

Authenticate using a certificate

The keystore is mandatory. It must contain the keypair and certificate the Certificate Manager will use to authenticate to Identity Manager. Its issuer must be present in the truststore of the Identity Manager Operator application.

  1. Create an appropriate PKCS#12 container and store it on the Certificate Manager server machine.
  2. Configuration: (you may use absolute or relative paths. These are relative to the Certificate Manager installation directory, for example, C:\Program Files\neXus\Certificate Manager\server\)
    1. Open config/da.conf for editing.

      This is an example of that file:

      Example - set key store

      ;; HTTP Push SSL content
      ;; Key store settings
      cm.da.http.ssl.keyStoreType = pkcs12
      cm.da.http.ssl.keyStore = user.p12
      cm.da.http.ssl.keyStorePassword = password
Authenticate using HTTP Basic authentication

Set a username and password of an Identity Manager internal user in the distribution rule as described above in Configure Certificate Manager.

Validate Identity Manager's TLS certificate

As described in the configuration file's comments, the truststore is optional but recommended. It should contain the issuer of the Identity Manager server certificate.

  • When set, the Identity Manager server certificate will only be accepted if is was issued by a certificate contained in the truststore.
  • When not set, the Identity Manager server certificate will be accepted regardless of the issuer.
  1. Configuration (you may use absolute or relative paths. These are relative to the Certificate Manager installation directory, for example, C:\Program Files\neXus\Certificate Manager\server\)
    1. Open config/da.conf for editing.

      This is an example of that file:

      Example - specify server certificate

      ;; HTTP Push SSL content
      ;; Trust store settings.
      ;; All server certificates will be accepted if not specified.
      ;cm.da.http.ssl.trustStoreType = jks
      ;cm.da.http.ssl.trustStore = truststore.jks
      ;cm.da.http.ssl.trustStorePassword = changeit

In Identity Manager

Configure Tomcat

If you want Certificate Manager to authenticate using a certificate, you need a Tomcat connector configured for two-way TLS aka client certificate authentication. The issuer of the Certificate Manager client certificate must be present in the truststore used by Identity Manager and Tomcat.

If you want Certificate Manager to authenticate using HTTP Basic authentication, you need a Tomcat connector configured for TLS without client authentication.

Configure CRL Validation

Identity Manager validates each received CRL request, logs error messages and returns http status code 422 (UNPROCESSABLE_ENTITY) in case of CRL validation failure.

To enable successful CRL validation you need to import the CA certificate(s) that sign(s) the CRL(s) into the Identity Manager truststore.

Revocation reason mapping

You must configure revocation reasons in Identity Manager Operator before using this feature. Transitions must be aligned with the certificate state graph. Identity Manager validates the transition for each CRL entry based upon specified system property mapping and state graph.

Identity Manager logs error messages in case of any invalid transition and returns HTTP status code 500 (INTERNAL_SERVER_ERROR).

Follow these steps in Identity Manager Operator to open the revocation reason mapping settings:

  1. Go to the ADMIN page.
  2. Click Configure system properties.
  3. Select CA Revocation Reason Mapping.

This configuration is tenant-specific, but not stategraph-specific! It is highly recommended to use a common state graph for all certificate configs within one tenant.

Keep your certificate state graph as simple as possible to avoid ambiguities, as you can map from multiple Identity Manager states to the same revocation reason, but for the reverse mapping of revocation reason to Identity Manager state you have to pick a single value.

For example, if you have both inactive and locked as Identity Manager states and both map to the revocation reason unspecified, then you have to decide whether an incoming CRL entry with reason unspecified shall set the Identity Manager state to inactive or locked.
In such a case it is best to consolidate to a single Identity Manager state per relevant revocation reason.

CRL processing in Identity Manager
  • Identity Manager will return the following HTTP response codes:
Response CodeReasonError Resolution
200 (OK)Successn/a
CRL could not be parsed by Identity ManagerCheck your CRL data.
422 (UNPROCESSABLE_ENTITY)CRL signature verification failed Check in Identity Manager trust store whether the certificate of the CA that signed the CRL is present.

Error logging

REST errors from the above table are logged by the de.vps.act.explorer.webservice.certificate.CertificateServiceRest_CRL logger on error loglevel.

You can configure desired appenders for this logger in log4j2.xml (see Configure Log4j2 for Identity Manager).

log4j2.xml example: send mail for CRL errors in addition to normal logging

<?xml version="1.0" encoding="UTF-8" ?>
<Configuration monitorInterval="30">
        <SMTP name="MAIL" subject="Error Log" to="admin@mycompany" from="idm.logging@mycompany"
          smtpHost="localhost" smtpPort="25" bufferSize="50">

           <!-- sending mail is slow, so it is essential to make this asynchronous! -->
        <Async name="ASYNC_MAIL">
            <AppenderRef ref="MAIL"/>

        <Logger name="de.vps.act.explorer.webservice.certificate.CertificateServiceRest_CRL" level="error" additivity="true">
            <AppenderRef ref="ASYNC_MAIL"/>
  • Identity Manager will iterate over the CRL entries and fetch the corresponding certificate details from the Identity Manager database based upon the certificate serial number and issuer name.
    Identity Manager logs messages when no matching certificate entry was found in the Identity Manager database and continues processing the rest of the CRL entries.

    There are clear log messages (INFO level log) when certificate states are updated in the database and clear error messages in case of exceptions.
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.