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
- Click “+ Add a permission” and add the following:
- Microsoft Graph > Delegated Permissions > SMTP.Send (https://graph.microsoft.com/SMTP.Send)
- Microsoft Graph > Delegated Permissions > offline_access
- 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:
- Directory (tenant) ID
- Client Secret value
- Application (client) ID
- 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
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope= user.read offiline_access
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh
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.
1. Navigate to Auth Providers and Create a New SMTP OAuth Provider
2. Fill Out the Values as Follows:
- Name: Custom
- Display Name: Custom
- Address: smtp.office365.com
- Port: 587
- Domain: the domain of the exchange setup. For example, Onit’s email domain is “onit”
- User Name (email): the email of the account that was used for the setup in the previous steps
- Tenant: Organizations
- Application (client) ID: Value from the Azure app
- Client Secret: Value from the Azure app
- Scope: https://graph.microsoft.com/SMTP.Send
- Redirect URI: Value from the Azure app
- 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.