E-mail Notifications

EJBCA uses a mail service in the application server to send emails. Mail settings in JBoss/WildFly are created during installation or configured afterward.

Approving End Entity E-mail Notifications

Email notification can be sent when the status changes for an end entity, for example when a new user is added (status changes to new).

To configure email notifications in EJBCA:

Create a new end entity profile to be able to issue certificates to end users using email notifications. Under the RA functions, select Edit End Entity Profiles and add a new profile. Select the profile and go to Edit End Entity profile to Enable Send Notifications and create the notification message. Make sure the option Use Send Notification is enabled.
Add a new end entity. Select the new end entity profile created above and make sure the option Send Notification is enabled. Enter the from-address, subject, and specify a message using the variables defined for dynamic substitution in the next section. Use ${NL} for newline in the mail message.

The Notification Recipient can have a few different values:

USER: send notification to the email registered for the end entity.
foo@bar.com: send notification to the specified email address. Multiple email 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.

You can also use the substitution variable in the notification sender and recipie/nt fields. See samples below.

The Notification Events specify which status changes for a user that will trigger a notification. The default values are suitable to send an email to a user when he/she should go and pick up a certificate. You can also select for example STATUSGENERATED to send email 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).

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

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

Dynamic Substitution Variables

Parameters can be used with different usages of email 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 email address from Subject DN.
${user.EE.EMAIL} = Ther user's email address from the End Entity data.
${user.SAN.EMAIL} = The user's email 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 email address of the administrator adding the end entity according to the administrator's End Entity data.
${requestAdmin.SAN.EMAIL} = The email 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 email 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, ...).

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 email notifications according to the following:

To: USER
Email 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.
To: ${approvalAdmin.E}
Email 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 email).
To: ca-team@foo... **
Email notification of the issuing to the auditor mailing lists, without above username/password.