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

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

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.

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

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

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

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.

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.

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.
   
   

• Identity Manager will return the following HTTP response codes:

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

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

...
    </Appenders>
    <Loggers>
        <Logger name="de.vps.act.explorer.webservice.certificate.CertificateServiceRest_CRL" level="error" additivity="true">
            <AppenderRef ref="ASYNC_MAIL"/>
        </Logger>
...
    </Loggers>
</Configuration>

• 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.