Administrator's Guide Netscape Certificate Management System

Previous      Contents      Index      DocHome      Next

Chapter 13   Automated Notifications

Netscape Certificate Management System (CMS) can be configured to send automatic email notifications to end users when certificates are issued and revoked, or to an agent when a new request has arrived in the agent request queue. This chapter describes automated notifications, details how to enable and configure them, and details how to customize the notification email messages that are sent.

This chapter contains the following sections:

• About Automated Notifications
• Customizing Notification Messages
• Setting Up Automated Notifications

About Automated Notifications

---

The automated notifications feature is an event-driven system that sends email notifications when the specified event occurs. The system uses listeners that monitor the system to determine when a particular event has occurred, and then trigger the notification system when the event does occur. Each type of notification is associated with a template in either plain text or HTML format that is used to construct the notification message. The template contains text and tokens that are expanded at run time to fill in the correct information for a particular event. The messages can be customized by changing the text and tokens contained in the templates. The HTML templates can be further customized by changing the HTML tags to create a different appearance for the message.

Setting Up Automated Notifications

The automated notifications feature is set up by performing the following tasks:

• Enabling and configuring one of the notification types and setting preferences for that notification type; see Setting Up Automated Notifications for complete details.
• Customizing the email notification messages that are sent. You do this by changing the template associated with a type of notification. You can change the contents of the message of both plain text messages and HTML messages, or the appearance of HTML messages. See Customizing Notification Messages for more information

Types of Automated Notifications

Three types of automated notifications are available:

• Certificate Issued
• Request In Queue
• Certificate Revocation.

Certificate Issued

A notification message is automatically sent to users who have been issued certificates. A rejection message is sent if the user's certificate request is rejected.

Request in Queue

A notification message is automatically sent to one or more agents when a request enters the agent request queue, using the email address(es) you set up for the agent when you set up this feature. There is also a job that sends a notification to agents about the status of the queue. The job sends a summary of the status at certain intervals. This notification sends an email every time a message enters the queue. For more information about the request in queue job, see "RequestInQueueJob".

Certificate Revocation

A notification message is automatically sent to users when their certificate is revoked.

You can create additional automated notifications using the CMS SDK.

Determining End-Entity Email Addresses

The notification system determines the email address of an end entity by checking in the certificate request or revocation request itself, then in the subject name of the certificate, and last in the Subject Alternative Name extension of the certificate—if the certificate contains this extension. If an email address cannot be found, the notification is sent to the email address specified in the "Sender's Email Address" field specified when you set up this notifications as undeliverable notification.

You can customize the email resolver using the ReqCertSANameEmailResolver.java class included as a sample with the CMS SDK.

Setting Up Automated Notifications

---

To configure a Certificate Manager or Registration Manager to send automated notifications, follow these steps:

1. Access the CMS console (see Logging Into the CMS Console).
2. Click the Configuration tab.
3. Select Notification in the navigation tree.

The Notification tabs appear in the right side of the window.
 







4. To enable Certificate Issued notifications, go to the Certificate Issued tab and specify information in the following fields:

Enable Certificate Issued notification. Select this field to enable Certificate Issued notifications.
 

Sender's E-mail Address. Type the sender's full email address; this is the email address of the person who is 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 constructing the message content.
 

5. To enable Request In Queue notifications, go to the Request In Queue tab and specify information in the following fields:

Enable Request In Queue notification. Select this field to enable Request In Queue notifications.
 

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

Subject. Type the subject title for the notification.
 

Recipient's E-Mail Address. Type the recipient's full email address; this is the email address of the agent, or agents, 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 constructing the message content.
 

6. To enable Certificate Revocation notifications, go to the Certificate Revoked tab and specify information in the following fields:

Enable Certificate Revoked notification. Select this field to enable Certificate Revoked notifications.
 

Sender's E-mail Address. Type the sender's full email address; this is the email address of the person who is 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 constructing the message content.
 

7. Click Save.
8. Make sure your mail server is set up correctly. See Mail Server.
9. Customize the notification message templates. See "Customizing Notification Messages".
10. Test your configuration. See "Testing Your Configuration".

Configuring Specific Notifications By Editing the Configuration File

1. Stop the server instance whose configuration file you will be editing.
2. Open the CMS.cfg file for that server instance in a text editor.
3. Edit all of the configuration parameters for the notification type you are enabling and configuring.

The parameters for this feature are identified as ca.notification for a Certificate Manager and ra.notification for a Registration Manager.
 

4. The parameters for a particular notification message are explained in the procedure in the section "Setting Up Automated Notifications".
5. Save the file.
6. Restart the server instance.
7. If you set up a job that sends automated messages, check that your have correctly set up a mail server. See "Mail Server".
8. If you set up a job that sends automated messages, you can customize those messages. See "Customizing Notification Messages" for details.

Testing Your Configuration

To test whether the subsystem you configured sends email notifications:

1. Change the email address in the notification configuration for the Request In Queue notification to your email address.
2. Go to the end-entity interface and request a certificate using the agent-approved enrollment form.

When the request gets queued for agent approval, you should receive a Request In Queue email notification. Check the message to see if has the correct information.
 

3. Login to the agent interface and approve the request.

When the server issues a certificate, you should receive a Certificate Issued email notification. Check the message to see if has the correct information.
 

4. Login to the agent interface and revoke the certificate.

You should receive an email message notifying you that the certificate has been revoked. Check the message to see if has the correct information.
 

Customizing Notification Messages

---

The email notifications that are sent are constructed using a template for each type of message that is sent. Each type of message has an HTML template and a plain text template associated with it. Messages are constructed from text and tokens, and HTML markup in the case of HTML templates. Tokens are variables, identified with the dollar sign ($) character, in the message that are replaced by the current value when the message is constructed. See "Token Definitions" for a list of available tokens.

You can modify the contents of any message type by making changes to the text and tokens contained in the template for that message type. You can modify the appearance of HTML messages by modifying the HTML commands included in the HTML template for that message type.

The text version of the certificate-issuance-notification message is a mixture of text and tokens, shown as follows:

Your certificate request has been processed successfully.

SubjectDN= $SubjectDN

IssuerDN= $IssuerDN

notAfter= $NotAfter

notBefore= $NotBefore

Serial Number= 0x$HexSerialNumber

To get your certificate, please follow this URL:

https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&seri alNumber=$SerialNumber

Please contact your admin if there is any problem.

And, of course, this is just a \$SAMPLE\$ email notification form.

You could change the message by changing the text and tokens, shown as follows:

THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER

Your certificate has been issued!

You can pick up your new certficate at the following website:

https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&seri alNumber=$SerialNumber

This certificate has been issued with the following information:

Serial Number= 0x$HexSerialNumber

Name of Certficate Holder = $SubjectDN

Name of Issuer = $IssuerDN

Certificate Expiration Date = $NotAfter

Certificate Validity Date = $NotBefore

Contact IT by calling X1234, or going to the IT website http://IT if you have any problems.

Notification Message Templates

Notification message templates are located in the following directory:

<server_root>/cert-<instance_id>/emails

You can change the name of these files as applicable or their location; be sure to make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates whose name must remain the same. The templates associated with certificate issuance and certificate rejection must be located in the same directory and must use the same extension.

Table 13-1 lists the default template files provided for creating notification messages.

Table 13-1    Notification Templates  

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.html	Template for the Certificate Manager to send HTML-based notifications to end entities when rejecting their certificate requests.
certRequestRevoked_CA	Template for the Certificate Manager to send plain-text notifications to end entities when their certificate is revoked.
certRequestRevoked_CA.html	Template for the Certificate Manager to send HTML-based notifications to end entities when their certificate is revoked.
certRequestRevoked_RA	Template for the Registration Manager to send plain-text notifications to end entities when their certificate is revoked.
certRequestRevoked_RA.html	Template for the Registration Manager to send HTML-based notifications to end entities when their certificate is revoked.
reqInQueue_CA	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.
reqInQueue_CA.html	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.
reqInQueue_RA	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.
reqInQueue_RA.html	Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.

Token Definitions

Table 13-2 lists and defines the tokens that can be used in the notification message templates.

Table 13-2    Notification Tokens 

Token	Description
$CertType	Specifies the type of certificate—whether SSL client (client), SSL server (server), Registration Manager's signing certificate (ra), Certificate Manager's CA signing certificate (ca), router certificate (Cisco-router), or other (other).
$ExecutionTime	Specifies the time the job (instance) was run.
$HexSerialNumber	Specifies the serial number of the certificate that has been issued in hexidecimal format.
$HttpHost	Specifies the fully qualified host name of the Certificate Manager or Registration Manager to which end entities should connect to retrieve their certificates.
$HttpPort	Specifies the port number at which the Certificate Manager or Registration Manager is listening to end-entity requests.
$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.
$RequestId	Specifies the request ID.
$RequestorEmail	Specifies the email address of the requestor.
$RequestType	Specifies the type of request that was made.
$RevocationDate	Specifies the date the certificate was revoked.
$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 when you configured this feature.
$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.
$Status	Specifies the status of the request.
$SubjectDN	Specifies the distinguished name of the certificate subject.
$SummaryItemList	Specifies the list of items in the summary notification. Each item corresponds to a certificate the job detects for renewal or for removal from the publishing directory.
$SummaryTotalFailure	Specifies the total number of items in the summary report that failed.
$SummaryTotalNum	Specifies the total number of items (certificate requests that are pending in the queue) in the summary report.
$SummaryTotalNum	Specifies the total number of items (certificates that require to be renewed, or certificates to be removed from the directory) in the summary report.
$SummaryTotalSuccess	Specifies how many of the total number of items in the summary report succeeded.

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.

Last Updated November 23, 2004