Mail Server Authentication

The add-on sends emails through the SMTP server defined by Spring Boot mail properties. The application can log in to the server in one of two ways:

Basic Authentication

The add-on uses basic authentication unless OAuth2 authentication is enabled by the jmix.email.oauth2.enabled property. Set the login and password of the mailbox account and turn on SMTP authentication:

application.properties
spring.mail.host=smtp.company.com
spring.mail.port=587
spring.mail.protocol=smtp
spring.mail.username=username
spring.mail.password=password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

Google and Microsoft 365 restrict basic authentication for SMTP. Use OAuth2 authentication for them.

To check the connection, click Test connection in the Email Connection view.

OAuth2 Authentication

With OAuth2 authentication, the add-on passes an access token to the SMTP server instead of a password, using the XOAUTH2 mechanism. The add-on gets access tokens from the provider using a refresh token.

To set up OAuth2 authentication, follow the section for your mail provider:

Then connect the mailbox account.

See OAuth2 Authentication Details for how the add-on uses the mail properties and the refresh token.

Using a Gmail or Google Workspace Mailbox

The instructions below are based on the Google Developer documentation for using OAuth 2.0 for web server applications. Check this page for the most up-to-date procedures.

Register an OAuth Client in Google Cloud

In the Google Cloud console, do the following:

  1. Create or select a project.

  2. Open the Google Auth Platform. In a new project, click Get started and enter the app information and contact email. Select the audience: Internal for a Google Workspace mailbox or External for a Gmail account. In a project that already has an OAuth consent screen, the same settings are on the Branding and Audience pages.

  3. If the audience is External and the app has the Testing publishing status, add the mailbox account as a test user on the Audience page. Authorizations of test users expire seven days after consent, and then you need to connect the account again.

  4. Create an OAuth client of the Web application type with the http://localhost:8080/email/oauth2/callback authorized redirect URI. Replace http://localhost:8080 with the address of your application, including the context path if the application has one.

  5. Copy the Client ID and Client secret of the client.

Configure Application Properties

Use the credentials to configure the application.properties file of your Jmix application:

application.properties
spring.mail.host=smtp.gmail.com
spring.mail.port=587
spring.mail.username=<account_name>
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

jmix.email.oauth2.enabled=true
jmix.email.oauth2.provider=google
jmix.email.oauth2.client-id=<client_id>
jmix.email.oauth2.secret=<client_secret>

# Default sender address for emails that do not set their own sender
jmix.email.from-address=<account_name>

Where <account_name> is the email address used for configuration. And <client_id>, <client_secret> are values obtained during the configuration process.

Add Gradle Dependency

Add the following dependency to your build.gradle:

implementation 'com.google.auth:google-auth-library-oauth2-http'

Connect Mailbox Account

Run the application and connect the mailbox account using Connect via authorization code, as described in Connecting Mailbox Account.

Using a Microsoft 365 Mailbox

The instructions below combine the Microsoft Entra quickstart for registering an application with the Exchange Online documentation on authenticating SMTP connections with OAuth. Check these pages for the most up-to-date procedures.

Register an App in Microsoft Entra

In the Microsoft Entra admin center, browse to Entra ID > App registrations and do the following:

  1. Click New registration, enter a name, select the supported account types and click Register.

  2. On the Authentication page, open the Redirect URI configuration tab, click Add Redirect URI, select Web and enter http://localhost:8080/email/oauth2/callback. Replace http://localhost:8080 with the address of your application, including the context path if the application has one.

  3. On the Certificates & secrets page of the application, create a client secret and copy its Value.

  4. On the API permissions page, add the delegated SMTP.Send permission. If users in your tenant can’t consent to applications, grant admin consent for it.

  5. To connect the mailbox account using Connect via device code, open the Settings tab of the Authentication page and enable Allow public client flows.

  6. Copy the Application (client) ID and Directory (tenant) ID from the Overview page.

SMTP AUTH must be enabled for the mailbox account: in the Microsoft 365 admin center, select Authenticated SMTP in the email app settings of the user. See Enable or disable SMTP AUTH in Exchange Online.

Configure Application Properties

Use the credentials to configure the application.properties file of your Jmix application:

application.properties
spring.mail.host=smtp.office365.com
spring.mail.port=587
spring.mail.username=<account_name>
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.starttls.required=true

jmix.email.oauth2.enabled=true
jmix.email.oauth2.provider=microsoft
jmix.email.oauth2.client-id=<client_id>
jmix.email.oauth2.secret=<client_secret>
jmix.email.oauth2.tenant-id=<tenant_id>

# Default sender address for emails that do not set their own sender
jmix.email.from-address=<account_name>

Where <account_name> is the email address used for configuration. And <client_id>, <client_secret>, <tenant_id> are values obtained during the configuration process. Without jmix.email.oauth2.tenant-id, the add-on uses the common tenant, which Microsoft supports only for multitenant applications.

Add Gradle Dependency

Add the following dependency to your build.gradle:

implementation 'com.microsoft.azure:msal4j'

Connect Mailbox Account

Run the application and connect the mailbox account using Connect via authorization code or Connect via device code, as described in Connecting Mailbox Account.

Connecting Mailbox Account

Since Jmix 3.1

After you configure the application, connect the mailbox account in the Email Connection view:

  1. Run the application and open Email → Email connection.

  2. Click Connect via authorization code. On the provider page, sign in to the mailbox account specified in spring.mail.username and grant access. When the application shows the result, click Continue.

    For Microsoft, you can click Connect via device code instead. Open the link shown in the dialog on any device, enter the code and sign in to the mailbox account. This flow requires public client flows to be allowed in the app registration.

  3. Click Test connection.

The add-on builds the redirect URI from the address at which the server received the request: the scheme, host, port and context path. Behind a reverse proxy, this address can differ from the public one, and the provider rejects the request because the redirect URI doesn’t match. In this case, set the registered redirect URI in the jmix.email.oauth2.redirect-uri property.

Entering Refresh Token Manually

If the provider doesn’t accept the application address as a redirect URI, get a refresh token in another way (for example, in the OAuth 2.0 Playground for Google, in Postman or by sending requests to the provider manually). Add the address that receives the provider response to the redirect URIs of the OAuth client. Then do one of the following:

The token must be issued to the client ID of the application with the following scopes:

  • Google: https://mail.google.com/

  • Microsoft: https://outlook.office.com/SMTP.Send and offline_access

For Microsoft, a refresh token that you enter manually must be obtained with the client secret (for example, by the authorization code flow, but not by the device code flow). Otherwise, Microsoft rejects it when the add-on exchanges it for an access token.

OAuth2 Authentication Details

OAuth2 Configuration Requirements

When OAuth2 authentication is enabled, the add-on handles the mail properties as follows:

  • spring.mail.username is required. It is the mailbox account that the application logs in to.

  • spring.mail.password is ignored. If it is set, the add-on logs a warning.

  • The add-on sets the mail.smtp.auth=true and mail.smtp.auth.mechanisms=XOAUTH2 JavaMail properties, unless you set them in spring.mail.properties.*.

The application fails to start if spring.mail.username, jmix.email.oauth2.provider, jmix.email.oauth2.client-id or jmix.email.oauth2.secret is not set, or if the library of the provider is missing.

Refresh Token

The add-on stores the refresh token in the database. The application has one stored token, and each connected account replaces it.

The jmix.email.oauth2.refresh-token property sets an initial token value. The add-on uses it only while no token is stored in the database.

When Microsoft returns a new refresh token, the add-on stores it.