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 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 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 Limiting application permissions to specific Exchange Online mailboxes.

Action Setup

OData filters

Information on the filter input formatting can be found here.

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 here.

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	booleanColumn	This column stores boolean values.
calculated	calculatedColumn	This column's data is calculated based on other columns.
choice	choiceColumn	This column stores data from a list of choices.
currency	currencyColumn	This column stores currency values.
dateTime	dateTimeColumn	This column stores DateTime values.
geolocation	geolocationColumn	This column stores a geolocation.
lookup	lookupColumn	This column's data is looked up from another source in the site.
number	numberColumn	This column stores number values.
personOrGroup	personOrGroupColumn	This column stores Person or Group values.
text	textColumn	This column stores text values.
validation	columnValidation	This column stores validation formula and message for the column.
hyperlinkOrPicture	hyperlinkOrPictureColumn	This column stores hyperlink or picture values.
term	termColumn	This column stores taxonomy terms.
thumbnail	thumbnailColumn	This column stores thumbnail values.
contentApprovalStatus	contentApprovalStatusColumn	This column stores content approval status.

For a complete version of this table please see the official column definition table.

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 OData filters section.

The column used to filter the output must be indexed, see the Microsoft documentation 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

An Introduction to Microsoft Graph API

Microsoft Graph REST API v1.0 reference

Query Parameters Documentation - OData V4

Microsoft Graph Security API v1.0 refrence

Azure AD OAuth2 flow

oauthlib Legacy Application client, 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":"[email protected]"}}

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
[email protected]	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.
[email protected]	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":"[email protected]","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":["[email protected]","[email protected]"],"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":"[email protected]","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	fffdaaac-17ba-4eb6-8fac-779da55a44b3
Content-Encoding	HTTP response header: Content-Encoding	gzip
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 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	2