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 https //portal azure com/#blade/microsoft aad registeredapps/applicationslistblade 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 https //portal azure com/#view/microsoft aad iam/activedirectorymenublade/ /overview 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 https //learn microsoft com/en us/azure/active directory/develop/v2 oauth2 client creds grant flow 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 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/ 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 contenttype string required indicates the content type must be a valid content type 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 starttime string optional optional datetimes (utc) indicating the time range of content to return, based on when the content became available endtime string optional optional datetimes (utc) indicating the time range of content to return, based on when the content became available output parameter type description status code number http status code of the response reason string response reason phrase 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" "1", "x content type options" "nosniff", "dataserviceversion" "2", "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" \[ {} ] } ] 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 publisheridentifier string required tenant guid of the vendor 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 status string status value address string output field address authid string unique identifier expiration object output field expiration 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" "1", "x content type options" "nosniff", "dataserviceversion" 2, "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" { "contenttype" "audit sharepoint", "status" "enabled", "webhook" {} } } ] 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 $format string optional parameter for message trace report $orderby string optional parameter for message trace report $select string optional parameter for message trace report $filter string optional parameter for message trace report output parameter type description status code number http status code of the response reason string response reason phrase d object output field d results array result of the operation metadata object response data id string unique identifier uri string output field uri type string type of the resource organization string output field organization messageid string unique identifier received string output field received senderaddress string output field senderaddress recipientaddress string output field recipientaddress subject string output field subject status string status value toip object output field toip fromip string output field fromip size number output field size messagetraceid string unique identifier startdate string date value enddate string date value index number output field index 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" "1", "x content type options" "nosniff", "dataserviceversion" "2 0;", "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" { "d" {} } } ] 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 organizationid string required the organization id contentid string required an opaque string that uniquely identifies the content output parameter type description status code number http status code of the response reason string response reason phrase 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" "1", "x content type options" "nosniff", "dataserviceversion" "2", "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" \[ {}, {}, {} ] } ] 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 contenttype string required must be a valid content type publisheridentifier string required tenant guid of the vendor coding webhook object optional webhook properties for notifications address string optional https endpoint for receiving notifications 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 expiration string optional datetime after which notifications stop 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 status string status value address string output field address authid string unique identifier expiration object output field expiration 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" "1", "x content type options" "nosniff", "dataserviceversion" 2, "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" { "contenttype" "audit sharepoint", "status" "enabled", "webhook" {} } } ] 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 publisheridentifier string required tenant guid of the vendor coding contenttype string required must be a valid content type output parameter type description status code number http status code of the response reason string response reason phrase 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" "1", "x content type options" "nosniff", "dataserviceversion" 2, "x aspnet version" "4 0 30319" }, "reason" "ok", "json body" {} } ] 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 0; 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 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 https //learn microsoft com/en us/office/office 365 management api/get started with office 365 management apis link to message trace report api https //learn microsoft com/en us/previous versions/office/developer/o365 enterprise developers/jj984335(v=office 15)start subscription https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#start a subscriptionstop subscription https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#stop a subscriptionlist subscriptions https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#list current subscriptionslist available content https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#list available contentretrieve content https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#retrieve content