Setting up OAuth for Google and Microsoft

Jmix application can use OAuth 2.0 token-based authorization to work with email service providers. This method offers enhanced security compared to basic authentication with login and password. Many providers are gradually deprecating support of basic authentication, leaving OAuth as the only viable authentication type.

This section describes the process to obtain OAuth credentials for Google and Microsoft, along with the setup steps for Jmix application.

Google

To enable OAuth with Google, register your OAuth application and generate credentials. Then, set up your Jmix application using obtained credentials.

The instructions below are based on the Google Developer documentation for setting up OAuth for web Applications. Please check this link for the most up-to-date procedures and any use case specifics.

Create a Project

  1. Sign in to the Google Cloud console.

  2. In the top bar, click Select a project.

  3. Click New project and enter you project information.

    google oauth project

  4. Click Create.

Create an OAuth 2.0 application

  1. Select the project created previously.

  2. Click the menu button in the top left corner, and select APIs & Services → OAuth consent screen.

  3. Click Get Started.

  4. Complete the form:

    google oauth app

  5. Click Create

Enable API for your project

To send emails, your application needs Gmail API:

  1. Open the API Library. If prompted, select your project.

  2. Search for the Gmail API and enable it.

    google oauth 1

Create authorization credentials

To access the API, your application must have authorization credentials:

  1. Go to the Clients page.

  2. If prompted, select your project.

  3. Click Create client.

  4. Select the Web application application type.

  5. Complete the form:

    • Name: (Provide any descriptive name.)

    • Authorized JavaScript origins: http://localhost:8080 (Use the address of your Jmix application. The origins identify the domains from which your application can send requests to the OAuth 2.0 server.)

    • Authorized redirect URIs:

  6. Click Create.

  7. Copy or download the Client ID and Client secret and store it securely. You will need this information later.

    google oauth 3

Obtain Refresh Token

Token will be obtained via Authorization Code flow using Google Developers OAuth2 playground.

You can use other approaches to go through Authorization Code flow, such as using Postman, oauthdebugger, or manual requests.

  1. Go to Google Developers OAuth2 Playground.

  2. Open OAuth 2.0 configuration (gear icon).

    google oauth 4

    • Select the Use your own OAuth credentials checkbox.

    • Input your Client ID and Client Secret.

  3. In the list of scopes on the left select Gmail API → https://mail.google.com/

  4. Click Authorize APIs and go through consent screens.

  5. Now you have Authorization code. Click Exchange authorization code for tokens.

    google oauth 5

  6. Copy Refresh token.

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.protocol=smtp
spring.mail.username=<account_name>
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.ssl.trust=smtp.gmail.com
spring.mail.properties.mail.smtp.auth.mechanisms=XOAUTH2
spring.mail.properties.mail.smtp.sasl.enable=true
spring.mail.properties.mail.smtp.sasl.mechanisms=XOAUTH2
spring.mail.properties.mail.smtp.auth.login.disable=true
spring.mail.properties.mail.smtp.auth.xoauth2.disable=false

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

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

Alternatively, you can provide or change the refresh token value at runtime via Email → OAuth2 token view.

Add gradle dependency

Add the following dependency to your build.gradle:

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

Microsoft

To enable OAuth with Microsoft, register your OAuth application and generate credentials. Then, set up your Jmix application using obtained credentials.

The instructions below are based on the Microsoft Entra documentation. Please check this link for the most up-to-date procedures and any use case specifics.

Register the application

  1. Sign in to the Microsoft Azure portal.

  2. If you have multiple Azure Active Directory tenants, switch to the desired tenant.

  3. Navigate to App registrations.

  4. Click New Registration and provide the following information:

    • Enter a name for your app.

    • Under Supported account types, select the option applicable to your business scenario.

    • Under Redirect URI, choose Web in the Select a platform dropdown and set http://localhost:8080 (address of your Jmix application) as redirect URI.

      microsoft oauth app

  5. Click Register.

Your application is now available under Home → App Registrations. Within the application you can view values for Application (client) ID and Directory (tenant) ID.

Generate a Client Secret

  1. Open your application and navigate to Certificates & Secrets.

  2. Click New Client Secret.

  3. Enter a description and an expiry period.

  4. Click Add then copy the key Value. This is the OAuth 2.0 client secret.

    microsoft oauth 1

Configuring API Permissions

To send emails, your application needs certain permissions:

  1. Open your application and navigate to API permissions.

  2. Add SMTP.Send permission.

Obtain Refresh Token

Token will be obtained via authorization Code flow using the browser and CLI.

You can use other approaches to go through Authorization Code flow, such as using Postman, oauthdebugger, or manual requests. The process described below uses browser and CLI.

  1. Navigate to the following URL:

    // Line breaks for legibility only

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize?
client_id=<client_id>
&response_type=code
&redirect_uri=http://localhost:8080
&response_mode=query
&scope=offline_access%20https://outlook.office.com/SMTP.Send

    This may require admin consent to get access to requested API permissions. Once the user authenticates and grants consent, the Microsoft identity platform returns a response. This example shows a successful response:

    http://localhost:8080/?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&session_state=12345

  2. Save the value of the code parameter from the response.

  3. Exchange code for token:

     curl -X POST https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=<client_id>" \
-d "client_secret=<client_secret>" \
-d "code=<code_value>" \
-d "redirect_uri=http://localhost:8080" \
-d "scope=offline_access https://outlook.office.com/SMTP.Send email openid"

  4. A successful response contains a refresh_token value. Copy its value for future use.

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.protocol=smtp
spring.mail.username=<account_name>
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
spring.mail.properties.mail.smtp.ssl.trust=smtp.office365.com
spring.mail.properties.mail.smtp.auth.mechanisms=XOAUTH2
spring.mail.properties.mail.smtp.sasl.enable=true
spring.mail.properties.mail.smtp.sasl.mechanisms=XOAUTH2
spring.mail.properties.mail.smtp.auth.login.disable=true
spring.mail.properties.mail.smtp.auth.xoauth2.disable=false

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>
jmix.email.oauth2.refresh-token=<refresh_token>

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

Alternatively, you can provide or change the refresh token value at runtime via Email → OAuth2 token view.

Add gradle dependency

Add the following dependency to your build.gradle:

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