Issued Certificate Request Alerts

1. On the Issued Certificate Request Alerts page, choose Add from the toolbar to create a new alert, or select an existing alert and choose Edit from the toolbar or right-click menu.

2. In the Issued Certificate Alert Settings dialog, select your Certificate Template (or select All Templates) in the first dropdown.

   

   Figure 179: Create a New Issued Certificate Alert

3. In the Display Name field, enter a name for the alert. This name appears in the list of issued certificate alerts in the Management Portal.

4. 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 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 (for example 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 (for example servername.keyexample.com or www.keyexample.com).} in the alert definition and each alert generated 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 (for example 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 (for example 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 (for example, {cn}).

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

   Copy

   Serial Number: {serial}
   Thumbprint: {thumbprint}
   SANs: {san}
   App Owner: {metadata:AppOwnerFirstName} {metadata:AppOwnerLastName}

   With this HTML code:

   Copy

   <table>
   <tr><td>Serial Number: </td><td>{serial}</td></tr>
   <tr><td>Thumbprint: </td><td>{thumbprint}</td></tr>
   <tr><td>SANs: </td><td>{san}</td></tr>
   <tr><td>App Owner: </td><td>{metadata:AppOwnerFirstName} {metadata:AppOwnerLastName}</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>

6. The Download Link substitutable special text field is an important one to include in your alert intended for the requester of the certificate or the person responsible for installing the certificate. This provides a link in the email message that the user can click to be taken to the Keyfactor Command Management Portal to download the certificate.

   Tip:  If the users who will receive the issued alerts do not have global Read permissions for Certificates, they will not be able to use the built-in download link. To resolve this, you can build a custom download link as follows:

   1. If you do not already have a My Certificates 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 available in other places in the Management Portal (for example expiration alerts and certain reports)., create one using the %ME% special value with a search string of:

      NetBIOSRequester -eq "%ME%"

   2. In the Management Portal, browse to the My Certificates collection page and look in the browser's address bar at the end of the URL to the number that has been assigned to the collection. For example, the following URL points to collection 9:

      https://keyfactor.keyexample.com/KeyfactorPortal/CertificateCollection/Edit?cid=9
   3. Grant the users who will receive the issued alerts Read permissions on the My Certificates collection (see Certificate Collection Permissions).

   4. In the message body of the issued alert, create a link that looks like the following, where keyfactor.keyexample.com is the name of your Keyfactor Command server and ID is the correct collection ID for your My Certificates collection (for example, 9):

      Copy

      <a href="https://keyfactor.keyexample.com/KeyfactorPortal/CertificateCollection/Edit?cid=ID&query=Thumbprint+-eq+%22{thumbprint}%22">Download Now</a>

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

8. In the Recipients table, click Add to create a new recipient entry. You can add multiple recipients to each alert. Each row in the table represents a separate email message that will be sent when the alert is triggered. For example:

   • You can enter specific email addresses (for example, user@keyexample.com) or use substitutable special text variables (for example, {certemail}) that are replaced with actual email addresses when the alert runs. This is useful for dynamically selecting recipients based on certificate data or metadata fields.

   • To include multiple recipients on the same email, where all recipients of the email will be able to see who the other recipients are, add them in a single row, separated by commas or semicolons (for example, user1@keyexample.com, user2@keyexample.com).

   • To send to multiple recipients in separate emails, where all recipients will receive separate email messages appearing as though there were no other recipients, add them on separate rows.

   To use substitutable special text, click the Use a variable from the certificate checkbox to select a built-in variable and choose a value from the dropdown. Each selected variable is added to the alert on its own row and sends a separate email to the respective recipient. You cannot add variables to a line that contains email addresses.
   

   Edit or delete a recipient by selecting it and using the action buttons on the toolbar.

   Tip:  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 (for example, 4155551212@txt.att.net) and Verizon can be addressed using 10-digit-number@vtext.com (for example, 2125551212@vtext.com). T-Mobile can be addressed using 10-digit-number@tmomail.net (for example, 2065551212@tmomail.net), but functionality can be spotty. Reliability of alerting via this method depends on the reliability of the carrier’s gateways.

   

   Figure 180: Issued Certificate Alerts Recipients

9. Click Save to save your issued certificate alert.

You may use the copy operation to create multiple similar alerts—for example, one to the requester of the certificate and another with a different message to the person responsible for installing it.

1. On the Issued Certificate Request Alerts page, highlight the row in the alerts grid and click Copy from the toolbar or right click menu.
2. The Issued Certificate 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 o 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 Issued Certificate Request Alerts page, highlight the 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 issued alerts, you may configure a schedule to send the alerts.

• On the Issued Certificate Request Alerts page, click Configure at the top of the Issued Certificate Request Alerts page to configure a monitoring execution schedule. This defines the frequency with which alerts are sent. You can choose to schedule the alerts either for daily delivery at a specified time or at intervals of anywhere from every 1 minute to every 12 hours. A short interval is the most common configuration.