Skip to main content
Skip table of contents

Push certificates from Certificate Manager to Identity Manager

This article describes how to push certificates from Smart ID Certificate Manager to Smart ID Identity Manager.

In some cases, certificates are issued directly via Certificate Manager without involving Identity Manager. One typical use case is when certificates for servers, devices, workstations etc. are requested via Protocol Gateway, using the automation protocols (such as SCEP, ACME, EST or Windows-Autoenrollment). Also, in these cases, we want to inform Identity Manager about the new certificates so that Identity Manager can do the corresponding lifecycle management later on.

To keep Certificate Manager and Identity Manager in sync, the certificates can be pushed from Certificate Manager via a 'Distribution Rule' to a HTTPS endpoint to Identity Manager. The push to Identity Manager will contain the certificate itself, a corresponding Certificate Template that it will be mapped on in Identity Manager. and optionally a BPMN process that will be executed with the push, for example to link the certificate to certain assets in Identity Manager.

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

    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 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
Authenticate Certificate Manager

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.

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

    Example - set key store

    CODE
    ;;
    ;; 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.
Authenticate using HTTP Basic authentication

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.

Validate Identity Manager's TLS certificate

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:

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

In Identity Manager

Execute a process

Optionally, a BPMN process can be executed on the certificate. Identity Manager 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 Manager 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 Manager 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.
JavaScript errors detected

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

If this problem persists, please contact our support.