Microsoft Graph API Users and Presence

this connector facilitates the management of user accounts and presence information through the microsoft graph api, enabling automated user profile updates and status checks microsoft graph api is a unified endpoint for accessing data, relationships, and insights across microsoft 365 services the microsoft graph api users and presence connector for swimlane turbine allows users to manage microsoft user accounts and their presence information efficiently by integrating with microsoft graph api, swimlane turbine users can automate user management tasks such as retrieving user details, presence status, group memberships, and updating user properties this integration enhances security operations by providing real time data on user status and streamlining user account management directly within the swimlane platform configuration prerequisites to utilize the microsoft graph api users and presence connector, ensure you have the following prerequisites client credentials and tenant id authentication with these parameters url endpoint for microsoft graph api client id application id registered in azure ad client secret password or key associated with the application tenant id directory id of the azure ad tenant scope permissions the app requires oauth 2 0 client credentials with these parameters url endpoint for microsoft graph api client id application id registered in azure ad client secret password or key associated with the application token url url to retrieve the oauth2 token scope permissions the app requires delegated flow authentication with these parameters url endpoint for microsoft graph api tenant id directory id of the azure ad tenant and so on authentication methods oauth 2 0 client credentials authentication with these parameters url endpoint for microsoft graph api client id application (client) id registered in azure ad client secret client secret (key) generated for the application in azure ad token url url to retrieve the oauth token scope permissions the app requires password grant (delegated authentication) for acting on behalf of a user url endpoint for microsoft graph api tenant id directory id of the azure ad tenant oauth un user's username to authenticate oauth pwd user's password to authenticate oauth cl id application (client) id registered in azure ad oauth cl secret client secret (key) generated for the application in azure ad login url login url default value is https //login microsoftonline com (optional) scope permissions the app requires optional field (optional) asset credentials specific to your organization (microsoft graph api asset tenant id) url endpoint for microsoft graph api client id application (client) id registered in azure ad client secret client secret (key) generated for the application in azure ad tenant id directory id of the azure ad tenant scope permissions the app requires authentication for oauth2 refresh token grant credentials for microsoft graph api authentication url endpoint for microsoft graph api client id application (client) id registered in azure ad client secret client secret (key) generated for the application in azure ad refresh token refresh token scope permissions the app requires capabilities the microsoft graph api connector gives the ability to get and update security alerts, and modify user licenses and sessions get presence get user by id list a users direct membership update user 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) user readwrite all directory readwrite all user read all directory read all presence readwrite all user enabledisableaccount all user manageidentities all sites readwrite all is needed by sharepoint actions only 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 microsoft graph select application permissions , 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 the client id , tenant id , and client secret described in the steps above are the credentials you need for the asset password flow (delegated auth) use delegated permissions, instead of application permissions, and generate client id , tenant id , and client secret as described in the above client credential flow authentication we also need an username and a password for this authentication authentication flow for oauth2 refresh token oauth 2 0 refresh token grant, which requires a refresh token , tenant id , 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', tenant id and client secret add the permissions in delegated permissions the swimlane team will provide a python script and instructions on how to use the script to generate the refresh token limit access to specific mailboxes administrators who want to limit app access to specific mailboxes can create an application access policy by using the new applicationaccesspolicy powershell cmdlet for more information please see the article https //docs microsoft com/en us/graph/auth limit mailbox access action setup odata filters information on the filter input formatting can be found https //docs microsoft com/en us/graph/query parameters#filter parameter keep in mind that not specifying a folder as an input will result in the query affecting all possible folders example if we want to ingest only unread emails, and we don't set the input "folder", we will ingest all unread emails from all folders, including "deleted items", "junk", etc well known folders well known folders can be used instead of folder ids for email actions all well known folder names can be found https //docs microsoft com/en us/graph/api/resources/mailfolder?view=graph rest 1 0 sites get site all the sites actions require the site id to be executed the site id can be obtained using the action sites get site, in order to run the action the site hostname and site name are needed this two values can be found in a site url https //{site hostname} sharepoint com/sites/{site name} for example if our site url is https //swimlaneintegrations sharepoint com/sites/integrationssite we should use site hostname swimlaneintegrations site name integrationssite after the action execution you can find the site id on the id output field sites create list in order to create a list with its columns, use the input columns you can find all the possible values with its configuration on the following table property name type description boolean https //docs microsoft com/en us/graph/api/resources/booleancolumn?view=graph rest 1 0 this column stores boolean values calculated https //docs microsoft com/en us/graph/api/resources/calculatedcolumn?view=graph rest 1 0 this column's data is calculated based on other columns choice https //docs microsoft com/en us/graph/api/resources/choicecolumn?view=graph rest 1 0 this column stores data from a list of choices currency https //docs microsoft com/en us/graph/api/resources/currencycolumn?view=graph rest 1 0 this column stores currency values datetime https //docs microsoft com/en us/graph/api/resources/datetimecolumn?view=graph rest 1 0 this column stores datetime values geolocation https //docs microsoft com/en us/graph/api/resources/geolocationcolumn?view=graph rest 1 0 this column stores a geolocation lookup https //docs microsoft com/en us/graph/api/resources/lookupcolumn?view=graph rest 1 0 this column's data is looked up from another source in the site number https //docs microsoft com/en us/graph/api/resources/numbercolumn?view=graph rest 1 0 this column stores number values personorgroup https //docs microsoft com/en us/graph/api/resources/personorgroupcolumn?view=graph rest 1 0 this column stores person or group values text https //docs microsoft com/en us/graph/api/resources/textcolumn?view=graph rest 1 0 this column stores text values validation https //docs microsoft com/en us/graph/api/resources/columnvalidation?view=graph rest 1 0 this column stores validation formula and message for the column hyperlinkorpicture https //docs microsoft com/en us/graph/api/resources/hyperlinkorpicturecolumn?view=graph rest 1 0 this column stores hyperlink or picture values term https //docs microsoft com/en us/graph/api/resources/termcolumn?view=graph rest 1 0 this column stores taxonomy terms thumbnail https //docs microsoft com/en us/graph/api/resources/thumbnailcolumn?view=graph rest 1 0 this column stores thumbnail values contentapprovalstatus https //docs microsoft com/en us/graph/api/resources/contentapprovalstatuscolumn?view=graph rest 1 0 this column stores content approval status for a complete version of this table please see https //docs microsoft com/en us/graph/api/resources/columndefinition?view=graph rest 1 0#properties create list column refer to the above table to get the type properties and column type input the type properties are documented within the links in the type column get list items in order to use the filter input please refer to the docid\ vgjkgbbns3fx1swd5rpr0 section the column used to filter the output must be indexed, see the https //support microsoft com/en us/office/add an index to a list or library column f3f00554 b7dc 44d1 a2ed d477eac463b0?ui=en us\&rs=en us\&ad=us to add an index to a list limitations when using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways properties that appear in $orderby must also appear in $filter properties that appear in $orderby are in the same order as in $filter properties that are present in $orderby appear in $filter before any properties that aren't failing to do this results in the following error error code inefficientfilter error message the restriction or sort order is too complex for this operation the assign/remove user license requires either the disabled plans and accompanying sku ids to assign licenses or the sku id of the license you want to remove the get security alert has additional information it can return there are a large number of fields that don't relate to many alerts, so they are not mapped; you can add them if desired notes https //social technet microsoft com/wiki/contents/articles/33525 an introduction to microsoft graph api aspx https //docs microsoft com/en us/graph/api/overview?view=graph rest 1 0 https //docs microsoft com/en us/graph/query parameters https //docs microsoft com/en us/graph/api/resources/security api overview?view=graph rest beta https //docs microsoft com/en us/azure/active directory/develop/v1 protocols oauth code https //requests oauthlib readthedocs io/en/latest/oauth2 workflow\ html#legacy application flow , this is sort of a hack to bypass manual login (typically required) configurations microsoft graph api asset tenant id authenticates using client credentials and tenant id configuration parameters parameter description type required url a url to the target host string required tenant id the tenant id string required client id the client id string required client secret the client secret string required scope list of permission scopes for this action array required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional password grant (delegated authentication) authenticates on behalf of a user using oauth 2 0 credentials configuration parameters parameter description type required url a url to the target host string required login url string optional tenant id string required oauth un the username for authentication string required oauth pwd the password for authentication string required oauth cl id the client id string required oauth cl secret the client secret string required scope permission scopes for this action array optional verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional 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 list of 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 graph openid connect refresh token grant authenticates using refresh token 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 optional verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions get presence retrieves the presence status of a user in microsoft graph api using their unique id endpoint url /users/{{id}}/presence method get input argument name type required description path parameters id string required the unique identifier of the user input example {"path parameters" {"id" "12345678 1234 1234 1234 123456789abc"}} output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier availability string output field availability activity string output field activity outofofficesettings object output field outofofficesettings outofofficesettings message object response message outofofficesettings isoutofoffice boolean output field outofofficesettings isoutofoffice sequencenumber string output field sequencenumber output example {"id" "66825e03 7ef5 42da 9069 724602c31f6b","availability" "donotdisturb","activity" "presenting","outofofficesettings" {"message"\ null,"isoutofoffice"\ false},"sequencenumber" "a0129311063"} get user by id retrieve detailed information for a specific user by their unique id in microsoft graph api endpoint url v1 0/users/{{id}} method get input argument name type required description path parameters id string required parameters for the get user by id action parameters $select string optional parameters for the get user by id action input example {"parameters" {"$select" "displayname,givenname,postalcode"},"path parameters" {"id" "87d349ed 44d7 43e1 9a83 5f2406dee5bd"}} output parameter type description status code number http status code of the response reason string response reason phrase businessphones array output field businessphones displayname string name of the resource givenname string name of the resource jobtitle string output field jobtitle mail string output field mail mobilephone string output field mobilephone officelocation string output field officelocation preferredlanguage string output field preferredlanguage surname string name of the resource userprincipalname string name of the resource id string unique identifier output example {"businessphones" \["string"],"displayname" "example name","givenname" "example name","jobtitle" "string","mail" "string","mobilephone" "string","officelocation" "string","preferredlanguage" "string","surname" "example name","userprincipalname" "example name","id" "12345678 1234 1234 1234 123456789abc"} list a users direct membership retrieve a user's direct group memberships, directory roles, and administrative units in microsoft graph api using their email address endpoint url /v1 0/users/{{email address}}/memberof method get input argument name type required description path parameters email address string required the account associated with the email parameters $filter string optional filters results (rows) parameters $count string optional include count of items parameters $search string optional search items by search phrases input example {"parameters" {"$search" "search","$count" "count","$filter" "filter"},"path parameters" {"email address" "integrations\@swimlaneintegrations onmicrosoft com"}} output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data value array value for the parameter value \@odata type string response data value id string unique identifier value deleteddatetime object value for the parameter value description string value for the parameter value displayname string name of the resource value roletemplateid string unique identifier value ismembermanagementrestricted boolean value for the parameter value membershiprule object value for the parameter value membershiptype object type of the resource value membershipruleprocessingstate object value for the parameter value visibility object value for the parameter output example {"@odata context" "https //graph microsoft com/v1 0/$metadata#directoryobjects","value" \[{"@odata type" "#microsoft graph directoryrole","id" "4c04548e 9bc4 45fb 8738 168610ddbe0c","deleteddatetime"\ null,"description" "can manage all aspects of azure ad and microsoft services that use azure ad identities ","displayname" "global administrator","roletemplateid" "62e90394 69f5 4237 9190 012177145e10"},{"@odata type" "#microsoft graph directoryrole","id" "417c2fd9 6d31 4d37 927f a6e54d37a4a4","delet update user updates a user's properties in microsoft graph api using the specified 'user id' and provided json body data endpoint url /v1 0/users/{{user id}} method patch input argument name type required description path parameters user id string required parameters for the update user action aboutme string optional a freeform text entry field for the user to describe themselves accountenabled boolean optional true if the account is enabled; otherwise, false agegroup string optional sets the age group of the user birthday string optional the birthday of the user businessphones array optional the telephone numbers for the user city string optional the city in which the user is located companyname string optional the name of the company that the user is associated consentprovidedforminor string optional sets whether consent has been obtained for minors country string optional the country/region in which the user is located customsecurityattributes object optional an open complex type that holds the value of a custom security attribute that is assigned to a directory object customsecurityattributes \@odata type string optional response data department string optional the name for the department in which the user works displayname string optional the name displayed in the address book for the user employeeid string optional the employee identifier assigned to the user by the organization employeetype string optional captures enterprise worker type givenname string optional the given name (first name) of the user employeehiredate string optional the hire date of the user the timestamp type represents date and time information using iso 8601 format and is always in utc time employeeleavedatetime string optional the date and time when the user left or will leave the organization the timestamp type represents date and time information using iso 8601 format and is always in utc time employeeorgdata object optional represents organization data (for example, division and costcenter) associated with a user employeeorgdata costcenter string optional the cost center associated with the user employeeorgdata division string optional the name of the division in which the user works interests array optional a list for the user to describe their interests jobtitle string optional the user's job title mail string optional the smtp address for the user, input example {"json body" {"aboutme" "name","accountenabled"\ true,"agegroup" "adult","birthday" "2014 01 01t00 00 00z","businessphones" \["+44 20 7946 0958","+91 9876543210"],"city" "london","companyname" "global enterprises","consentprovidedforminor" "granted","country" "us","customsecurityattributes" {"@odata type" "#microsoft graph customsecurityattributevalue"},"department" "engineering","displayname" "ane m smith","employeeid" "emp123456789","employeetype" "contractor","givenname" "sana","employeehiredate" "2024 05 27t00 00 00z","employeeleavedatetime" "2014 01 01t00 00 00z ","employeeorgdata" {"costcenter" "string","division" "string"},"interests" \["cooking","playing"],"jobtitle" "software engineer","mail" "jeff\@contoso com","mailnickname" "john","mobilephone" "+1234567890","mysite" "https //www example com/johndoe","officelocation" "hyderabad","onpremisesextensionattributes" {"extensionattribute1" "string","extensionattribute2" "string","extensionattribute3" "string","extensionattribute4" "string","extensionattribute5" "string","extensionattribute6" "string","extensionattribute7" "string","extensionattribute8" "string","extensionattribute9" "string","extensionattribute10" "string","extensionattribute11" "string","extensionattribute12" "string","extensionattribute13" "string","extensionattribute14" "string","extensionattribute15" "string"},"onpremisesimmutableid" "01234567 89ab cdef 0123 456789abcdef","othermails" \["bob\@contoso com","robert\@fabrikam com"],"passwordpolicies" "disablestrongpassword","passwordprofile" {"forcechangepasswordnextsignin"\ true,"forcechangepasswordnextsigninwithmfa"\ false,"password" "string"},"pastprojects" \["project alpha","project gama"],"postalcode" "12345","preferredlanguage" "en us","responsibilities" \["managing client relationships","project management"],"schools" \["high school abc","high school xyz"],"skills" \["data analysis","data science"],"state" "ap","streetaddress" "sreeram nagar","surname" "sana","usagelocation" "us","userprincipalname" "john doe\@example com","usertype" "guest"},"path parameters" {"user id" "678f80e5 e506 4f10 895d bf664699475d"}} output parameter type description status code number http status code of the response reason string response reason phrase response text string output field response text output example {"response text" "string"} response headers header description example cache control directives for caching mechanisms no cache client request id http response header client request id 38dd3b1c ff86 4da9 9647 bdcde1a611c8 content encoding http response header content encoding gzip content type the media type of the resource application/json;odata metadata=minimal;odata streaming=true;ieee754compatible=false;charset=utf 8 date the date and time at which the message was originated tue, 28 may 2024 10 09 05 gmt odata version http response header odata version 4 0 request id http response header request id fffdaaac 17ba 4eb6 8fac 779da55a44b3 strict transport security http response header strict transport security max age=31536000 transfer encoding http response header transfer encoding chunked vary http response header vary accept encoding x ms ags diagnostic http response header x ms ags diagnostic {"serverinfo" {"datacenter" "central india","slice" "e","ring" "3","scaleunit" "000","roleinstance" "pn1pepf00007040"}} x ms resource unit http response header x ms resource unit 1