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.

5. To use workflow to deliver the alerts, leave the Use Workflows toggle enabled. To use the legacy alerting system to deliver the alerts, toggle the Use Workflows to disabled.

   

   Figure 157: Create a Key Rotation Alert with Use Workflows Enabled

6. If you toggled the Use Workflows option to disabled, you will see 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 158: Substitutable Special Text for Key Rotation Alerts

7. If you toggled the Use Workflows option to disabled, you will see 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>

   

   Figure 159: Create a Key Rotation Alert with Use Workflows Disabled

8. If you toggled the Use Workflows option to disabled, you will see 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 Adding Logging Handlers to Alerts for information on using event logging handlers and Adding PowerShell Handlers to Alerts for information about using PowerShell handlers.

   Tip:  With workflows, the equivalent functionality to the handlers can be achieved using either Set Variable Data or Use Custom PowerShell steps. See the examples for Write to Windows Event Log with Expiration Workflow and Update Additional Enrollment Field on Enrollment.

9. Click Save to save your key rotation alert.

   If you enabled the Use Workflow option and are saving an alert that does not have a matching workflow, you will receive a notification indicating that a workflow needs to be created to match the alert. When you click OK to the notification, you will be redirected to the workflow page with a new workflow open and pre-populated with the Name, Type, and Key Rotation Alert (key) appropriate to the alert you have saved.

   

   Figure 160: Workflow Required for Alert Notice

   

   Figure 161: Workflow Pre-Populated for Key Rotation Alert

10. In the Add/Edit Workflow Definition dialog on the Definition tab, enter a Description for your workflow.
11. On the Workflow Configuration page, add a new step of type Send Email (see Adding, Copying or Modifying a Workflow Definition) with appropriate subject, message, and recipients for your key rotation alert.
12. If desired, add other steps to the workflow for other functionality such as event logging (see the example Write to Windows Event Log with Expiration Workflow).

For key rotation alerts that use workflow, you can open the associated workflow for the alert using the Configure Workflow option.

1. In the Management Portal, browse to Alerts > Key Rotation.
2. On the Key Rotation Alerts page, highlight a row in the alerts grid and click Configure Workflow from the grid header or right-click menu.
3. You will be redirected to the workflow workspace for the workflow associated with the selected alert. If a workflow does not exist for the selected alert, one will be created and pre-populated with the Name, Type, and Key Rotation Alert (key) of the selected alert. Edit the workflow as needed (see Adding, Copying or Modifying a Workflow Definition).

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 a row in the alerts grid and click Copy from the grid header or 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 a row in the alerts grid and click Delete from the grid header or 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, highlight a row in the alerts grid and click Test from the grid header or right-click menu.
3. In the Key Rotation Alert Test dialog, select a Start Date and End Date for the test period. This would be the period when the SSH keys are reaching the defined stale period.

4. In the Key Rotation Alert Test: Select Targets dialog, select one or more users for testing. For alerts that do not use workflow, enable the Send Emails option if you would like to deliver email messages as part of the test. Alerts that do use workflow will generate workflow instances for each selected user.

   Tip:  If no users appear in the grid for testing, this indicates no users with SSH keys were found matching the criteria of the alert and test period selected for testing.
5. Click the Start Tests button to begin generating alerts. Depending on the number of users to process, this may take a few seconds.

6. In the Key Rotation Alert Test: Results dialog, you can review the generated key rotation alerts to confirm that the substitutable special text is being replaced as expected and the recipients are as expected. Scroll 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:  The display results will vary depending on whether the alert uses workflow to deliver the alerts or the legacy alerting system.