Sending Email

CAS presents the ability to notify users on select actions via email messages. Example actions include notification of risky authentication attempts or password reset links/tokens, etc. Configuring an email provider (i.e. Amazon Simple Email Service ) is a matter of defining SMTP settings. Each particular feature in need of email functionality should be able to gracefully continue in case settings are not defined.

Default support for email notifications is automatically enabled/included by the relevant modules using the following module:

<dependency>
    <groupId>org.apereo.cas</groupId>
    <artifactId>cas-server-core-notifications</artifactId>
    <version>${cas.version}</version>
</dependency>

implementation "org.apereo.cas:cas-server-core-notifications:${project.'cas.version'}"

dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
    }
}

dependencies {
    implementation "org.apereo.cas:cas-server-core-notifications"
}

dependencies {
    /*
    The following platform references should be included automatically and are listed here for reference only.
            
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    */

    implementation "org.apereo.cas:cas-server-core-notifications"
}

You need not explicitly include this module in WAR Overlay configurations, except when there is a need to access components and APIs at compile-time.

Email Server Settings

The following settings may also need to be defined to describe the mail server settings:

spring.mail.default-encoding=UTF-8

Default MimeMessage encoding.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value. The only possible exception to this rule is when naming actuator endpoints; The name of the actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.default-encoding=UTF-8

This is the most common form of property configuration that is recognized by CAS, regardless of the actual property source, which might in fact be managed separately outside the CAS environment, by another system or cloud framework.

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    default-encoding: "UTF-8"

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.default-encoding="UTF-8" -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory. Note the placement of the system property which must be specified before the CAS web application is launched.

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_DEFAULT_ENCODING="UTF-8"

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.default-encoding="UTF-8"

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.host=

SMTP server host. For instance, 'smtp.example.com'.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.host=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    host: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.host="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_HOST="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.host="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.jndi-name=

Session JNDI name. When set, takes precedence over other Session settings.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.jndi-name=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    jndi-name: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.jndi-name="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_JNDI_NAME="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.jndi-name="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.password=

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.password=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    password: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.password="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_PASSWORD="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.password="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.port=

SMTP server port.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.port=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    port: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.port="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_PORT="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.port="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.properties=

Additional JavaMail Session properties.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.properties=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    properties: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.properties="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_PROPERTIES="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.properties="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.protocol=smtp

Protocol used by the SMTP server.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.protocol=smtp

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    protocol: "smtp"

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.protocol="smtp" -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_PROTOCOL="smtp"

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.protocol="smtp"

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.test-connection=false

Whether to test that the mail server is available on startup.

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.test-connection=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    test-connection: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.test-connection="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_TEST_CONNECTION="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.test-connection="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

spring.mail.username=

_{How can I configure this property?}

Configuration properties can be included and activated using the following strategies.

:information_source: Note

CAS properties can be specified using the Java configuration property syntax in any and all .properties files:

spring.mail.username=...

CAS properties can be specified using the YAML syntax:

spring: 
  mail: 
    username: "..."

Note that YAML is very specific about structure and indentation. Be sure to verify the correctness of the final result with your YAML validator of choice.

CAS properties can be passed to the CAS web application as system properties, when the application is launched:

java -Dspring.mail.username="..." -jar build/libs/cas.war

CAS properties can specified as system environment variables before the CAS web application is launched:

export SPRING_MAIL_USERNAME="..."

java -jar build/libs/cas.war

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

CAS properties can be passed to the CAS web application as command-line arguments, when the application is launched:

java -jar build/libs/cas.war --spring.mail.username="..."

The above example assumes that the CAS web application is packaged as cas.war with an embedded server container and can be found in the build/libs directory.

Email Message Body

The body of the email message that is defined in the CAS configuration can be constructed using the following strategies.

Default

By default, the body of the email message that is defined in the CAS configuration is formatted using special placeholders for variables that are marked as %s. The formatting of the message closely follows the semantics of JDK’s String.format(). Arguments referenced by the format specifiers in the format string are passed by CAS depending on the context or feature. If there are more arguments than format specifiers, the extra arguments are ignored.

Template File

The configuration setting for the email message body can also accept a path to an external file (i.e. HTML). The contents of the file are processed for placeholder variables and values using the same default strategy.

The email template file can also be processed via GStringTemplateEngine, if the path ends with the file extension .gtemplate. Input parameters are passed to the template which will substitute variables and expressions into placeholders in a template source text to produce the desired output.

An example template, with variables and expressions such as firstname file would be:

Dear <%= firstname %> $lastname,
We <% if (accepted) print 'are pleased' else print 'regret' %> \
to inform you that your paper entitled
'$title' was ${ accepted ? 'accepted' : 'rejected' }.

Note that the template file can be automatically localized per the available locale parameter. For example, if the template file is specified as EmailTemplate.html, and the available locale is de , CAS will automatically check for EmailTemplate_de.html first and will then fall back onto the default if the localized template file is not found.

Groovy Script

The configuration setting for the email message body can also point to an external Groovy script to build the contents of the message body dynamically. The script may be designed as:

def run(Object[] args) {
    def values = (args[0] as Map).values()
    def logger = args[1]
    def locale = args.length == 3 ? args[2] : null
    
    logger.info("Parameters are {} with locale {}", args[0], locale)
    return String.format("%s, %s", values[0], values[1]);
}

The following parameters are passed to the script:

Parameter	Description
`parameters`	`Map<String, ?>` of parameters passed by CAS, depending on feature and/or context.
`logger`	The object responsible for issuing log messages such as `logger.info(...)`.
`locale`	The object representing the available `Locale`, if any and available.

The outcome of the script should be message body text.

Custom

You may also define your own communication manager that would be tasked to send emails, etc using the following bean definition and by implementing CommunicationsManager:

@Bean
public CommunicationsManager communicationsManager() {
    return new MyCommunicationsManager();   
}

See this guide to learn more about how to register configurations into the CAS runtime.