Microsoft office 365

The Microsoft Office 365 connector facilitates automation of email tracing, subscription management, and content retrieval within the Office 365 platform.

Microsoft Office 365 is a comprehensive suite of productivity tools that includes email, document management, and collaboration services. The Microsoft Office 365 Turbine Connector allows users to automate security and compliance workflows by integrating with Office 365 services. Users can retrieve content, manage subscriptions, and generate reports to gain insights into their Office 365 environment. This integration empowers Swimlane Turbine users to enhance their security posture, streamline incident response, and maintain compliance with ease.

Prerequisites

To effectively utilize the Microsoft Office 365 connector for Swimlane Turbine, ensure you have the following prerequisites:

OAuth2 Refresh Token authentication with the following parameters:

URL: Endpoint URL for Office 365 services

Client ID: Unique identifier for the registered application

Client Secret: Confidential secret associated with the Client ID

Refresh Token: Token used to obtain new access tokens

OAuth2 Client Credentials authentication with the following parameters:

URL: Endpoint URL for Office 365 services

Client ID: Unique identifier for the registered application

Client Secret: Confidential secret associated with the Client ID

Token URL: URL to retrieve the OAuth2 token

Scopes: Permissions the application requires

Asset Setup

Client Credential Flow Authentication

Authentication uses Azure application OAuth2. You will need an admin account in Azure to create the application.

Recommended Application Permissions (feel free use custom permissions if you only use certain actions):

ReportingWebService.Read

In order to set up the asset, you need the following:

Azure Application Client ID

Azure Application Client Secret

Azure Tenant ID

Steps to create the Azure app:

Go to the App Registration page in the Azure portal.

Click New Registration.

Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.

Navigate to the API permissions tab on the left navigation menu.

Select Add a permission.

Select APIs my organization uses.

Search Office 365 Exchange Online, then mark all the permissions you need for the actions you are using (See suggested permissions at the top of the asset setup section).

Click the Add permissions button at the bottom of the page.

Select Grant admin consent for your organization, then your permissions should look as below.

Navigate to the Certificates & secrets tab and select New client secret.

Fill out the description and expiration, then click the Add button at the bottom.

The Value of the secret you just created is the Client Secret needed for the Swimlane asset.

Navigate to the Overview tab on the left menu.

The Client ID and Tenant ID needed in the asset are shown on this page.

Assign Roles to the Application

Global Reader and Security Reader are required for the application to get Trace Report

Steps to assign roles to the Azure app:

Go the Azure Active Directory Page.

Click on Roles and Administrators tab on the left side of Azure Active Directory Page.

Search for Global Reader in the filter search bar and select the Global Reader role by clicking on its text. Make sure not to click the checkbox next to it and click only on the role's name with the checkbox unmarked.

Click on the Add Assignments tab for the Global Reader.

Opens the Add Assignments page click on the text below Select member(s) and search for your application. Select it and click Add then click on the Next button on the bottom left after that it will go to Setting tab.

Select Active for Assignment type and enter the description explaining why this role should be added.

Click on Roles and administrators | All roles at the top of the page to view the complete list of roles.

Modify your filter selection to Security Reader and click on the text representing Security Reader. Ensure you do not select the checkbox next to Security Reader instead, click directly on the text with the checkbox unselected.

Similarly follow the steps from 4 to 6.

Authentication

The connector can be authenticated in one of two ways:

Oauth 2.0 client credentials flow, which requires a Client ID, Client Secret and Token URL. For more information, click here

Oauth 2.0 refresh token grant, which requires a 'Refresh Token', 'Client ID' and 'Client Secret'. Use this auth with accounts which have MFA enabled. To generate a refresh token please follow the instructions below.

In step 3 of the above-mentioned setup instructions, please provide a 'Redirect URI' and select the platform as 'Web', before clicking on 'Register' at the the bottom.

Proceed with the remaining steps to generate 'Client ID' and 'Client Secret'.

The Swimlane team will provide a Python script and instructions on how to use the script to generate the Refresh Token.

Capabilities

This Connector provides the following capabilities:

List Available Content

List Current Subscriptions

Message Trace Report

Retrieve Content

Start Subscription

Stop Subscription

Notes

For the Refresh Token Auth, The generated refresh token will have 90 days as the default expiry value unless it is reduced by your organization. You need to update the asset after the refresh token expires.

For more information on Microsoft Office 365 is found at: Microsoft Office 365 Documentation

Link to Message Trace Report API

Start Subscription

Stop Subscription

List subscriptions

List Available Content

Retrieve Content

Additional Documentation

Microsoft office 365 Connector Documentation

Microsoft office 365 API Documentation

Microsoft office 365 Authentication Guide

Configurations

MS Office 365 Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token_url	Must start with https://login.microsoftonline.com/ and then continue with the tenant_id, and then be prepended with /oauth2/v2.0/token	string	Required
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

MS Office 365 Refresh Token Grant

Authenticates using refresh token. Use this authentication for accounts with MFA enabled.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
cl_id	The client ID.	string	Required
cl_secret	The client secret.	string	Required
refresh_token	Refresh Token.	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

List Available Content

Retrieves a list of currently available content for a specified type from Microsoft Office 365, requiring ContentType and PublisherIdentifier.

Endpoint

URL: /subscriptions/content

Method: GET

Input

Argument Name	Type	Required	Description
parameters.ContentType	string	Required	Indicates the content type. Must be a valid content type.
parameters.PublisherIdentifier	string	Required	The tenant GUID of the vendor coding against the API. This is not the application GUID or the GUID of the customer using the application, but the GUID of the company writing the code.
parameters.startTime	string	Optional	Optional datetimes (UTC) indicating the time range of content to return, based on when the content became available.
parameters.endTime	string	Optional	Optional datetimes (UTC) indicating the time range of content to return, based on when the content became available.

Input Example

{"parameters":{"ContentType":"Audit.SharePoint","PublisherIdentifier":"46b472a7-c68e-4adf-8ade-3db49497518e","startTime":"2015-05-23","endTime":"2015-05-30"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

{"status_code":200,"response_headers":{"Cache-Control":"no-cache, no-store","Content-Length":"788","Content-Type":"application/json;odata=verbose;charset=utf-8","Server":"Microsoft-IIS/10.0","request-id":"2cf9be82-5112-b143-24d7-fe3e1df355d7","X-CalculatedBETarget":"DM4PR14MB4896.namprd14.PROD.OUTLOOK.COM","X-BackEndHttpStatus":"200","X-RUM-Validated":"1","X-RUM-NotUpdateQueriedPath":"1","X-RUM-NotUpdateQueriedDbCopy":"1","x-ms-appId":"95d971d3-07b0-4eda-9e7e-c72ffae8ede2","Restrict-Access-Confi...

List Current Subscriptions

Retrieve current Microsoft Office 365 subscriptions and associated webhooks using a specific PublisherIdentifier.

Endpoint

URL: /subscriptions/list

Method: GET

Input

Argument Name	Type	Required	Description
parameters.PublisherIdentifier	string	Required	Tenant GUID of the Vendor.

Input Example

{"parameters":{"PublisherIdentifier":"46b472a7-c68e-4adf-8ade-3db49497518e"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
contentType	string	Type of the resource
status	string	Status value
webhook	object	Output field: webhook
webhook.status	string	Status value
webhook.address	string	Output field: webhook.address
webhook.authId	string	Unique identifier
webhook.expiration	object	Output field: webhook.expiration

Output Example

{"status_code":200,"response_headers":{"Cache-Control":"no-cache, no-store","Content-Length":788,"Content-Type":"application/json;odata=verbose;charset=utf-8","Server":"Microsoft-IIS/10.0","request-id":"2cf9be82-5112-b143-24d7-fe3e1df355d7","X-CalculatedBETarget":"DM4PR14MB4896.namprd14.PROD.OUTLOOK.COM","X-BackEndHttpStatus":"200","X-RUM-Validated":"1","X-RUM-NotUpdateQueriedPath":"1","X-RUM-NotUpdateQueriedDbCopy":"1","x-ms-appId":"95d971d3-07b0-4eda-9e7e-c72ffae8ede2","Restrict-Access-Confirm...

Message Trace Report

Generates a summary report on email message processing to provide insights within the Microsoft Office 365 system.

Endpoint

URL: /ecp/reportingwebservice/reporting.svc/MessageTrace

Method: GET

Input

Argument Name	Type	Required	Description
parameters.$format	string	Optional	Parameters for the Message Trace Report action
parameters.$orderby	string	Optional	Parameters for the Message Trace Report action
parameters.$select	string	Optional	Parameters for the Message Trace Report action
parameters.$filter	string	Optional	Parameters for the Message Trace Report action

Input Example

{"parameters":{"$format":"json","$orderby":"Received desc","$select":"MessageId","$filter":"MessageTraceId eq (guid'98b131b3-267a-4366-c6e8-08dcb5d09c09')"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
d	object	Output field: d
d.results	array	Result of the operation
d.results.__metadata	object	Response data
d.results.__metadata.id	string	Response data
d.results.__metadata.uri	string	Response data
d.results.__metadata.type	string	Response data
d.results.Organization	string	Result of the operation
d.results.MessageId	string	Unique identifier
d.results.Received	string	Result of the operation
d.results.SenderAddress	string	Result of the operation
d.results.RecipientAddress	string	Result of the operation
d.results.Subject	string	Result of the operation
d.results.Status	string	Status value
d.results.ToIP	object	Result of the operation
d.results.FromIP	string	Result of the operation
d.results.Size	number	Result of the operation
d.results.MessageTraceId	string	Unique identifier
d.results.StartDate	string	Result of the operation
d.results.EndDate	string	Result of the operation
d.results.Index	number	Result of the operation

Output Example

Retrieve Content

Retrieve a content blob from Microsoft Office 365 using specified organization and content IDs, returning data in JSON format.

Endpoint

URL: api/v1.0/{{organizationId}}/activity/feed/audit/{{contentId}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.organizationId	string	Required	The Organization ID.
path_parameters.contentId	string	Required	An opaque string that uniquely identifies the content.

Input Example

{"path_parameters":{"organizationId":"41463f53-8812-40f4-890f-865bf6e35190","contentId":"492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

Start Subscription

Initiates a subscription to a specified content type in Microsoft Office 365, requiring contentType and PublisherIdentifier.

Endpoint

URL: /subscriptions/start

Method: POST

Input

Argument Name	Type	Required	Description
parameters.contentType	string	Required	Must be a valid Content Type.
parameters.PublisherIdentifier	string	Required	Tenant GUID of the Vendor Coding.
webhook	object	Optional	Webhook Properties for Notifications.
webhook.address	string	Optional	HTTPS Endpoint for receiving Notifications.
webhook.authId	string	Optional	string that will be included as the WebHook-AuthID header in notifications sent to the webhook as a means of identifying and authorizing the source of the request to the webhook.
webhook.expiration	string	Optional	Datetime after which Notifications stop.

Input Example

{"parameters":{"contentType":"Audit.SharePoint","PublisherIdentifier":"46b472a7-c68e-4adf-8ade-3db49497518e"},"json_body":{"webhook":{"address":"https://webhook.myapp.com/o365/","authId":"o365activityapinotification","expiration":""}}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
contentType	string	Type of the resource
status	string	Status value
webhook	object	Output field: webhook
webhook.status	string	Status value
webhook.address	string	Output field: webhook.address
webhook.authId	string	Unique identifier
webhook.expiration	object	Output field: webhook.expiration

Output Example

Stop Subscription

Terminates an active subscription for a specified content type in Microsoft Office 365, requiring PublisherIdentifier and contentType.

Endpoint

URL: /subscriptions/stop

Method: POST

Input

Argument Name	Type	Required	Description
parameters.PublisherIdentifier	string	Required	Tenant GUID of the Vendor Coding.
parameters.contentType	string	Required	Must be a valid Content Type.

Input Example

{"parameters":{"PublisherIdentifier":"46b472a7-c68e-4adf-8ade-3db49497518e","contentType":"Audit.SharePoint"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase

Output Example

Response Headers

Header	Description	Example
Alt-Svc	HTTP response header: Alt-Svc	h3=:443;ma=2592000,h3-29=:443;ma=2592000
Cache-Control	Directives for caching mechanisms	no-cache, no-store
Content-Length	The length of the response body in bytes	788
Content-Type	The media type of the resource	application/json;odata=verbose;charset=utf-8
DataServiceVersion	HTTP response header: DataServiceVersion	2
Date	The date and time at which the message was originated	Tue, 06 Aug 2024 10:35:53 GMT
request-id	HTTP response header: request-id	2cf9be82-5112-b143-24d7-fe3e1df355d7
Restrict-Access-Confirm	HTTP response header: Restrict-Access-Confirm	1
Server	Information about the software used by the origin server	Microsoft-IIS/10.0
X-AspNet-Version	HTTP response header: X-AspNet-Version	4.0.30319
X-BackEndHttpStatus	HTTP response header: X-BackEndHttpStatus	200
X-BEServer	HTTP response header: X-BEServer	DM4PR14MB4896
X-CalculatedBETarget	HTTP response header: X-CalculatedBETarget	DM4PR14MB4896.namprd14.PROD.OUTLOOK.COM
X-Content-Type-Options	HTTP response header: X-Content-Type-Options	nosniff
X-DiagInfo	HTTP response header: X-DiagInfo	DM4PR14MB4896
X-FEEFZInfo	HTTP response header: X-FEEFZInfo	MAA
X-FEProxyInfo	HTTP response header: X-FEProxyInfo	MA1PR01CA0171.INDPRD01.PROD.OUTLOOK.COM
X-FEServer	HTTP response header: X-FEServer	MA1PR01CA0171
X-FirstHopCafeEFZ	HTTP response header: X-FirstHopCafeEFZ	MAA
x-ms-appId	HTTP response header: x-ms-appId	95d971d3-07b0-4eda-9e7e-c72ffae8ede2
X-Powered-By	HTTP response header: X-Powered-By	ASP.NET
X-Proxy-BackendServerStatus	HTTP response header: X-Proxy-BackendServerStatus	200
X-Proxy-RoutingCorrectness	HTTP response header: X-Proxy-RoutingCorrectness	1
X-RUM-NotUpdateQueriedDbCopy	HTTP response header: X-RUM-NotUpdateQueriedDbCopy	1
X-RUM-NotUpdateQueriedPath	HTTP response header: X-RUM-NotUpdateQueriedPath	1
X-RUM-Validated	HTTP response header: X-RUM-Validated	1
X-RWS-Version	HTTP response header: X-RWS-Version	2013-V1
X-UA-Compatible	HTTP response header: X-UA-Compatible	IE=10