7.7:documentation:modules_crt

Modules - Certificates [crt]

CRT module was designed to handle various certificate authority implementations via specific drivers. Currently, there is one driver implemented - the CAW driver that handles the communication with CAW certificate authority (bundled in the module).

Module consists of those basic parts:

  • GUI - Users can manage their certificates or request a new one via standard CzechIdM web GUI
  • Registration authority - When user requests for a certificate, the request is processed by appropriate driver.
  • Certificate store - users' certificates are stored in CzechIdM for future download or e.g. provisioning (send to other managed system)
  • Drivers - Driver implements mainly the communication mechanism between CzechIdM and CA (e.g. CAW or Microsoft CA). Currently CzechIdM provides the driver for CAW, others can be implemented on demand. If the request from registration authority does not contain CSR, driver creates it.
  • CAW - Our CA implementation based on openssl.
  • RESTful API - Standard communication API. Use it e.g. when users request for a new certificate via some external registration authority software.

 CRT module architecture

  • Generate - Generate a new certificate. The user must select a certification authority, a certificate type (Authentication, Signing, Encryption), and a password. The password will be required to open a downloaded storage with a private key and a user certificate. The password will be stored in the confidential storage in IdM. If the certificate generation is complete, password will be removed from the IdM.
  • Generate by CSR - Generate a certificate from an existing request (Certificate Signing Request). The user has a certificate request already generated in the CSR format. This request contains all the necessary information to generate. The user must only select authority and file with CSR request. In this case, it does not enter or store any password (the private part of the certificate already has the user with).
  • Renew - Extending the validity of an existing certificate. Extensions can only be made on a valid certificate.
  • Revocate - Certificate invalidation. For example, if the private part of the certificate is compromised, you must revoke the certificate to prevent further abuse.
  • Archivate - Certificate is archived ("soft delete"). Archived certificates cannot be renewed or revoked. They are still controlled for expiration (see long running tasks and notifications below).
  • Cancel request - Certificate request can be canceled, when request is in concept state.
  • Download certificate - Public and private (if exists) certificate can be downloaded. Private certificate can be downloaded just by certificate owner.

All certificates that IdM manages are stored in the certificate store. All operations over certificates (validation, download, notifications) are only performed over the certificates stored directly in the IDM.

In the certificate store, you can get the certificate in the following ways:

  • It is generated by the appropriate CA (see below).
  • Manually uploaded by the user via GUI. You can also upload certificates that are not managed by the certification authority within this module. In this case, only expiration is validated. Otherwise, the certificate is validated directly against the certification authority (for example, checking the CSR revocation).
  • Synchronized within identity synchronization (not implemented at this time).
  • Uploaded via REST api (the same as uploaded by user via GUI).
We supports upload in PEM and DER format. Downloaded (public) certificates are always in the PEM format.

Driver provides communication with an external CA. The certification authority can have any interface (REST api, Web service, Bash command, …) and very different behavior (synchronous / asynchronous). The driver is used to implement communication with a specific CA. The driver thus allows communication with any authority to go through the standardized interface provided by the driver and with which CRT module can works.

The CRT module contains a CAW-driver. This is a driver implementation that communicates with our internal certification authority (CAW). This authority is based on openssl and the CAW-driver uses for communication Bash commands.

Each certification authority needs specific configuration parameters.

These may include:

  • User and password for authentication.
  • Location of CA (url, path on server).
  • Global parameters (type of certificate, organization for which we want to generate certificates, …).

Obviously, for each certification authority, the driver must have a specific set of parameters. For easier development and configuration of the CA, the configuration is implemented as a JAVA class that contains fields corresponding to the given parameters. This configuration class then generates a configuration definition (EAV) that is represented in the GUI by a dynamic form. With this approach, configuration items can be clearly displayed, entered and validated.

Bellow is show authority detail uses the CAW-driver:

Each active operation performed on a certification authority (generation, renew, revocation) is performed by a request (crt-request). The request contains all the necessary information to perform the operation. For example, for generate certificate it is: Certificate type, certification authority, user defined password, request status.

The request is necessary in the case of asynchronous processing, here the situation where the external CA does not execute the operation immediately, but it is necessary check CA for the result again. In this case, the request is in the In progress state. The same situation occurs when we require a workflow approval before the request is executed. Even in this case, the request is the holder of the current status, in this case In approval.

If some error occures during processing of the request, then this error message will be persisted in this request and state will be in the state Exception.

If it is required approving all active operations before implementation, it is possible to enable approval in the CA configuration according to the selected workflow process. In this configuration, it is also possible to choose the roles used in the approval process. By default, all users with these roles will be able to approve/disapprove that request.

The CRT module contains "crt-approve-request" process that is used as the default setting for each new CA.

The "crt-approve-request" process only requires approval for new certificate generating requirements. For "Renew" and "Revocation" operations, approval is not required and the process ends immediately.

Configured notification topics (email by default):

  • certificateExpiredOwner - When certificate is expired, notification is sent to certificate owner.
    • Can be disabled by property idm.sec.crt.processor.certificate-expired-notification-owner-processor.enabled=false.
  • certificateExpiredAdmin - When certificate is expired, notification is sent to certificate admin.
    • Certificate admins are identities with role configured by property idm.sec.crt.processor.certificate-expired-notification-admin-processor.adminRole. When no identity is found, then notification isn't sent.
    • Can be disabled by property idm.sec.crt.processor.certificate-expired-notification-admin-processor.enabled=false.
  • certificateExpirationWarningOwner - CertificateExpirationWarningOwnerTaskExecutor
  • certificateExpirationWarningAdmin - CertificateExpirationWarningAdminTaskExecutor
  • certificateRevokedOwner - When certificate is revoked, notification is sent to certificate owner.
    • Can be disabled by property idm.sec.crt.processor.certificate-revoked-notification-owner-processor.enabled=false.
  • certificateRevokedAdmin - When certificate is revoked, notification is sent to certificate admin.
    • Certificate admins are identities with role configured by property idm.sec.crt.processor.certificate-revoked-notification-admin-processor.adminRole. When no identity is found, then notification isn't sent.
    • Can be disabled by property idm.sec.crt.processor.certificate-revoked-notification-admin-processor.enabled=false.
  • certificateCreatedOwner - When certificate is created, notification is sent to certificate owner.
    • Can be disabled by property idm.sec.crt.processor.certificate-created-notification-owner-processor.enabled=false.
  • certificateCreatedAdmin - When certificate is created, notification is sent to certificate admin.
    • Certificate admins are identities with role configured by property idm.sec.crt.processor.certificate-created-notification-admin-processor.adminRole. When no identity is found, then notification isn't sent.
    • Can be disabled by property idm.sec.crt.processor.certificate-created-notification-admin-processor.enabled=false.
  • requestApproved - When certificate request is approved, notification is sent to certificate owner.
  • requestDisapproved - When certificate request is disapproved, notification is sent to certificate owner.

Each topic has template with the same name with Crt prefix in module resources.

Authoritazion policies have to be configured to work with certificates and certificate authorities. Authorities can be configured on a role and then role can be assigned to identity.

If we want to an identity can request a certificates, we set authorization policies as follows:

  • Permission to read and download one's own identity certificates: Certificates (CrtCertificate) | Read | SelfCertificateEvaluator
  • Permission to read, create, update and cancel one's own identity certificate requests: Certificate requests (CrtRequest) | Create, Read, Update | SelfRequestEvaluator
  • Enabling the autocomplete for entities:
    • Certificate authorities (CrtAuthority) | Displaying in autocomplete, selections | BasePermissionEvaluator

When request is created, certificate authority has to be selected (autocomplete authorities permission). Request is created (as concept), description can be edited and then request is submitted to approving (if approving is configured). After certificate is generated, identity can read, renew and revoke him.

Renew and revoke certificate is controlled by create request permission (CERTIFICATEREQUEST_CREATE).
Certificate authority public certificate can be downloaded from authority info card, when autocomplete permission to certificate authority is granted.

Certificate generated by third party authority can be uploaded to CzechIdM (or synchronized from target system). If we want to an identity can upload certificate, we set authorization policies as follows:

  • Permission to read, create and download one's own identity certificates: Certificates (CrtCertificate) | Read, Create | SelfCertificateEvaluator

If we want to an identity can approve certificate request, we can use RequestByWfInvolvedIdentityEvaluator authorization policy evaluator. This evaluator grants permission to read certificate requests, which can be approved by logged identity. It's good to have autocomplete permission to identities (or subordinates etc.), otherwise identity identifier is shown as request owner on request detail.

If we want to an identity, which can administer certificates and authorities, we set authorization policies as follows:

  • Permission to all certificates: Certificates (CrtCertificate) | Admin | BasePermissionEvaluator
  • Permission to all certificate requests: Certificate requests (CrtRequest) | Admin | BasePermissionEvaluator
  • Permission to all certificate authorities: Certificate authorities (CrtAuthority) | Admin | BasePermissionEvaluator

Policies can be configured by custom needs. This example enables all operations with certificates, requests and certificate authorities.

Private certificate can be downloaded just by certificate owner. Even identity with admin permission for certificates cannot download private certificates for other identities.

Some certificate authorities can generate certificate asynchronously. This task checks certificate state on the certificate authority. When certificate is generated by the authority, then request is completed and certificate is saved in CzechIdM as attachment.

Default schedule: 0 0 1 ? * *

Expire certificates - persists certificate state, when certificate expires.

Default schedule: 0 0 1 ? * *

Expiration is controlled (and all notifications are send) even for archived certificates.

Sends warning notifications before certificate expires to certificate owner.

Parameters:

  • days before - notification is sent number of days before certificate expiration

Not scheduled by default.

Sends warning notifications before certificates expire to certificate admin.

Parameters:

  • days before - notification is sent number of days before certificate expiration
  • admin role - certificate admins are identities with this role. When no identity is found, then notification isn't sent.

Not scheduled by default.

Read more