Example: OAuth Configuration for Microsoft Outlook

This guide explains how to:

Integrate an Algo device with Microsoft Outlook using OAuth
Verify the configuration by sending a test Outlook email
Use the OAuth profile to send a test Outlook email from an Algo 8450

Note
This document includes third-party configuration procedures that are subject to change. It is provided for reference purposes only, and Algo cannot guarantee that the screenshots or procedures will always be current or up to date.

Before you start

Ensure you have an Outlook account.

Procedure Overview

This procedure includes the following steps:

Creating a Microsoft Entra Application

Create a Microsoft Entra application and obtain the required credentials for OAuth.

Sign in to the Microsoft Entra admin center.
Go to App registrations and select + New registration.
Configure the application details:
- Name: Enter a name for your application. For example, Algo Device Notifier.
- Supported account types: Choose the option that fits your deployment.
- Enter the redirect URI: Select Single-page application (SPA) and enter your Algo device’s callback URL using this format: https://<ALGO_DEVICE_IP>/control/oauth-callback.lua.
  Note
  - The redirect URI must use HTTPS.
  - The redirect URI must match exactly in both Microsoft Entra and the device’s configuration.

Select Register.
After registration, copy these values from the application’s Overview page:
- Application (client) ID
- Directory (tenant) ID
  You need this information to configure OAuth later.
Select Certificates & secrets → + New client secret.
Enter the client secret details, then select Add.
- Description: Enter a description.
- Expires: Select an expiration option.
Copy the secret Value and save it securely. You will need it when creating the OAuth authorization profile later.
Go to API permissions → Add a permission.
Select Microsoft Graph.
Select Delegated permissions.
Type to search the following permissions, then select Add Permissions.
- mail.send
- offline_access

Creating OAuth Authorization Profile

Create an OAuth profile to store your Outlook authentication settings.

Ensure you have the following:

Directory (tenant) ID
Application (client) ID
Client Secret

To create an Outlook OAuth Profile:

Log in to your device’s web interface using HTTPS.
HTTPS is required by the Outlook OAuth process.
Go to the Advanced Settings → OAuth.
Set a Name for your OAuth profile.
Select MICROSOFT_OUTLOOK as the Provider Type.
Accept the following automatically populated values:
- Grant Type: AUTH_CODE_PKCE
- Client Auth Mode: NONE
- Scope Mode: SCOPES_LIST
- Scope: offline_access Mail.Send
- PKCE Method: S256
- Response Type: code
Configure the following:
- Client ID: Enter your Application (client) ID.
- Client Secret: Enter your Client Secret
Leave the following fields blank. These values are automatically populated during authorization.
- PKCE Authorization Code
- PKCE Code Verifier
- PKCE Refresh Token
  Note
  Refresh tokens can expire or become invalid for several reasons, such as revoked app access, password changes, unused tokens, or admin policy restrictions. Refer to the OAuth provider’s documentation for more information. If a refresh token expires or becomes invalid, your automation stops working until OAuth access is reauthorized.

Set Extra Params (JSON) as below:

Replace the <YOUR_ACTUAL_TENANT_ID> with your Directory (tenant) ID.

{
  "tenant": "<YOUR_ACTUAL_TENANT_ID>",
  "prompt": "select_account",
  "resource_hint": "graph",
  "jwks_uri": "https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys"
}

Select START AUTHORIZATION.
Select your Outlook account.
Select Create Profile.
Your profile appears under the OAuth Profiles list.

Sending a Test Email

You can create a test email to verify that the configuration is working correctly.

To send a test email:

Log in to your device’s web interface using HTTPS.
HTTPS is required by the Outlook OAuth process.
Go to the Advanced Settings → OAuth.
Select your Outlook profile from the Test OAuth Profile dropdown list.
Select MICROSOFT_OUTLOOK as the Provider Type Template.

Edit the Data Payload.

Replace user@example.com with your email address.

{
  "message": {
    "subject": "OAuth test",
    "body": {
      "contentType": "Text",
      "content": "HELLO!"
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "user@example.com"
        }
      }
    ]
  },
  "saveToSentItems": "false"
}

Select RUN OAuth Test.
Upon success:
- The email appears in your Outlook inbox.
  
  A successful response is displayed.

Configuring an 8450 Button to Send an Email

You can configure a button on the Algo 8450 to send an Outlook email.

To configure a 8450 button to send an Outlook email:

Create a button on a 8450 screen.
Set the Button Status to Enabled.
Configure the following:
- Text: Enter the button display text.
- Action: Set to Send API Request.
- Number of API Requests: Set to 1.
- Request 1 - Command: Set to Other.
- Request 1 - Method: Set to POST.
- Request 1 - Custom Path: Set to v1.0/me/sendMail.
- Request 1 - Targets: Set to graph.microsoft.com.
- Request 1 - OAuth Profile: Select your Outlook profile.
- Request 1 - Headers: Set to Custom Headers.
- Request 1 - Custom Headers: Set to Content-Type: application/json; charset=utf-8.
- Request 1 - Data Payload: You can use the default payload.
  Replace the user@example.com with your email address.
```
{
  "message": {
    "subject": "OAuth test",
    "body": {
      "contentType": "Text",
      "content": "HELLO!"
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "user@example.com"
        }
      }
    ]
  },
  "saveToSentItems": "false"
}
```
Select Save.
Press the button and verify that the email is received in your Outlook inbox.

Troubleshooting

I get a 502 error when I run the OAuth Test

You may be logged out of your Algo device’s web interface. Log in again and retry.

After I run the “Start Authorization” again, my OAuth Test fails

Each time you run Start Authorization again, select Update Profile to save the new credentials before running the test.

My OAuth profile stops working.

An OAuth profile can stop working if the OAuth provider rejects or invalidates the access or refresh token. Refer to the OAuth provider’s documentation for more information. If this occurs, the OAuth profile must be reauthorized.

Documentation Index