Key Rotation Alert Operations

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation 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.
3. In the Key Rotation Alert Settings dialog, select a Timeframe for the alert by choosing the number of days, weeks, or months to define the alert period.
   Note:  When the alert is stored in the database, weeks are converted to 7 days and months are converted to 30 days.
4. In the Key Rotation Alert Settings dialog, enter a Display Name for the alert. This name appears in the list of key rotation alerts in the Management Portal.

   

   Figure 129: Key Rotation Alerts Recipients

5. 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 key record at processing time. For example, you can enter {fingerprint} in the alert definition and each alert generated at processing time will contain the specific fingerprint of the given key instead of the variable {fingerprint}. To add substitutable special text to the subject line, type the special text variable enclosed in curly braces (e.g. {fingerprint}).

   

   Figure 130: Substitutable Special Text for Key Rotation Alerts

6. 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. 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. If desired, you can format the message body using HTML. For example, you could place the key detail information into a table by replacing this text:
    
   Fingerprint: {fingerprint}
   Username: {username}
   Comment: {comment}
    

   With this HTML code:

   <table>
   <tr><td>Fingerprint:</td><td>{fingerprint}</td></tr>
   <tr><td>Username:</td><td>{username}</td></tr>
   <tr><td>Comment:</td><td>{comment}</td></tr>
   </table>
7. 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 event 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.

8. Click Save to save your key rotation alert.

You may use the copy operation to create multiple similar alerts—for example, one for a warning a month in advance of the stale date of keys and another shortly before the keys become stale.

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation Alerts page, highlight the row in the alerts grid and click Copy at the top of the grid, or from the right click menu.
3. The Key Rotation 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.

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation Alerts page, highlight the row in the alerts grid and click Delete at the top of the grid, or from the right click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

After adding your desired key rotation alerts, you may configure a schedule to send the alerts.

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation Alerts page, click the Configure button at the top of the Key Rotation Alerts page to configure an alert execution schedule. This defines the frequency with which key rotation alerts are sent. This type of alert is scheduled for daily delivery at a specified time.

Once the alerts are configured, you may run a test of all or selected alerts to see if they are configured correctly.

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation 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.
3. In the Key Rotation Alert Viewer 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.
4. In the Key Rotation Alert Viewer 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.
5. Click the Generate button to begin generating alerts. Depending on the number of keys to process, this may take a few seconds.
6. In the Key Rotation Alert Viewer dialog in the Alert Data and Alert Message sections, you can review the keys found to confirm that the expected keys 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.

Tip:  Alerts are generated when an SSH The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. key is approaching or has reached its stale date as defined by the timeframe configured in the alert and the SSH key lifetime (the Key Lifetime (days) application setting).

By default, a maximum of 100 alerts will be generated during a test. The maximum value is configurable with the Key Rotation 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) when the test is run. This is true whether or not you click the Send Alerts toggle.