====== Modules - Certificates: - Scheduled tasks, notifications and automatic certificate renew, generating or revocation ======

In this tutorial, we will create a new scheduled task. This scheduled task will send a notification a few days before a certificate expires.

===== What do you need before you start =====

  * You need to have **CzechIdM 7.7.0**  (and higher) installed.
  * You need to be logged in as **admin**  (or a user with superAdminRole).
  * You need to enable the **Certificate**  module.

===== Create scheduled task =====

In the left menu, select **Settings**  and then **Task scheduler**. And click on **Add**  button.

{{  .:ca_lrt_01.png  }}

In the popup window select **CertificateExpirationWarningOwnerTaskExecutor**  and fill in how many days before a certificate expires you want to receive the notification, in our tutorial it is 3. (There is another scheduled task **CertificateExpirationWarningAdminTaskExecutor**, which is similar to this one, the only difference is that the notification is sent to users with a role defined in scheduled task.)

{{  .:ca_lrt_02.png  }}

As you can see in the following picture, there is now new scheduled task with a parameter of 3 **days before**. In column **Action**  there is a green button "play" and by clicking on it, the scheduled task will start. (If you want to start this task automatically, look in tutorial about [[.:create_and_configure_trigger|triggers]].)

{{  .:ca_lrt_03.png  }}

Scheduled task will send a notification to the owner of the certificate when certificate would expire in 3 days.

{{  .:ca_lrt_04.png  }}

Congratulations, now your certificates will never expire.

===== Notification configuration =====

In this part of tutorial, there are mentioned a few certificate notifications, which can be easily configured. The configuration of these notifications is in the left menu **Settings**→**Configuration**.

Configured notification topics (email by default):

  * **certificateExpiredOwner**  - When a 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 a 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''.
  * **certificateRevokedOwner**  - When a 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 a 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 a 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 a 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 a certificate request is approved, notification is sent to certificate owner.
  * **requestDisapproved**  - When a certificate request is disapproved, notification is sent to certificate owner.
  * **certificateCreatedPasswordOwner**  - notification with new password generates or filled during creating certificate.
Each topic has a template with the same name with ''Crt''  prefix in module resources.

===== Auto-Renewal of Certificates =====

To enable auto-renewal of certificates before expiration, you would need to set **CertificateRenewalTaskExecutor **in (**Settings → Scheduler and Scheduled Tasks**) that triggers renewal tasks automatically in user defined times its not automatically sett. There should be a set how many days before the expiration of a certificate the renewal process should be initiated. This ensures that certificates are renewed.

Setting conditions before renewal:

User or Role Validity Checks:

When setting up the renewal process, there is an option to choose between checking the validity of a user or a role.

  * If "Role" is chosen, the renewal task will verify if the user associated with the certificate has been assigned the specified role before renewal. If you don’t chose any role role validation will be skipped.
  * Additionally, there's an option to enable a "User validity check before renew" checkbox. If checked, the renewal task will verify if the user is valid before initiating the renewal process. Otherwise validation will be ignored.

Combining Conditions or no conditions:

  * You can combine both role-based and user validity checks before triggering the certificate renewal process. If both of these conditions are left empty, validation will be ignored, and every certificate within the defined timeframe before expiration will be updated.

Setting example

{{.:crt_autorenew.png?nolink&697x545}}

The task showed in this image is designed to renew certificates with 5 days or less remaining validity. Minimum value is 1 which means certificates will be updated at expiration time. **Be careful expired certificates can't be renew!**  It checks whether the owner of the certificate holds a specific role, in this case, the role "Certificate." The user validity check is turned off. How to set task to be runining periodicaly or once is described above.

<note important> Check results of executed renew task in **Settings → Task scheduler**  find tab **ALL TASKS**  in field Task type find **CertificateRenewalTaskExecutor**  and click magnify glass and open tab **Processed items**. There you can check which certificates was renewed. </note>

===== Auto-Generating or Revocation of Certificates =====

<note important> **CrtManageCertificatesForRole **expect to have defined only one certification authority in Idm! </note>

To enable auto-generating or revocating of certificates, you would need to set **CrtManageCertificatesForRole **in (**Settings ****→**** Scheduler and Scheduled Tasks**) that triggers generate or revocate tasks automatically in user defined times. This task is not automatically sett! You should choose role which defines certificate ownership. This ensures that certificates are generated or revocated.
=== Setting example and explanation what will happen when LRT starts: ===

Role - defines ownership of certificate

{{.:crt-example.png?nolink&720x397}}

LRT check conditions for each user:

User have role **Certificate** and don't have valid certificate → LRT will generate new certificate for him.

User have role **Certificate** and one or more valid certificates → nothing will be changed.

User don't have role **Certificate** and have one or more valid certificates → LRT will revoke certificate o.

User don’t have role **Certificate** and don’t have certificate → nothing will be changed

At the end of this task every user with defined role will have certificate.