SMTP Email Provider

The most common way to send out email messages is through the SMTP protocol.

Configuration#

The following configuration settings are available for the SMTP Email Provider:

ConfigurationMandatoryDescription
smtp-hostYesThe SMTP server name.
smtp-portYesThe port of the SMTP server. Defaults to 587.
enable-tlsYesWhether to use a TLS-protected connection to communicate with the server. Defaults to false.
default-senderYesAn email address (RFC 822) that is used as the sender of each outgoing email message, accepting two formats: "user@host.domain" or "User Name <user@host.domain>".

These settings must be used to configure SMTP email provider in the facilities section.

The SMTP server connection can authenticate using either basic authentication or OAuth 2.0. The two methods are mutually exclusive. When neither is configured, the connection is made without authentication.

Configuring an SMTP Email Provider facility in the Curity Admin UI
Configuring an SMTP Email Provider facility in the Curity Admin UI. (Admin UI version: 11.5)

Basic Authentication#

The SMTP Email Provider can authenticate to the SMTP server using a static username and password (basic authentication). To enable it, configure the username/password settings on the SMTP provider:

ConfigurationMandatoryDescription
usernameYesA username to use to authenticate with the SMTP server.
passwordYesA password to use to authenticate with the SMTP server. It is stored encrypted.

OAuth 2.0 Authentication#

Instead of a static username/password, the SMTP Email Provider can authenticate to the SMTP server using an OAuth 2.0 access token via the SMTP AUTH XOAUTH2 SASL mechanism. the Curity Identity Server obtains the access token itself using the OAuth 2.0 client credentials grant, caches it, and reuses it across sends until it is near expiry (so a new token is not requested for every email). To enable OAuth authentication, configure the oauth settings on the SMTP provider:

ConfigurationMandatoryDescription
token-endpointYesThe complete URL of the OAuth 2.0 token endpoint used to obtain the access token.
client-idYesThe client id used when obtaining an access token.
client-secretYesThe client secret used when obtaining an access token. It is stored encrypted.
scopeNoThe scopes to request when obtaining an access token.
http-clientYesA reference to a configured HTTP Client facility used to perform the token request. This controls the TLS trust, proxy, and timeouts used when calling the token endpoint.
token-expiration-time-skewNoThe time skew, in seconds, applied when deciding whether the cached token should be considered expired (for example, with a skew of 10 seconds a token that expires in 9 seconds is treated as already expired). Defaults to 10.

The XOAUTH2 mechanism authenticates a specific mailbox. The Curity Identity Server uses the SMTP provider’s default-sender address as the mailbox identity presented during authentication, so the default-sender must be a mailbox that the configured client is authorized to send as.

Only the client credentials grant is supported (application-only, no interactive user). If the token endpoint cannot be reached or does not return a usable access token, the email is not sent and the email provider’s failed-connection alarm is raised.

SMTP Properties#

The SMTP Email Provider is implemented on top of the Jakarta Mail API. Hence, mail.smtp system properties may be used to configure many aspects of the email service.

By default, the Curity Identity Server applies the following properties when connecting to an SMTP server:

System PropertyDefaultDescription
mail.smtp.connectiontimeout10000Timeout in milliseconds for establishing a TCP connection to the server.
mail.smtp.timeout6000Timeout in milliseconds for waiting for a response from the server.
mail.smtp.writetimeout6000Timeout in milliseconds for sending data to the server.

These defaults can be overridden by passing JVM system properties at startup, for example:

-Dmail.smtp.connectiontimeout=15000
-Dmail.smtp.timeout=120000
-Dmail.smtp.writetimeout=120000

A complete list of all SMTP system properties is available in the Jakarta Mail SMTP documentation.

DomainKeys Identified Mail#

It is possible to sign messages sent via SMTP using DomainKeys Identified Mail (DKIM) Signatures. This helps the receiver know that the mail originated from a trustworthy source. The technique is defined in RFC 6376, and is well documented from various sources. The particulars of the implementation provided in the Curity Identity Server is described here. Specifically, the following constraints are important to be aware of:

  • Only RSA keys that are at least 1024 bits can be used to sign an email message.
  • Canonicalization is always performed using relaxed/relaxed. In other words, the body and headers are normalized using those methods, and this cannot be configured.
  • rsa-sha256 will always be used as the signing and hashing algorithm. This is not configurable.
  • The default-sender must include an at symbol (@).
  • The public key query method cannot be configured, so the default of dns/txt will be assumed by the email receiver.
  • The agent (or AUID) is always the same as the default-sender and is not configurable.
  • The signature timestamp and expiration cannot be specified.
  • The body signature length is never used.
  • Only the following headers will be signed (when applicable):
    • Cc
    • Content-Description
    • Content-Type
    • Date
    • From
    • Message-Id
    • MIME-Version
    • Sender
    • Subject
    • To
  • The SDID or domain that is used in the DKIM-Signature will be the one specified after the at symbol (@) of the default-sender.
  • The selector that is used in the DKIM-Signature must be in the same domain.

On the last two points, an example can help clarify the behavior. Suppose the default-sender was configured to be noreply@example.com and the selector was configured to be brisbane, then the DKIM-Signature would include the tags d=example.com, s=brisbane, and i=noreply@example.com. Because the query method for the public key will always be assumed by the receiver to be text, for this example, the DNS TXT record brisbane._domainkey.example.com should be created that contains the public key.

If the DKIM signature is said to be invalid by the validator, check that the From email header that it received is the same as the value of the default-sender. If they are different, the signature will certainly be invalid.

Embedded Content#

The SMTP email provider supports adding embedded/inline content to email messages. When the email data to be sent contains embedded content, the HTML version of the email message is a multipart message with additional parts for the embedded contents. Each part has a Content-ID which can be used to reference it from the main HTML body part using Content-ID URLs.

For more information on how to develop an SMTP Email message content plugin see the developer guide.

Was this helpful?