Push CRL from Certificate Manager to Identity Manager

• 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

      CODE

      ;;
      ;; 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

      CODE

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

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.

• Identity Manager will return the following HTTP response codes:

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

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