Expiration Alert Operations
Expiration Alert Operations
Expiration alerts are based on certificate collections. Before you can work with expiration alerts, you need to have created a certificate collection The certificate search function allows you to query the Keyfactor Command database for certificates from any available source based on any criteria of the certificates and save the results as a collection that will be availble in other places in the Management Portal (e.g. expiration alerts and certain reports). on which to base the alert (see Certificate Search and Collections).
- In the Management Portal, browse to Alerts > Expiration.
- On the Expiration Alerts page, click Add from the top menu to create a new alert, or Edit from either the top or right click menu, to modify an existing one.
-
In the Certificate Expiration Alert Settings dialog, select your Certificate Collection in the first dropdown.
Figure 115: Create a New Expiration Alert
-
In the Timeframe fields, select the warning timeframe by defining a number for either days, weeks, or months for the alert. For example, if you select three weeks, the expiration alerts will be sent automatically three weeks ahead of certificate expiration.
Note: When the alert is stored in the database, weeks are converted to 7 days and months are converted to 30 days.Example: When alerts run, the alert engine reports on all the certificates expiring within the next X days (e.g. 30 days) from the execution time that have not previously been reported on. This means that if the alerts run daily and have been running daily regularly for some time, only a single day of expiring certificates will be reported on by any given alert run.For example, say you create a new alert that has never run before for collection A and set it to 30 days. You configure it to run daily at 5:00 am. The alert runs for the first time at 5:00 am on July 1st. All the certificates in collection A that will expire between July 1st at 12:oo am UTC and July 31 at 12:00 am UTC will be alerted on. The next day when the alert runs again at 5:00 am on July 2nd, the certificates in collection A expiring between July 31st at 12:00 am UTC and August 1st at 12:oo am UTC will be alerted on.
If alerts are missed for a period of time (due to an outage, for example), the next run of the alerts will check the previous successful run date for the alerts and report on certificates expiring X days from that outage window. For example, using the collection A alert referenced above, say an outage caused the alerts not to run on August 1 and August 2. On August 3, the alert would run again at 5:00 am, and the certificates in collection A expiring between August 30th at 12:00 am UTC and September 2nd at 12:oo am UTC would be alerted on.
- In the Display Name field, enter a name for the alert. This name appears in the list of expiration alerts in the Management Portal.
-
In the Subject field, enter a subject line for the email message that will be delivered when the alert is triggered. You can use substitutable special text in the subject line. Substitutable special text uses a variable in the alert definition that is replaced by data from the certificate or certificate metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. at processing time. For example, you can enter {cn A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com).} in the alert definition and each alert generated at processing time will contain the specific common name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). of the given certificate instead of the variable {cn}.
To add substitutable special text to the subject line; place your cursor where you would like the text to appear on the subject line, select the appropriate variable from the Insert special text dropdown, and click Insert. Alternately, type the special text variable enclosed in curly braces (e.g. {cn}).
-
In the Message box, enter the body of the email message that will be delivered when the alert is triggered. You can use the Insert special text dropdown below the message window to add substitutable special text to the message. The metadata that appears in the dropdown will depend upon the custom metadata you have defined (see Certificate Metadata). Place your cursor where you would like the text to appear, select the appropriate variable from the dropdown, and click Insert. Alternately, you can type the special text variable enclosed in curly braces directly. In addition to the substitutable special text fields available in the dropdown, you can also build your own substitutable fields for the principal and/or requester based on string values from the user or computer Active Directory record. See Table 9: Substitutable Special Text for Expiration Alerts. If desired, you can format the message body using HTML. For example, you could place certificate detail information into a table by replacing this text:
CN: {cn}UPN: {upn}Thumbprint: {thumbprint}Serial Number: {serial}With this HTML code:
<table><tr><td>DN:</td><td>{dn}</td></tr><tr><td>CN:</td><td>{cn}</td></tr><tr><td>UPN:</td><td>{upn}</td></tr><tr><td>Thumbprint:</td><td>{thumbprint}</td></tr><tr><td>Serial Number:</td><td>{serial}</td></tr></table> -
Check the Use handler box if you would like the alert to trigger an event handler at processing time, select the appropriate handler in the dropdown, and click the Configure button to configure the handler. See Using Event Handlers for more information on using event handlers.
Note: As of version 9.0 of Keyfactor Command, PowerShell scripts for alert handlers need to be in the extension path or a subdirectory of it specified by the Extension Handler Path application setting (see Application Settings: Console Tab). By default this is:C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\For example, create a directory called Scripts under the ExtensionLibrary directory and then reference your PowerShell script as Scripts\MyPowerShell.ps1. Any scripts referenced by PowerShell handlers that are outside this path will fail to run.
-
In the Recipients section of the page, click Add to add a recipient to the alert. Each alert can have multiple recipients. Recipients should be added one at a time. You can enter specific email addresses and/or use substitutable special text to replace an email address variable with actual email addresses at processing time. The built-in variable can be selected in the Recipient dialog Use a variable from the certificate dropdown. In addition, you can type a special text variable enclosed in curly braces in the Email field if you have, for example, a metadata field that contains an email address.
Keyfactor Command sends SMS (text) messages by leveraging the email to text gateways that many major mobile carriers provide. Check with your carrier for specific instructions. Keyfactor has tested that AT&T can be addressed using 10-digit-number@txt.att.net (e.g. 4155551212@txt.att.net) and Verizon can be addressed using 10-digit-number@vtext.com (e.g. 2125551212@vtext.com). T-Mobile can be addressed using 10-digit-number@tmomail.net (e.g. 2065551212@tmomail.net), but functionality can be spotty. Reliability of alerting via this method depends on the reliability of the carrier’s gateways.
Figure 116: Expiration Alerts Recipients
- Click Save to save your expiration alert, or your changes.
You may use the copy operation to create multiple similar alerts—for example, several alerts for the same certificate collection but with different warning timeframes.
- In the Management Portal, browse to Alerts > Expiration.
- On the Expiration Alerts page, highlight the row in the expiration alerts grid and click Copy at the top of the grid, or from the right click menu.
- The Certificate Expiration Alert Settings dialog will pop-up with the details from the selected alert. The display name field will have "- Copy" tagged to the end of it to indicate it is a new alert. You may modify the alert as needed and click Save to add the new alert, or Cancel to cancel the operation.
You may delete one expiration alert at a time.
- In the Management Portal, browse to Alerts > Expiration.
- On the Expiration Alerts page, highlight the row in the Expiration Alerts grid and click Delete at the top of the grid, or from the right click menu.
- On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.
After adding your desired Certificate Expiration Alerts, you may configure an alert schedule.
- In the Management Portal, browse to Alerts > Expiration.
- On the Expiration Alerts page, click the Configure button at the top of the Expiration Alerts page to configure a monitoring execution schedule. This will apply for all the expiration alerts. This defines the frequency with which alerts are sent. This type of alert is scheduled for daily delivery at a specified time.
For example, say you create a new alert that has never run before for collection A and set it to 30 days. You configure it to run daily at 5:00 am. The alert runs for the first time at 5:00 am on July 1st. All the certificates in collection A that will expire between July 1st at 12:oo am UTC and July 31 at 12:00 am UTC will be alerted on. The next day when the alert runs again at 5:00 am on July 2nd, the certificates in collection A expiring between July 31st at 12:00 am UTC and August 1st at 12:oo am UTC will be alerted on.
If alerts are missed for a period of time (due to an outage, for example), the next run of the alerts will check the previous successful run date for the alerts and report on certificates expiring X days from that outage window. For example, using the collection A alert referenced above, say an outage caused the alerts not to run on August 1 and August 2. On August 3, the alert would run again at 5:00 am, and the certificates in collection A expiring between August 30th at 12:00 am UTC and September 2nd at 12:oo am UTC would be alerted on.
Figure 117: Expiration Alert Schedule
Once the alerts are configured, you may run a test of all, or selected, alerts to see if they are configured correctly.
- In the Management Portal, browse to Alerts > Expiration.
- On the Expiration Alerts page, either highlight one row in the expiration alert grid and click the Test button at the top of the grid or click the Test All button at the top of the grid to test all the alerts.
-
In the Expiration Alert Test dialog in the Alert Parameters section, select a Start Date and End Date for testing. You can use this option to simulate running the alerts a month from now instead of today, for example, or put in a broad date range to be sure you pick up some expiring certificates for testing purposes.
Example: Say you had experienced an outage and alerts that normally run daily at 5:00 pm did not run for two days. You wanted to test to see what to expect of the alerts once the system was up and running again. You are running your test on August 3rd for an alert that's configured to report at 30 days for collection A. The alert last ran on July 31. This means the alert has a Previous Evaluation Date of July 31. When running your test, set the Start Date to July 31st to match the Previous Evaluation Date. Set the End Date to the current date, August 2nd in this example, to simulate the results when the alerts are run today. The test results will include up to 100 certificates in collection A expiring between August 30th at 12:00 am UTC and September 1st at 12:oo am UTC. - In the Expiration Alert Test dialog in the Alert Parameters section, click the toggle button for Send Alerts if you would like to deliver email messages as part of the test.
- Click the Generate button to begin generating alerts. Depending on the number of certificates to process, this may take a few seconds.
- In the Expiration Alert Test dialog in the Alert Data and Alert Message sections, you can review the certificates found to confirm that the expected certificates are appearing and that the substitutable special text is being replaced as expected. Scroll through the alerts using the First, Previous, Next and Last buttons at the bottom of the dialog. The number of alerts generated will display between the navigation buttons.Note: You may see fewer alerts than you have certificates expiring in the selected time window for the certificate collection if you enabled one of the options to ignore duplicate certificates on the certificate collection (see Saving Search Criteria as a Collection).
By default, a maximum of 100 alerts will be generated during a test. The maximum value is configurable with the Expiration Alert Test Result Limit setting in Keyfactor Command application settings (see Application Settings: Console Tab in the Keyfactor Command Reference Guide). If more than 100 alerts are generated, no email messages will be sent and you'll have the opportunity to view the first 100 alerts generated.
If you're using an event handler, the event handler is run and the handler actions taken (PowerShell script run, event log message written, certificates renewed) when the test is run. This is true whether or not you click the Send Alerts toggle.
Figure 118: Expiration Alert Test
Refer to the following table for a complete list of the substitutable special text that can be used to customize alert messages.
Table 9: Substitutable Special Text for Expiration Alerts
Variable |
Name |
Description |
---|---|---|
{certemail} |
Email Address in Certificate |
Email address contained in the certificate, if present |
{cn} |
Common Name |
Common name contained in the certificate |
{dn} |
Distinguished Name |
Distinguished name contained in the certificate |
{certnotbefore} |
Issue Date |
Validity date of the certificate |
{certnotafter} |
Expiration Date |
Expiration date of the certificate |
{issuerDN} |
Issuer DN |
Distinguished name of the certificate’s issuer |
{locations:certstore} |
Certificate Store Locations |
The server and path location to the certificate store(s) where the certificate resides, if any, for certificates found in certificate stores (e.g. server1.keyexample.com – /opt/test/mystore.jks) |
{principal:mail} |
Principal’s Email |
Email address retrieved from Active Directory of the user whose UPN is contained in the SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common. field of the certificate, if present |
{principal:givenname} |
Principal’s First Name |
First name retrieved from Active Directory of the user whose UPN is contained in the SAN field of the certificate, if present |
{principal:sn} |
Principal’s Last Name |
Last name retrieved from Active Directory of the user whose UPN is contained in the SAN field of the certificate, if present |
{principal:displayname} |
Principal’s Display Name |
Display name retrieved from Active Directory of the user whose UPN is contained in the SAN field of the certificate, if present |
{requester} |
Requester |
The user account that requested the certificate from the CA A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA., in the form "DOMAIN\username" |
{requester:mail} |
Requester’s Email |
Email address retrieved from Active Directory of the user account that requested the certificate from the CA, if present |
{requester:givenname} |
Requester’s First Name |
First name retrieved from Active Directory of the user account that requested the certificate from the CA, if present |
{requester:sn} |
Requester’s Last Name |
Last name retrieved from Active Directory of the user account that requested the certificate from the CA, if present |
{requester:displayname} |
Requester’s Display Name |
Display name retrieved from Active Directory of the user account that requested the certificate from the CA, if present |
{careqid} |
Issuing CA / Request ID |
A string containing the Issuing CA name and the certificate’s Request ID from the CA |
{serial} |
Serial Number |
The serial number of the certificate |
{locations:ssl} |
The server location(s) where the certificate resides, if any, for certificates synchronized using SSL synchronization |
|
{san} |
Subject alternative name(s) contained in the certificate |
|
Template Name |
Name of the certificate template used to create the certificate |
|
{templateshortname} |
Template Short Name |
Short name (often the name with no spaces) of the certificate template used to create the certificate |
{thumbprint} |
Thumbprint |
The thumbprint (hash) of the certificate |
{upn} |
User Principal Name |
The user principal name (UPN) contained in the subject alternative name (SAN) field of the certificate, if present (e.g. "username@keyexample.com") |
{metadata: Email-Contact} |
Email-Contact |
Example of a custom metadata field |
{principal:field} |
String Value from AD |
Locates the object in Active Directory identified by the UPN in the certificate (if present), and substitutes the contents of the attribute named by "field". For example:
Note: This substitutable special text field is partially user defined—you pick the field out of AD to include—and is therefore not available in the Insert special text dropdown; it needs to be typed manually.
|
{requester:field} |
String Value from AD |
Locates the object in Active Directory identified by the user or computer account that requested the certificate from the CA, and substitutes the contents of the attribute named by "field". For example, for users:
For computers:
Note: This substitutable special text field is partially user defined—you pick the field out of AD to include—and is therefore not available in the Insert special text dropdown; it needs to be typed manually.
|