• 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

   URL: https://<idm_operator>:<port>/ws/certificate/register/<certificateCoreTemplate>[/<processDefinitionId>]?tenantId=<tenantId>

   If you want to authenticate to Identity Manager using HTTP basic authentication, use the port that does not require client authentication.

   <certificateCoreTemplate> stands for the core template the certificate will be stored as.

   If you want Identity Manager to execute a process on the certificate after persisting it, specify an optional processDefinitionId.

   Payload: Cert

   Encoding: Base64

   Content type: application/pkix-cert

   username/password: you may set an Identity Manger Manager internal user username/password or preferably leave this blank and use certificate based authentication.

2. Create a certificate procedure - Create certificate procedure in Certificate Manager
   1. Add the distribution rule you created previously
3. Create a token procedure - Create token procedure in Certificate Manager
   1. Add the certificate procedure you just created

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

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. Open config/da.conf for editing. See an example of the file below:

   Code Block
   title Example - set key store
   ;; ;; HTTP Push SSL content ;; ;; Key store settings cm.da.http.ssl.keyStoreType = pkcs12 cm.da.http.ssl.keyStore = </my/AbsolutePathTo/ClientCertificate.p12> cm.da.http.ssl.keyStorePassword = <passwordToP12>

   
   

3. On the Identity Manager Operator side, make sure that the URL, configured in the Distribution rule accepts a client certificate.

Just set a username/password of an Identity Manager internal user in the distribution rule. Also you need to make sure that the URL to connect to Identity Manager Operator does not require a client certifciate.

Optionally, but highly recommended, Identity Manager's TLS server certificate can be validated also on Certificate Manager side. Therefore, a corresponding truststore can be configured. 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. Open config/da.conf for editing. See an example of the file below:

   Code Block
   title 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 = </my/absolutePathTo/truststore.jks> ;cm.da.http.ssl.trustStorePassword = <PasswordToTruststore>

   
   

Optionally, a BPMN process can be executed on the certificate. Identity Manger will first persist the certificate core object. After that, if a processDefinitionId is specified in the distribution rule URL in the Certificate Manager, the specified process will be executed with the persisted certificate. Take care of the following:

• The user the Certificate Manager logs in with must have the permission to execute the process.
• The process should not be interactive.
• It is recommended that the process runs asynchronously, so that Identity Manger can immediately respond to Certificate Manager.
  
• If the process throws an exception or ends in an Error End Event, the certificate will remain persisted in Identity Manger and Certificate Manager will get an OK response (in order not to retry the distribution). It is the responsibility of the process to make sure the error can somehow be handled.
  
• A CertificatePublicationException containing the certificateID will be visible in the log if any throwable is thrown in the thread that handled the certificate registration REST call. This will, for example, be the case, if the process does not exist. Remember that as soon as a task runs asynchronously (as recommended), it will run in a separate thread.