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 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 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 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 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 https //learn microsoft com/en us/office/office 365 management api/get started with office 365 management apis link to https //learn microsoft com/en us/previous versions/office/developer/o365 enterprise developers/jj984335(v=office 15) https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#start a subscription https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#stop a subscription https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#list current subscriptions https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#list available content https //learn microsoft com/en us/office/office 365 management api/office 365 management activity api reference#retrieve content 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 {"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 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 {"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 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 {"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 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 {"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 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