EJBCA uses a mail service in the application server to send e-mails. These e-mails can be configured to use substitution variables in order to present relevant data to the recipients, and can be triggered to be sent on different events. Several notification schemes can be active at the same time, for example to alert different recipients on different events. 

If you configure an autogenerated password in the end entity profile you don't need to enter one on the adduser page. A generated one will automatically be sent with the e-mail. 

If you want to re-send a notification for a user, reset the status to NEW.

Setup

Mail settings in JBoss/WildFly are created during installation or configured afterward.

Fields

The following describes available e-mail notification fields.

FieldDescription
Default

Sets the Send Notification checkbox as selected by default when enrolling an end entity.

RequiredTogether with Default, this option binds the end entity to send notifications for the given events. 
Notification SenderThe sender in the resulting e-mail notification. You can also use substitution variables in this field, see Dynamic Substitution Variables. 
Notification Recipient

The Notification Recipient can have a few different values:

  • USER: send notification to the e-mail registered for the end entity.
  • An e-mail address: Send notification to the specified e-mail address. Multiple e-mail addresses can be entered, comma-separated.
  • CUSTOM: Plug-in mechanism to retrieve addresses your own way. See interface org.ejbca.core.model.ra.raadmin.ICustomNotificationRecipient for implementation details. Enter a string like "CUSTOM:org.ejbca.MyCustomPluginClass" to use.
Notification Events

The Notification Events specify which status changes for a user that will trigger a notification. The default values are suitable to send an e-mail to a user when he/she should go and pick up a certificate. You can also select for example STATUSGENERATED to send e-mail notifications to an administrator when the user picks up the certificate.

When STATUSREVOKED is selected, the notification will be triggered either if the entire user is revoked or if an individual certificate is revoked or re-activated (even though the End Entity's status will not change by the individual certificate revocation or re-activation).

For more information about each event, see Notification Events

Notification SubjectThe subject line in the resulting e-mail. You can also use substitution variables in this field, see Dynamic Substitution Variables.
Notification MessageThe notification message will be the message body of the e-mail. You may use substitution variables to add specific context to the message, see Dynamic Substitution Variables.

Dynamic Substitution Variables 

Parameters can be used with different usages of e-mail notification and mandatory parameters depend on the input data.

The following parameters can be set:

  • ${NL} = New Line in message
  • ${DATE} or ${current.DATE} = The current date

Variables used with userdata:

  • ${USERNAME} or ${user.USERNAME} = The user's username.
  • ${PASSWORD} or ${user.PASSWORD} = The user's password, or "enrollment code" as it is called in most pages in the public web.
  • ${UID} or ${user.UID} = The user's unique identifier.
  • ${CN} or ${user.CN} = The common name of the user.
  • ${SN} or ${user.SN} = The serial number (in DN) of the user.
  • ${O} or ${user.O} = The user's organization.
  • ${OU} or ${user.OU} = The user's organizational unit.
  • ${C} or ${user.C} = The user's country.
  • ${user.E} = The user's e-mail address from Subject DN.
  • ${user.EE.EMAIL} = Ther user's e-mail address from the End Entity data.
  • ${user.SAN.EMAIL} = The user's e-mail address from Subject Alternative Name, RFC822Name field.
  • ${user.TIMECREATED} = The time the user was created.
  • ${user.TIMEMODIFIED} = The time the user was modified.
  • ${requestAdmin.CN} = The common name of the requesting administrator.
  • ${requestAdmin.EE.EMAIL} = The e-mail address of the administrator adding the end entity according to the administrator's End Entity data.
  • ${requestAdmin.SAN.EMAIL} = The e-mail address of the administrator adding the end entity according to the administrator's Subject Alternative Name, RFC822Name field.
  • ${approvalAdmin.XX} variables from below can be used to get the administrator who adds an end entity.

Variables used with approvals:

  • ${approvalAdmin.USERNAME} = The last approving administrator's username.
  • ${approvalAdmin.CN} = The common name of the last approving administrator.
  • ${approvalAdmin.SN} = The last approving administrator's DN serialNumber.
  • ${approvalAdmin.O} = The last approving administrator's organization.
  • ${approvalAdmin.OU} = The last approving administrator's organization unit.
  • ${approvalAdmin.C} = The last approving administrator's country.
  • ${approvalAdmin.E} = The last approving administrator's e-mail address from Subject DN.
  • ${approvalRequestID} = The ID of the approval request that was created.

Variables used with expiring certificates:

  • ${expiringCert.CERTSERIAL} = The serial number of the certificate about to expire.
  • ${expiringCert.EXPIREDATE} = The date the certificate will expire.
  • ${expiringCert.CERTSUBJECTDN} = The certificate subject DN.
  • ${expiringCert.CERTISSUERDN} = The certificate issuer DN.

Variables used with revocation or re-activation of individual End Entity certificates:

  • ${revokedCertificate.CERTSERIAL} = The serial number of the revoked certificate.
  • ${revokedCertificate.EXPIREDATE} = The date the revoked certificate will expire.
  • ${revokedCertificate.CERTSUBJECTDN} = The certificate subject DN.
  • ${revokedCertificate.CERTISSUERDN} = The certificate issuer DN.
  • ${revokedCertificate.REVOCATIONSTATUS} = The new revocation status of the certificate (Active/Revoked).
  • ${revokedCertificate.REVOCATIONREASON} = The new revocation reason of the certificate (unspecified, keyCompromise, ...).

Notification Events

Event NameDescription

STATUSNEW

Triggered upon the end entity being created.
STATUSFAILEDTriggered if certificate generation failed. 
STATUSINITIALIZEDLegacy value, no longer used in EJBCA.
STATUSINPROCESSLegacy value, no longer used in EJBCA.
STATUSGENERATEDTriggered when a certificate has been issued for this end entity.
STATUSREVOKEDTriggered when the end entity is set as revoked.
STATUSHISTORICALLegacy value, no longer used in EJBCA.
STATUSKEYRECOVERYTriggered when the end entity has been set up for key recovery by an administrator.

Examples

If you need to comply with PCI or the lighter levels of FIPS-140/160, it may be required to configure a two-step issuance process.

Set up notifications by creating three e-mail notifications according to the following:

  1. To: USER
    E-mail notification to just the user with the URL to pick up the cert and the username. Make clear in the message that he or she will be contacted by the approving admin with the password.
  2. To: ${approvalAdmin.E}
    E-mail notification to the approving admin with the password (but not the username) and a message which makes clear that this password is to be passed to the user, by phone or f2f (but not by e-mail).
  3. To: ca-team@foo... **
    E-mail notification of the issuing to the auditor mailing lists, without above username/password.