Microsoft 365

Introduction

This guide explains how to authenticate the Microsoft Graph API connector in Swimlane using one of the following authentication methods:

OAuth 2.0 Client Credentials (Application permissions)

OAuth 2.0 Refresh Token Grant (Delegated permissions with MFA)

You will create an Azure app, assign permissions, collect the required identifiers, and configure the connector inside Swimlane.

Prerequisites

Azure Access Requirements

You must have Azure permissions to:

Assign API permissions

Grant admin consent

Create and manage client secrets

Assign directory roles (Global Reader, Security Reader)

View tenant, subscription, and organizational properties

Required Credentials

During setup, you will collect:

Client ID

Client Secret

Tenant ID

Token URL (for Client Credentials flow)

Refresh Token (for Refresh Token flow)

Scopes (API permissions required for Office 365)

Host URL (Office 365 service endpoint)

Authentication Methods Overview

OAuth 2.0 Client Credentials

Used for non-MFA accounts and for most server-to-server automations.

You will need:

Client ID

Client Secret

Tenant ID

Token URL (must include Tenant ID)

Scope(s)

OAuth 2.0 Refresh Token Grant

Use this when:

The Office 365 account has MFA enabled

You need a long-lived token flow based on user authentication

You will need:

Client ID

Client Secret

Refresh Token

Redirect URI (added during Azure App Registration)

Azure Setup

Take the following steps to register the application:

Go to Azure Portal > Azure Active Directory > App Registrations

Click New Registration.

Enter an application name.

Select Accounts in this organizational directory only.

(Refresh Token method only) Add a Redirect URI (Platform: Web).

Click Register.

Take the following steps to assign the API permissions:

Open the API Permissions tab.

Click Add a permission.

Select APIs my organization uses.

Search and select Office 365 Exchange Online.

Add the required permissions (recommended):

ReportingWebService.Read

(Any additional permissions needed for your actions)

Click Add permissions.

Click Grant admin consent for your organization.

Take the following steps to generate a client secret

Go to Certificates & secrets.

Click New client secret.

Add description and expiration.

Click Add.

Copy and save the value. This saved value is Client Secret.

Take the following steps to collect required Identifiers:

From App Registration > Overview, copy:

Client ID

Tenant ID

From the Office Azure tenant workspace, copy:

Organization/Tenant ID

Subscription ID (if applicable to your environment)

Any required Office 365 identifiers used in your actions

Additional Step (Required for Trace Reports)

Assign Required Directory Roles

Office 365 Message Trace APIs require:

Global Reader

Security Reader

Steps:

Go to Azure Active Directory.

Open Roles and administrators.

Search Global Reader.

Click the role name (not the checkbox).

Click Add assignments.

Search for your app > Select > Add.

Set Assignment type = Active.

Repeat for Security Reader.

Method 1: Authenticate Using OAuth 2.0 Client Credentials

Token URL Format

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token

Host URL

(Your Office 365 endpoint - usually service-specific)

Method 2: Authenticate Using OAuth 2.0 Refresh Token Grant

Use this for MFA-enabled accounts

Additional Requirements

Redirect URI must be provided during registration.

A Refresh Token must be generated using the Swimlane-provided script.

How the Refresh Token Is Generated?

Swimlane will provide:

A Python script

Instructions to log in using your Azure user

The script returns:

refresh_token

access_token (not used in Turbine)

Refresh Tokens expire every 90 days (or sooner if your organization enforces a shorter policy). You must update the asset before expiry.

Connector Configuration in Swimlane

Log into Turbine.

From the left-hand navigation pane, click ORCHESTRATION and click Assets. Asset homepage opens.

Click the + icon to create a new asset.

Select Microsoft Office 365 from the Asset Type list.

Fill in the Asset Settings and Asset Input as shown: a) Configuration - OAuth 2.0 Client Credentials

Field	Description	Required/Optional
url	Office 365 Host URL	Required
token_url	Token URL including tenant_id	Required
client_id	Client ID from Azure	Required
client_secret	Client secret from Azure	Required
scope	API scope added in the permission step	Required
verify_ssl	SSL verification	Optional
http_proxy	Proxy to route requests	Optional

Fields with * marks are required.

b) Configuration - OAuth 2.0 Refresh Token Grant

Field	Description	Required/Optional
url	Office 365 Host URL	Required
cl_id	Client ID	Required
cl_secret	Client Secret	Required
refresh_token	Refresh token generated via script	Required
verify_ssl	SSL verification	Optional
http_proxy	Proxy to route requests	Optional

Fields with * marks are required.

6. Click Create.

Troubleshooting

If you encounter a 403 Forbidden error:

Ensure Global Reader and Security Reader roles are correctly assigned.

Confirm admin consent is granted.

Verify API permissions match connector actions.

If you encounter 401 Unauthorized error:

Incorrect Client Secret, create a new one.

Missing scopes, re-add required permissions.

Token expired, regenerate Refresh Token.

You have successfully authenticated the Microsoft Office 365 connector in Swimlane using either Client Credentials or Refresh Token authentication.