Chapter 16   Setting Up Automated Notifications


iPlanet Certificate Management Server can send email notifications automatically when certain events occur. Unlike jobs that are executed on a preconfigured schedule, these notifications are event-driven—that is, whenever an event occurs, the server notifies the user. Notifiable events include certificate issuance and pending requests in an agent queue.

This chapter describes event-driven notifications supported by Certificate Management System and explains how to turn them on. The chapter has the following sections:

• Automated Notifications

• Customizing Notification Messages

• Configuring a Subsytem to Send Notifications

Automated Notifications

---

You can configure the Certificate Manager and Registration Manager to send automated email notifications to end entities, agents, or administrators when events relevant to these users occur. The email notifications are event-driven—that is, whenever an event occurs, the subsystem generates the notification message and sends it to the user. Event-driven notification involves a listener class in the subsystem that registers an interest in an appropriate event, for example, successful completion of an enrollment request.

Notifiable events include the following:

• Notifications of Certificate Issuance to End Entities—end entities are notified by email that a requested certificate has been issued.

• Notification of New Request in Queue—agents are notified by email that a request has been added to the request queue. Alternatively (or in addition) a schedulable job can notify agents at regular intervals of the current state of the request queue; see Configuring a Subsystem to Run Automated Jobs.

Notifications of Certificate Issuance to End Entities

You can configure the Certificate Manager or Registration Manager to send a notification message to users who have been issued certificates in response to enrollment requests. This message normally includes information about the issued certificate and instructions for importing the certificate into the user's client.

This kind of notification involves a listener class in the subsystem that registers an interest in an appropriate event, in this case successful completion of an enrollment request. In the CMS configuration, this listener class for a Certificate Manager is defined as ca.notification.certIssued and for the Registration Manager it is defined as ra.notification.certIssued.

For more information on listeners, check the samples directory:

<server_root>/cms_sdk/cms_jdk/samples/listeners

When a certificate is issued, the listener builds a notification message based on a configured template and sends it to an email address that it determines by using an email resolver. By default the email is obtained from the email address entered in the request or from the certificate.

• The email resolver first checks the request for the email address and if doesn't find one, it checks the subject name of the certificate for the email address; if the subject name doesn't include the email address, the resolver checks the certificate for the Subject Alternative Name extension to see whether it specifies the email address. For specifying an email address in the Subject Alternative Name extension, see Configuring Policy Rules for a Subsystem.

• In the absence of an email address, the notification is sent to the email address specified in the "Sender's Email Address" field, instead of the requestor, as an undeliverable notification. There'll also be a message to this effect in the logs; see Monitoring CMS Logs.

Note that you can customize the email resolver using the ReqCertSANameEmailResolver.java class included as a sample at this location:

<server_root>/cms_sdk/cms_jdk/samples/resolvers

The template that the listener uses to construct the email notification message is located in the configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails

You can configure both the path and filename of the template file. You can also modify the template to customize the contents and appearance of the messages; see Customizing Message Templates.

Messages can be sent as HTML or plain text.

For the certIssued listener, you can configure the following:

• Whether the listener is enabled.

• The sender of the notification messages (who will be notified of any delivery problems).

• The location of the notification email template.

• The subject line of the notification message.

Notification of New Request in Queue

When a deferred end-entity request enters the request queue of a Certificate Manager or Registration Manager, agents assigned to manage the queue must review the request and reject or accept it. To help ensure that an agent processes the request in a timely manner, you can configure the subsystem to notify agents whenever a new request gets added to the request queue.

This kind of notification involves a listener class in the subsystem that registers an interest in an appropriate event, in this case the addition of a request to the request queue. In the CMS configuration, this listener class is identified as follows: ca.notification.requestInQ

For more information on listener classes, check the samples directory:

<server_root>/cms_sdk/cms_jdk/samples/listeners

When a request is added to the queue, the listener builds a notification message based on a configured template and sends it to one or more agents' email addresses as configured.

The template that the listener uses to construct the email notification message is located in the configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails

You can configure both the path and filename of the template file. You can also modify the template to customize the contents and appearance of the messages; see Customizing Message Templates.

For the requestInQ event listener, you can configure the following:

• Whether the listener is enabled.

• The sender of the notification messages (who will be notified of any delivery problems).

• The location of the notification email template.

• The subject line of the notification message.

• The email addresses of message recipients; these should be subsystem agents whose task is to review deferred enrollment requests.

Customizing Notification Messages

---

Notification and summary email messages are constructed using templates located in the emails directory of a CMS instance. This directory has the following default location: <server_root>/cert-<instance_id>/emails

Both text an HTML templates are included by default. They are listed in Table 16-1.

Templates for Event-Triggered Notifications

Table 16-1 lists the default template files provided for formulating event-triggered-notification messages. You can customize certain aspects of these templates, such as the subject of the email message and the location and name of the template file, using the CMS window.

Table 16-1    Default templates for event-triggered notifications  

Filename	Description
certIssued_CA	Template for the Certificate Manager to send plain-text notifications to end entities upon issuance of certificates.
certIssued_CA.html	Template for the Certificate Manager to send HTML-based notifications to end entities upon issuance of certificates.
certIssued_RA	Template for the Registration Manager to send plain-text notifications to end entities upon issuance of certificates.
certIssued_RA.html	Template for the Registration Manager to send HTML-based notifications to end entities upon issuance of certificates.
certRequestRejected_CA	Template for the Certificate Manager to send plain-text notifications to end entities when rejecting their certificate requests.
certRequestRejected_CA.html	Template for the Certificate Manager to send HTML-based notifications to end entities when rejecting their certificate requests.
certRequestRejected_RA	Template for the Registration Manager to send plain-text notifications to end entities when rejecting their certificate requests.
certRequestRejected_RA.html	Template for the Registration Manager to send HTML-based notifications to end entities when rejecting their certificate requests.
reqInQueue	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.
reqInQueue.html	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.

Note that the email notification that a certificate has been issued is based on a template file whose default name begins with certIssued. Similarly, the email notification that a certificate has been rejected is based on a template file whose name begins with certRequestRejected. This template file must be located in the same directory as the certificate-issuance template. Unlike the certificate-issuance template, the filename of the certificate-rejection template (certRequestRejected) cannot be changed. However, the file extension for the certRequestRejected file can be changed, as long as it exactly matches the file extension specified for the certificate issuance template file. For example, if the certificate issuance template file is named certIssued_CA.htm, the certRequestRejected file must be named certRequestRejected.htm. The HTML file extensions permitted are .htm, .html, .HTM, and .HTML. Template files with any other extension (or no extension) are treated as text files.

If you change the name of any of these files, be sure to make the appropriate changes to the configuration (see the "Content template file" field on page 585 and page 586). In the CMS configuration, template files for event-triggered notifications are identified as follows:

<subsystem>.notification.<notification_name>.emailTemplate=
<template_file_path>

<subsystem>.notification.<notification_name>.emailTemplate=
<template_file_path>

<subsystem> specifies the prefix that identifies the subsystem to which the configuration parameter belongs—ca for the Certificate Manager and ra for the Registration Manager.

<notification_name> specifies the name of the event-triggered notification—certIssued for the certificate issuance notifications to end entities and requestInQ for the request in queue notifications to agents.

<template_file_path> specifies the path, including the filename, to the directory that contains the template to be used for formulating the message content.

Tokens, which you can use as variables in the body of the message, are also defined for each template, enabling you to customize the message; a token is replaced by its current variable value in the constructed message. For details, see Customizing Message Templates.

Customizing Message Templates

You can modify the templates to customize the contents and appearance of messages. The message body can contain HTML or plain text. In the body of the message, you can use tokens or keywords as variables. A token is indicated by the dollar character ($) and is replaced by its current variable value in the constructed message. Different tokens are available for each job or notification class. These are listed in Tokens Available in Message Templates.

For example, a certificate-issuance-notification message can make use of tokens as follows:

------------------------------------
CERTIFICATE ISSUANCE NOTIFICATION
------------------------------------

Your certificate request ($RequestId) has been processed successfully. Details of your certificate are as follows:

Serial Number= $SerialNumber
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN
Validity Period= $NotBefore - $NotAfter

To get your certificate, please follow this URL:

https://$HttpHost:$HttpPort/getCertFromRequest?requestId=$RequestId

If you have any questions or problems, please send an email to cert_central@siroe.com.

Thank you.

Tokens Available in Message Templates

This section explains the tokens provided in the templates used by the default job plug-in and event-triggered notification modules to formulate notification messages.

• Tokens for Certificate Issuance Notifications to End Entities

• Tokens for Rejection Notifications to End Entities

• Tokens for Request In Queue Notification Messages

Tokens for Certificate Issuance Notifications to End Entities

Table 16-2 lists the tokens that are available in the message templates provided for formulating the content of email notifications to end entities; a Certificate Manager or Registration Manager can send these notifications upon issuance of the certificates they requested.

Table 16-2    Tokens defined in templates used for certificate-issuance notifications  

Token	Description
$HttpHost	Specifies the fully qualified host name of the Certificate Manager or Registration Manager to which end entities should connect to retrieve their certificates. (This token enables you to construct the URL from which end entities can download their certificates; see the example in Customizing Message Templates.)
$HttpPort	Specifies the port number at which the Certificate Manager or Registration Manager is listening to end-entity requests. (This token enables you to construct the URL from which end entities can download their certificates; see the example in Customizing Message Templates.)
$InstanceID	Specifies the ID assigned to the subsystem that sent this notification. If the notification is sent by a Certificate Manager, this will be ca. If the notification is sent by a Registration Manager, this will be ra.
$IssuerDN	Specifies the distinguished name of the CA that issued the certificate.
$NotAfter	Specifies the NotAfter attribute.
$NotBefore	Specifies the NotBefore attribute.
$RecipientEmail	Specifies the email address of the recipient (the address resolved from the email resolver explained in Notifications of Certificate Issuance to End Entities).
$RequestId	Specifies the request ID.
$SerialNumber	Specifies the serial number of the certificate that has been issued; the serial number will be displayed as a hexadecimal value in the resulting message.
$SenderEmail	Specifies the email address of the sender (it is the same as the one you specify in the Sender's E-mail Address field in Step 2. Turn On Certificate-Issuance Notification).
$SubjectDN	Specifies the distinguished name of the certificate subject.

Tokens for Rejection Notifications to End Entities

Table 16-3 lists tokens that are available in the message templates provided for formulating the content of email notifications to end entities; a Certificate Manager or Registration Manager can send these notifications to end entities when rejecting certificate requests.

Table 16-3    Tokens defined in templates used for request-rejection notifications  

Token	Description
$InstanceID	Specifies the ID assigned to the subsystem that sent this notification. If the notification is sent by a Certificate Manager, this will be ca. If the notification is sent by a Registration Manager, this will be ra.
$RequestId	Specifies the request ID.

Tokens for Request In Queue Notification Messages

Table 16-4 lists the tokens that you can use for formulating the content of the RequestInQueueJob job's summary report.

Table 16-4    Tokens for the request-in-queue job's summary report  

Token	Description
$InstanceID	Specifies the ID assigned to the subsystem that sent this notification. If the notification is sent by a Certificate Manager, this will be ca. If the notification is sent by a Registration Manager, this will be ra.
$ExecutionTime	Specifies the time the job (instance) was run.
$RecipientEmail	Specifies the email address of the recipient.
$SenderEmail	Specifies the email address of the sender (it is the same as the one you specify in the Sender's E-mail Address field in Step 3. Turn on Request in Queue Notification).
$SummaryTotalNum	Specifies the total number of items (certificate requests that are pending in the queue) in the summary report.

Configuring a Subsytem to Send Notifications

---

To configure a Certificate Manager or Registration Manager to send event-driven notifications, follow these steps:

• Step 1. Before You Begin

• Step 2. Turn On Certificate-Issuance Notification

• Step 3. Turn on Request in Queue Notification

• Step 4. Verify Mail Server Settings

• Step 5. Test Your Configuration

Step 1. Before You Begin

• Read section Automated Notifications and decide which of the two notification features you want to turn on.

• Read section Customizing Notification Messages and customize the message templates for the notifications your want to turn on.

Step 2. Turn On Certificate-Issuance Notification

Skip to the next step if you don't want to turn this feature on.

To configure a Certificate Manager or Registration Manager to send certificate-issuance notifications to end entities:

1. Access the CMS window (see Logging In to the CMS Window).

2. Click the Configuration tab.

3. In the navigation tree, select the subsystem, then click Notification. (The figure below shows the Certificate Manager's notification feature; the Registration Manager also has a similar feature.)
   
   

4. To enable the notification feature, check the "Enable Certificate Issued notification" option.

5. In the Email Information Settings section, enter information as appropriate:

   Sender's E-mail Address. Type the sender's full email address (this is the person who should be notified of any delivery problems).

   Subject. Type the subject title for the notification.

   Content template path. Type the path, including the filename, to the directory that contains the template to be used for formulating the message content.

6. To save your changes, click Save.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet.

Step 3. Turn on Request in Queue Notification

Skip to the next step if you don't want to turn this feature on.

To configure a Certificate Manager or Registration Manager to send email notifications to its agents:

1. In the navigation tree of CMS window, select the subsystem, and then click Notification. (The figure below shows the Certificate Manager's notification feature; the Registration Manager also has a similar feature.)

2. In the right pane, click Request In Queue.
   
   

3. To enable the notification feature, check the "Enable Request In Queue notification" option.

4. Enter information as appropriate:

   Sender's E-Mail Address. Type the sender's full email address (this is the person who should be notified of any delivery problems).

   Subject. Type the subject title for the notification—for example, "End Entity Request in Queue."

   Recipient's E-Mail Address. Type the recipient's full email address (this is the person who will check the queue). You can specify more than one recipient; separate email addresses by commas.

   Content template path. Type the path, including the filename, to the directory that contains the template to be used for formulating the message content.

5. To save your changes, click Save.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet.

Step 4. Verify Mail Server Settings

To identify the mail server that the Certificate Manager or Registration Manager should use for routing email notifications:

1. In the CMS window, select the Configuration tab, and then in the right pane, select the SMTP tab.
   
   

2. Identify the mail server by providing the following details:

   Server name. Make sure the field shows the correct host name for your mail server. Otherwise, type the full host name of the machine on which your mail server is installed. Certificate Management System uses this name to access the mail server. The format for the host name is as follows:

   <machine_name>.<your_domain>.<domain>

   By default, the host name of the mail server is shown as localhost instead of the actual host name (for example, mail.siroe.com).

   Port number. Make sure that the field shows the correct port number at which the mail server is listening for requests. Otherwise type the port number.

3. To save your changes, click Save.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Step 5. Test Your Configuration

To test whether the subsystem you configured sends email notifications:

1. Change the email addresses in the notification configuration to your email address.

2. Go to the end-entity interface and request a certificate using the manual enrollment form. When the request gets queued for agent approval, you should get notified. Check the message to see if has the correct information. Otherwise, correct the message template.

3. Next, login to the agent interface and approve the request. When the server issues a certificate, you should get an email notification.