Onit Documentation

Configuring a SMTP OAuth Connection

by [email protected] Updated on

Configuring the App Registration

This step must be done by someone with access to the client’s Azure configuration.

1. Go to Azure App registrations and Click “+New Registration”

Go to Azure App registrations at https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade and click “+New Registration” to open the App registrations page.

2. Setup a Single Tenant Account

Name and redirect URI can be anything but a redirect URI must be entered.

3. Click “Add a certificate or a secret” to Add a New Secret

You should be taken to the main page for the app. Once on the homepage, find "Client credentials: Add a certificate or a secret” and open the link to add a new secret.

4. Click “+ New client secret”

a. Provide a brief description of where this secret will be used and select an expiration length.

A longer expiration is better if the client does not want to update the secret frequently.

b. Once the secret is created, copy the value and secret ID.

This will be your only chance to copy the value so keep it somewhere secure.

5. Setup API Permissions

  1. Click “+ Add a permission” and add the following:
  2. Grant admin consent by clicking “Grant admin consent for …”. After consent is successfully granted, a green check mark and "Granted for ..." will appear under the Status column (shown below).

6. Copy Important Information

Grab the following information for use later:

  1. Directory (tenant) ID
  2. Client Secret value
  3. Application (client) ID
  4. Redirect-URI

Generating the Refresh Token

For this stage it is best to follow the steps mentioned in Microsoft’s documentation: https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow.

Below is a copy of Microsoft's instructions.

1. Requesting an Authorization Code

This step must be done using the account that is tied to the SMTP OAuth configuration.

a. Copy the URL below and paste it into the browser.

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id={client id}&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.send&state=12345

b. Add in the correct values from the previous step (6) for “tenant” and “client_id” (highlighted below) into the URL that you just pasted into the browser.

tenant = Directory (tenant) ID. Valid tenant values are common, organizations, consumers, and tenant identifiers.

client_id = Application (client) ID. An example of a client_id is: 6731de76-14a6-49ae-97bc-6eba6914391e.

When navigated to in the browser the user will be prompted to login. Upon successful completion of this step the user will be redirected and the new url will look similar to the image below.

c. Copy the “code” value from this url to use in the next step (2b).

2. Request an Access Token with a Client Secret

You will need to use Postman or a similar tool for these steps. The client_id, scope, code, redirect_url, grant_type, and client_secret values will need to be added to the Body of the request.

a. In Postman, setup a new request as follows:

POST /{tenant}/oauth2/v2.0/token HTTP/1.1

Host: https://login.microsoftonline.com

Content-Type: application/x-www-form-urlencoded


&scope= user.read offiline_access





client_secret is only required for web apps. This secret needs to be URL-Encoded.

b. Update the tenant, client_id, redirect_uri, and client_secret values with what you have setup in Azure. The “code” will be the value returned in the previous step (1c).

c. Copy the refresh_token from the successful request. We’ll be using it to finish our setup in the next step (2l).

"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",

"token_type": "Bearer",

"expires_in": 3599,

"scope": "user.read offiline_access",

"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."

"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",

Setting up the SMTP OAuth Connection in Onit

Now that we have all of our information we can do the setup in Onit.

2. Fill Out the Values as Follows:

  1. Name: Custom
  2. Display Name: Custom
  3. Address: smtp.office365.com
  4. Port: 587
  5. Domain: the domain of the exchange setup. For example, Onit’s email domain is “onit”
  6. User Name (email): the email of the account that was used for the setup in the previous steps
  7. Tenant: Organizations
  8. Application (client) ID: Value from the Azure app
  9. Client Secret: Value from the Azure app
  10. Scope: https://graph.microsoft.com/SMTP.Send
  11. Redirect URI: Value from the Azure app
  12. Refresh Token: The refresh token value from the Postman response

3. Ensure that the “Enabled” Checkbox is Checked and then Save

That’s all! Now you can test to see if emails are going out properly. Please note that the sent emails page cannot track successful delivery of emails when an SMTP provider is configured.

Previous Article Onit Outlook Add-In Centralized Deployment
Next Article ONIT Outlook Add-In 2.1 End User Guide

© 2024 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.