Once you have configured your mail server as described below, Crowd can send email notifications to users at specific events, such as when a user requests a password reset or a server event occurs.

On this page:

Accessing the Mail Configuration Screen

To configure SMTP email,

Mail Server Option 1: SMTP

 

Enter the details as follows:

• Server alert email — The email address which will receive notifications about server events. For example, Crowd will send an email message to this address when the number of users approaches the license limit.
• From Email Address — Crowd will add this email address as the 'sender' on the emails generated by Crowd and sent to users.
• Subject Prefix — The prefix which will appear at the start of the email subject, for all emails generated by Crowd. This can be useful for email client programs that offer filtering rules.
• Mail Server Type — Select the 'SMTP Server' radio button.
• SMTP Host — The hostname of the SMTP mail server, e.g. 'localhost' or 'smtp.acme.com'.
• SMTP Port — The port on which the SMTP mail server listens. The default is '25'.
• Timeout — Maximum time Crowd tries to send messages. The default is '60' seconds.
• Use Secure Sockets Layer (SSL) — Select this check-box if you want to access your mail server over SSL (Secure Sockets Layer). This ensures that all email communications between Crowd and your mail server are encrypted, provided your mail server supports SSL.

Additionally, as you are connecting to an SSL service, you will need to import the SMTP server certificate into a Java keystore. The process is described in Configuring Crowd to Work with SSL.

There are two options for authenticating with the SMTP Mail Server: with the username and password or with the OAuth 2.0 authentication.

Using username and password

You can connect to the mail server using basic authentication:

• Username — The username that your Crowd server will use when it logs in to your mail server.

• Password — The password that your Crowd server will use when it logs in to your mail server.

Select Send test email to make sure Crowd can send emails. Then, select Update to save the Mail Configuration.

Using OAuth 2.0

You can also connect to the mail server using OAuth 2.0. To do that, create an Application Link. More about outgoing links

You also need to give Crowd permissions to the mailbox:

1. Enter the username that your Crowd server will use when it logs in to your mail server.

2. Select Authorize and log in with OAuth 2.0 by using the same username. You'll be redirected to your service provider's site to log in to your account and authorize the connection. After that, you'll be redirected back to the application.

3. Grant permissions for Crowd to send emails.

After authorizing successfully with the mail server, Crowd obtains an authentication token and a refresh token that will be used on subsequent requests to the mail server. You only need to authorize once.

Select Send test email to make sure Crowd can send emails. Then, select Update to save the Mail Configuration.

Mail Server Option 2: JNDI Location

 

Select the 'JNDI Location' if you want to connect to a mail server via a datasource managed by your application server.

Enter the details as follows:

• Server alert email — The email address which will receive notifications about server events.
• From Email Address — Crowd will add this email address as the 'sender' on the emails generated by Crowd and sent to users.
• Subject Prefix — The prefix which will appear at the start of the email subject, for all emails generated by Crowd. This can be useful for email client programs that offer filtering rules.
• Mail Server Type — Select the 'JNDI Location' radio button.
• JNDI Location — The datasource name of a javax.mail.Session object which has been set up by your application server.

Configuring the JNDI Resource

For example, in Tomcat 5.5 (the default application server that is bundled with the Crowd distribution (not EAR-WAR)), your JNDI location would be java:comp/env/mail/CrowdMailServer, and you would add the following section in conf/server.xml or conf/Catalina/localhost/crowd.xml, inside the <Context> node:

<Context path="/crowd" docBase="${CATALINA_HOME}/crowd-webapp" reloadable="false">
  <Resource name="mail/CrowdMailServer"
    auth="Container"
    type="javax.mail.Session"
    mail.smtp.host="yourmailserver.example.com"
    mail.smtp.port="25"
    mail.transport.protocol="smtp"
    mail.smtp.auth="true"
    mail.smtp.user="your_userid"
    password="your_password"
   />
</Context>

If you have problems connecting, add a mail.debug="true" parameter, which will let you see SMTP-level details when testing the connection.

You will also need to ensure that the JavaMail classes and Java Beans Activation Framework are present in your application server's classpath.

If JavaMail is not present in your application server installation, you will receive the following error in your log file:

java.lang.NoClassDefFoundError: javax/mail/Authenticator

If the Activation Framework is not present in your application server installation, you will receive the following error in your log file:

java.lang.NoClassDefFoundError: javax/activation/DataSource

Notes

• To customize the password notification message, see the page about email notification templates.