Key Rotation Alert Operations

1. On the Key Rotation Alerts page, click Add from the top menu to create a new alert, or Edit, from either the toolbar or right click menu, to modify an existing one.

2. 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.
3. 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.

4. Choose how alerts are delivered. Set Use Workflows to On or Off, depending on how you want alerts delivered.

   • If Use Workflows is set to On (workflow-based alerting):

     1. Select an option in the Workflow Definitions dropdown. You can either choose an existing workflow or select Add New Workflow.

        

        Figure 173: Create an SSH Key Rotation Alert with Workflow Option

     2. Save the alert.

        If you select Add New Workflow, saving the alert creates a new workflow with the same name as the key rotation alert. The workflow workspace opens automatically so you can add steps.

     3. Add one or more workflow steps, such as:

        • Send Email to notify recipients of the expiration event (see Workflow Step Configuration).

        • Optional steps for additional functionality, such as: Write to Windows Event Log for event logging (see the example 47 Day Certificate Renewal and Email Notification).

   • If Use Workflows is set to Off (legacy alerting):

     Continue with the following steps to configure legacy alert settings.

     1. 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 174: Substitutable Special Text for Key Rotation Alerts

     2. 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:

        Copy

        Fingerprint: {fingerprint}
        Username: {username}
        Comment: {comment}

        With this HTML code:

        Copy

        <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>

        Note:  When using HTML to format an email sent from Keyfactor Command, use inline styles and avoid linked stylesheets or embedded <style> rules. Many email clients do not fully support external or embedded CSS.

        Line breaks are not inserted automatically when HTML formatting is used. Define line breaks explicitly using tags such as <br>, <br/>, or <p></p>.

        Recommended:

        <p style="font-size:14px; color:#333; margin:0 0 12px;">Hello</p>

        Not Recommended:

        <link rel="stylesheet" href="https://cdn.keyexample.com/styles.css">

        or

        <style>p { color:#333; }</style>

        

        Figure 175: Create a Key Rotation Alert with Legacy Option

     3. In 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.

        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.
     4. Save the alert.

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

1. On the Key Rotation Alerts page, highlight a row in the alerts grid and click Configure Workflow from the toolbar or right-click menu.
2. 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 Add, Copy, or Modify 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. On the Key Rotation Alerts page, highlight a row in the alerts grid and click Copy from the toolbar or right-click menu.
2. 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. On the Key Rotation Alerts page, highlight a row in the alerts grid and click Delete from the toolbar or right-click menu.
2. 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.

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. On the Key Rotation Alerts page, highlight a row in the alerts grid and click Test from the toolbar or right-click menu.
2. 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.

3. 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.
4. Click the Start Tests button to begin generating alerts. Depending on the number of users to process, this may take a few seconds.

5. 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.