E-mail Notifications

Mail settings in JBoss is created when running the 'ant deploy' or 'ant deploy-service' using the values specified in conf/mail.properties (or default). It is (automatically) configured in $APPSRV_HOME/server/default/deploy/ejbca-mail-service.xml for JBoss. For other containers you must create a mail service with the same JNDI name as specified in conf/mail.properties.

ApprovingEnd Entity E-mail Notifications

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

To configure email notifications in EJBCA:

  1. You must create a new end-entity profile to be able to issue certificates to end users using email notifications. Under the RA functions, choose Edit End Entity Profiles and add a new profile. Select the profile and go into Edit End Entity profile. In this page you can Enable Send Notifications and create the notification message. Make sure the checkbox Use Send Notification is checked.

  2. Add a new end entity. You must select the new end entity profile you created above. Make sure the checkbox Send Notification is checked. Enter the from-address and subject. Enter 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 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 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 that can be used with different usages of email notification. All parameters isn't always set, it depends 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

In certain circumstances, e.g. when you need to comply with PCI or the lighter levels of FIPS-140/160, it may be required to configure a 2 step issuance process. This can by done by using the notifications. Create 3 email notifications:

  1. 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.

  2. 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).

  3. To: ca-team@foo... **
    Email notification of the issuing to the auditor mailing lists - without above username/password.