Red Hat SummitCe contenu n'est pas disponible dans la langue sélectionnée.
Chapter 13. Using automated notifications
Certificate System can be configured to send automatic email notifications to end users when certificates are issued or revoked or to an agent when a new request has arrived in the agent request queue. This chapter describes automated notifications and details how to enable, configure, and customize the notification email messages that are sent.
Automated notifications are not to be confused with automated jobs. See Chapter 14, Setting automated jobs for more on this topic.
Because of the types of notifications that can be sent, only Certificate Managers have the ability to be configured for notifications; this option is not available on the other subsystems.
13.1. About automated notifications for the CA
Automated notifications are email messages sent when a specified event occurs. The system uses listeners that monitor the system to determine when a particular event has occurred; when the event happens, then the system is triggered to send an email to the configured recipient.
Each type of notification uses a template, either in plain text or HTML, to construct the notification message. The template contains text and tokens that are expanded to fill in the correct information for a particular event. You can customize the messages by changing the text and tokens contained in the templates. You can also customize the HTML templates for different appearances and formatting.
13.1.1. Types of automated notifications
There are three types of automated notifications:
Certificate Issued.
A notification message is automatically sent to users who have been issued certificates. A rejection message is sent to a user if the user’s certificate request is rejected.
Certificate Revocation.
A notification message is automatically sent to users when the user certificate is revoked.
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 addresses set for the agent. This notification type sends an email every time a message enters the queue. For more information about the request in queue job, see Section 14.1.2, “requestInQueueNotifier (RequestInQueueJob)”.
There is also a job that sends a notification to agents about the status of the queue, which includes a summary of the queue status at certain intervals.
13.1.2. Determining end-entity email addresses
The notification system determines the email address of an end entity by checking:
- The certificate request or revocation request
- The subject name of the certificate
- 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 of the Notification panel.
13.1.3. Creating custom notifications for the CA
It can be possible to create custom notification functions to handle other PKI operations, such as token enrollments, by editing existing email notifications plug-ins for the Certificate System CA. Before attempting to create or use custom notification plug-ins, contact support.
13.2. Configuring automated notifications for the CA
13.2.1. Configuring automated notifications in the console
Open the Certificate Manager Console.
pkiconsole https://server.example.com:8443/ca
Notepkiconsoleis being deprecated.- Open the Configuration tab.
Open the Certificate Manager heading in the navigation tree on the left. Then select Notification.
The Notification tabs appear in the right side of the window.
Notifications can be sent for three kinds of events: newly-issued certificates, revoked certificates, and new certificate requests. To send a notification for any event, select the tab, check the Enable checkbox, and specify information in the following fields:
- Sender’s E-mail Address. Type the sender’s full email address of the user who is notified of any delivery problems.
- Recipient’s E-mail Address. These are the email addresses of the agents who will check the queue. To list more than one recipient, separate the email addresses with commas. For new requests in queue only.
- 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 use to construct the message content.
Click .
NOTEMake sure the mail server is set up correctly. See Section 13.4, “Configuring a mail server for notifications”.
- Customize the notification message templates. See Section 13.3, “Customizing CA notification messages” for more information.
- Test the configuration. See Section 13.2.3, “Testing configuration”.
13.2.2. Configuring specific notifications by editing the CS.cfg file
Stop the CA subsystem.
# pki-server stop instance_name
-
Open the
CS.cfgfile for that instance. This file is in the instance’sconf/directory. Edit all of the configuration parameters for the notification type being enabled.
For certificate issuing notifications, there are four parameters:
ca.notification.certIssued.emailSubject ca.notification.certIssued.emailTemplate ca.notification.certIssued.enabled ca.notification.certIssued.senderEmail
For certificate revocation notifications, there are four parameters:
ca.notification.certRevoked.emailSubject ca.notification.certRevoked.emailTemplate ca.notification.certRevoked.enabled ca.notification.certRevoked.senderEmail
For certificate request notifications, there are five parameters:
ca.notification.requestInQ.emailSubject ca.notification.requestInQ.emailTemplate ca.notification.requestInQ.enabled ca.notification.requestInQ.recipientEmail ca.notification.requestInQ.senderEmail
The parameters for the notification messages are explained in Section 13.2, “Configuring automated notifications for the CA”.
- Save the file.
Restart the CA instance.
pki-server start instance_name
- If a job has been created to send automated messages, check that the mail server is correctly configured. See Section 13.4, “Configuring a mail server for notifications”.
- The messages that are sent automatically can be customized; see Section 13.3, “Customizing CA notification messages” for more information.
13.2.3. Testing configuration
To test whether the subsystem sends email notifications as configured, do the following:
- Change the email address in the notification configuration for the request in queue notification to an accessible agent or administrator email address.
Open the end-entities page, and request a certificate using the agent-approved enrollment form.
When the request gets queued for agent approval, a request-in-queue email notification should be sent. Check the message to see if it contains the configured information.
Log into the agent interface, and approve the request.
When the server issues a certificate, the user receive a certificate-issued email notification to the address listed in the request. Check the message to see if it has the correct information.
Log into the agent interface, and revoke the certificate.
The user email account should contain an email message reading that the certificate has been revoked. Check the message to see if it has the correct information.
13.3. Customizing CA notification messages
The email notifications are constructed using a template for each type of message. This allows messages to be informative, easily reproducible, and easily customizable. The CA uses templates for its notification messages. Separate templates exist for HTML and plain text messages.
Each type of CA notification message has an HTML template and a plain text template associated with it. Messages are constructed from text, tokens, and, for the HTML templates, HTML markup. Tokens are variables, identified by a dollar sign ($), in the message that are replaced by the current value when the message is constructed. See Table 13.3, “Notification variables” for a list of available tokens.
The contents of any message type can be modified by changing the text and tokens in the message template. The appearance of the HTML messages can be changed by modifying the HTML commands in the HTML message template.
The default text version of the certificate-issuance-notification message is 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& serialNumber=$SerialNumber Please contact your admin if there is any problem. And, of course, this is just a \$SAMPLE\$ email notification form.
This template can be customized as desired, by rearranging, adding, or removing tokens and text, as shown:
THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER Your certificate has been issued! You can pick up your new certificate at the following website: https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial& serialNumber=$SerialNumber This certificate has been issued with the following information: Serial Number= 0x$HexSerialNumber Name of Certificate 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 are located in the /var/lib/pki/ instance_name/ca/emails directory.
You can change the name and location of these messages; make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates; these names 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.
The following table lists the default template files provided for creating notification messages. Table 13.2, “Job notification email templates” lists the default template files provided for creating job summary messages.
| Filename | Description |
|---|---|
| certIssued_CA | Template for plain text notification emails to end entities when certificates are issued. |
| certIssued_CA.html | Template for HTML-based notification emails to end entities when certificates are issued. |
| certRequestRejected.html | Template for HTML-based notification emails to end entities when certificate requests are rejected. |
| certRequestRevoked_CA | Template for plain text notification emails to end entities when a certificate is revoked. |
| certRequestRevoked_CA.html | Template for HTML-based notification emails to end entities when a certificate is revoked. |
| reqInQueue_CA | Template for plain text notification emails to agents when a request enters the queue. |
| reqInQueue_CA.html | Template for HTML-based notification emails to agents when a request enters the queue. |
| Filename | Description |
|---|---|
| rnJob1.txt | Template for formulating the message content sent to end entities to inform them that their certificates are about to expire and that the certificates should be renewed or replaced before they expire. |
| rnJob1Summary.txt |
Template for constructing the summary report to be sent to agents and administrators. Uses the |
| rnJob1Item.txt | Template for formatting the items included in the summary report. |
| riq1Item.html |
Template for formatting the items included in the summary table, which is constructed using the |
| riq1Summary.html | Template for formulating the report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager. |
| publishCerts |
Template for the report or table that summarizes the certificates to be published to the directory. Uses the |
| publishCertsItem.html | Template for formatting the items included in the summary table. |
| ExpiredUnpublishJob |
Template for the report or table that summarizes removal of expired certificates from the directory. Uses the |
| ExpiredUnpublishJobItem | Template for formatting the items included in the summary table. |
The following table lists and defines the variables that can be used in the notification message templates.
| Token | Description |
|---|---|
| $CertType | Specifies the type of certificate; these can be any of the following:
|
| $ExecutionTime | Gives the time the job was run. |
| $HexSerialNumber | Gives the serial number of the certificate that was issued in hexadecimal format. |
| $HttpHost | Gives the fully qualified host name of the Certificate Manager to which end entities should connect to retrieve their certificates. |
| $HttpPort | Gives the Certificate Manager’s end-entities (non-TLS) port number. |
| $InstanceID | Gives the ID of the subsystem that sent the notification. |
| $IssuerDN | Gives the DN of the CA that issued the certificate. |
| $NotAfter | Gives the end date of the validity period. |
| $NotBefore | Gives the beginning date of the validity period. |
| $RecipientEmail | Gives the email address of the recipient. |
| $RequestId | Gives the request ID. |
| $RequestorEmail | Gives the email address of the requester. |
| $RequestType | Gives the type of request that was made. |
| $RevocationDate | Gives the date the certificate was revoked. |
| $SenderEmail | Gives the email address of the sender; this is the same as the one specified in the Sender’s E-mail Address field in the notification configuration. |
| $SerialNumber | Gives the serial number of the certificate that has been issued; the serial number is displayed as a hexadecimal value in the resulting message. |
| $Status | Gives the request status. |
| $SubjectDN | Gives the DN of the certificate subject. |
| $SummaryItemList | Lists the items in the summary notification. Each item corresponds to a certificate the job detects for renewal or removal from the publishing directory. |
| $SummaryTotalFailure | Gives the total number of items in the summary report that failed. |
| $SummaryTotalNum | Gives the total number of certificate requests that are pending in the queue or the total number of certificates to be renewed or removed from the directory in the summary report. |
| $SummaryTotalSuccess | Shows how many of the total number of items in the summary report succeeded. |
13.4. Configuring a mail server for notifications
The notifications and jobs features use the mail server configured in the Certificate System CA instances to send notification messages.
Before you start setting up the mail server, ensure the following parameters are specified in the CS.cfg configuration file:
smtp.host=localhost smtp.port=25
Set up a mail server by doing the following:
Open the CA subsystem administrative console. For example:
pkiconsole https://server.example.com:8443/ca
Notepkiconsoleis being deprecated.- In the Configuration tab, highlight the instance name at the top, and select the SMTP tab.
Supply the server name and port number of the mail server.
The server name is the fully qualified DNS hostname of the machine on which the mail server is installed, such as
mail.example.com. By default, the hostname of the mail server islocalhostinstead of the actual hostname.The default port number on which the SMTP mail server listens is
25.- Click .
