Lab 9: Event Handlers and Automation

Event Handlers and Automation Lab Activity

Event handlers are a core extensibility point for the Keyfactor platform.  An event handler is available for each Alert type and will be executed for each certificate found during alert processing.  For example, a pending request alert that finds 10 outstanding certificate requests. Each request will generate an event that gets processed by the handler and there are three types of handlers available:

• Logger
  The logger handler will enable writing output to the Windows Event Log for each certificate or request found by the alert

• PowerShell
  The PowerShell handler enables the execution of a PowerShell script for each certificate or request found by the alert

• Renewal
  The Renewal handler is a special handler for the Expiration alert type.  This handler will renew the expiring certificate using the Keyfactor API and if the certificate is part of a certificate store, Keyfactor will generate the required job to replace the expiring certificate.

Automated Renewal Permissions

In preparation for our automation lab, we need to make sure our Keyfactor Service account has the appropriate API permissions to renew a certificate and create the associated jobs to replace the expiring certificate. 

1. Navigate to the Gear Icon > Security Roles & Claims.

2. Click Add in the ribbon to create a new Security Role with the following values:

4. On the Global Permissions tab, enable the following permissions:

6. Click the Claims tab.

7. On the Claims tab, add the kftrain\kf_service account to the new role.

8. Click Include and Close.

9. Click Save.

Note: By creating this role and adding the service account, we've enabled the Orchestrator service access to the API. This access will be used later to process an automated renewal based on an expiration alert.

Event Handler Configuration

Short-Lived Template

In order to configure our event handlers, we will need to make sure we have certificates and alerts to support our demo scenarios.  In order to ensure we have some expiring certificates, let's duplicate the Web Server template and make it valid for 7 days.

1. Open the Lab Console on the Desktop.

2. Click the Certificate Templates folder

3. Right click the 2YearWebServer template and select right click Duplicate Template

4. Click the General tab and give it a new name (i.e. Web Server 7  Day).

5. Change the Validity Period to 7 days

6. Click Ok on the pop up message.

7. Click Ok to Save and Close the new template.

8. Expand the Certification Authority folder

9. Expand the KFTRAIN-LAB-CA object

10. Right Click the Certificate Templates folder

11. Choose New > Certificate Template to Issue

12. Select the new 7 day template and click Ok.

We have created a new template we can now use to issue certificates that expire quickly in order to test our Expiration Alerts.  We still need to enable enrollment of this new template in Keyfactor.  Take a minute to enable PFX enrollment for the new template in the Keyfactor Portal. (Note: Private Key Retention must be configured in order to use PFX Enrollment) After issuing some of the short lived certificates, send at least one to the Windows Certificate store we created earlier.

Expiration Alert Configuration

Now that we have some certificates that will expire in the next week, we can begin configuration of our expiration alerts.  All expiration alerts are driven by a collection.  Go ahead and create a new collection that contains all certificates that use our new template. Once that is done, follow the steps below to create a new Expiration Alert.

1. Navigate to Alerts > Expiration.
   

2. Click Add in the ribbon menu

3. Configure your alert with the following configuration:

4. Click Save.

Once the alert is saved, we can force the process to run by executing a test of the Expiration Alert. Otherwise, we could configure our daily execution time and wait.  Let's run the test and see what happens.

1. Navigate to Alerts > Expiration

2. Select the Lab 9: 7 day Renewal alert

3. Click test in the ribbon menu.

4. Set the Start Date to yesterday

5. Set the End Date date to today

6. Enable Send Alerts

7. Click Generate

Note: Testing an expiration alert will execute the renewal and create the automation jobs associated with the certificate if it finds a certificate located in a store.