Insights & updates from our experts
Overview
Connects to Microsoft Entra ID via the Microsoft Graph API to create, manage and restore users, set their managers, reset their passwords and sign-in methods, invite guests, manage licenses, groups and group members, app assignments, access packages and directory roles, mark user risk, and to start workflows when users, groups or group members change. Intune managed devices are in the Microsoft Intune connector.
Prerequisites
- A Microsoft Entra ID (formerly Azure AD) tenant.
- An app registration in Microsoft Entra. Obtain:
- Tenant ID: GUID visible in Microsoft Entra → Overview → Tenant ID.
- Client ID: visible on the app registration's Overview page.
- Client Secret: created under the app registration's Certificates & secrets. Copy the value at creation time; it is not shown again.
- API permissions granted on the app registration (type: Application), with admin consent. Grant only the ones for the actions and triggers you use:
Device.Read.All: lets Retrieve Entra group members return thedevice_idof members that are devices. Without it, Microsoft Graph returns a device member with its ID and type only, itsdevice_idis empty, and the job fails withNot all devices have deviceId.GroupMember.Read.All: used by the group lookup and group members actions.User.Read.All: used by Get Entra user, Search Entra users, Get Entra user licenses, Restore deleted Entra user and the user triggers.User.ReadWrite.All: used by Update Entra user, Delete Entra user and Set Entra user manager. Account enabled also needsUser.EnableDisableAccount.All, and phone numbers also needUser-Phone.ReadWrite.All.User.Create: used by Create Entra user.User.ReadWrite.Allalso works.User.DeleteRestore.All: used by Restore deleted Entra user. Restoring a user who holds a privileged administrator role also needsUser.ReadWrite.Alland an administrator role on the app.LicenseAssignment.ReadWrite.All: used by Assign or remove Entra user licenses.User.RevokeSessions.All: used by Revoke Entra user sign-in sessions.Group.Read.All: used by Get Entra group by ID and the group triggers.Group.ReadWrite.All: used by Create Entra group, Update Entra group, Delete Entra group and Add Entra group owner.GroupMember.ReadWrite.All: used by Add member to Entra group and Remove member from Entra group. Remove member from Entra group also reads the group after a 404, which Microsoft lists underGroupMember.Read.All.Device.ReadWrite.All: used by Add member to Entra group when the member is a device.User-PasswordProfile.ReadWrite.All: used by Reset Entra user password. The app also needs at least the User Administrator role in Microsoft Entra.UserAuthMethod-TAP.ReadWrite.All: used by Issue Entra Temporary Access Pass.UserAuthenticationMethod.Read.All: used by List Entra user authentication methods.UserAuthenticationMethod.ReadWrite.All: used by Remove Entra user authentication method.User.Invite.All: used by Invite Entra guest user.AppRoleAssignment.ReadWrite.All: used by Assign Entra enterprise app to user, which also needsApplication.Read.All, and by Remove Entra enterprise app assignment.EntitlementManagement.ReadWrite.All: used by Request Entra access package assignment.RoleManagement.ReadWrite.Directory: used by Assign Entra directory role and Remove Entra directory role assignment. Delete Entra group, Add member to Entra group and Remove member from Entra group also need it when the group can be assigned to a role.RoleEligibilitySchedule.ReadWrite.Directory: used by Create Entra PIM eligible role assignment.IdentityRiskyUser.ReadWrite.All: used by Confirm Entra user compromised and Dismiss Entra user risk. These need a Microsoft Entra ID P2 license.- The transitive group members action uses
GroupMember.Read.All. Call Microsoft Graph uses whatever its endpoint needs.
- Warning:
RoleManagement.ReadWrite.Directory,RoleEligibilitySchedule.ReadWrite.Directory,AppRoleAssignment.ReadWrite.AllandEntitlementManagement.ReadWrite.Alllet the app give itself, or anyone, more access: any directory role, any Microsoft Graph permission, or any access package.UserAuthMethod-TAP.ReadWrite.AllandUserAuthenticationMethod.ReadWrite.Alllet the app sign in as any user or change how a user signs in. Grant them only when you use the actions that need them. - Licenses: Create Entra PIM eligible role assignment needs Microsoft Entra ID P2 or Microsoft Entra ID Governance. Request Entra access package assignment needs Microsoft Entra ID P2 or Microsoft Entra ID Governance for the users it assigns. Assigning a group with Assign Entra enterprise app to user needs Microsoft Entra ID P1 or P2, and members of groups inside that group get no access.
Authentication
The connector uses the OAuth 2.0 client credentials flow against https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token and requests the https://graph.microsoft.com/.default scope. The Tenant ID, Client ID, and Client Secret obtained in Prerequisites are passed as:
tenant_id: substituted into the OAuth2 token endpoint URL.client_idandclient_secret: sent in the token request body as form-encoded credentials.
Environment (optional): leave these blank to use the Microsoft global cloud.
| Field | Default | Description |
|---|---|---|
oauth2_endpoint (OAuth2 endpoint) | https://login.microsoftonline.com | Base URL of the token endpoint. The connector adds /{tenant_id}/oauth2/v2.0/token. |
graph_endpoint (Graph API endpoint) | https://graph.microsoft.com/v1.0 | Base URL for Microsoft Graph calls. |
Triggers
Every trigger is driven by a Microsoft Graph change notification subscription. Deploying a trigger records what to watch. The Renew directory subscriptions action creates the subscription and keeps it alive, so put that action in a runbook of its own on a Scheduler trigger every 15 minutes before you rely on any trigger.
New Entra user
Starts a workflow when a user is created in Microsoft Entra ID. Microsoft Graph sends a change notification, so nothing polls the directory.
Microsoft Graph sends the same notification for a new user, a changed user and a deleted user that can still be restored. When a notification arrives, this trigger asks Microsoft Graph when each user was created, and keeps the users created in the last 60 minutes. Microsoft sends a notification that was not accepted again for up to 4 hours, so after an iPaaS outage longer than 60 minutes, a user created more than 60 minutes before the outage ended is not reported. Each new user is reported once, even when it changes again in that hour, unless two notifications about it arrive at the same moment. When more than 300 objects change in one delivery, only the first 300 are checked. A deleted user is not reported, and the log of the trigger event names its ID. When Microsoft Graph does not show a user yet, the trigger asks Microsoft to send the notification again, for up to 5 minutes. After that, the user is not reported, and the log names its ID. A notification carries the user ID, not the user: call Get Entra user to read the user.
Microsoft can put several notifications in one request, so Users is a list. Read every user in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice, so a workflow that must act once checks the User ID first. When this trigger cannot ask Microsoft Graph in time, it answers with an error, and Microsoft sends the notifications again later.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: User.Read.All
Output
| Field Name | Type | Description |
|---|---|---|
users | Object[] | The new users: user_id and created_date_time |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
New or updated Entra user
Starts a workflow when a user in Microsoft Entra ID is created, changed, or deleted in a way that can still be restored. Microsoft Graph sends a change notification, so nothing polls the directory.
A notification carries the user ID, not the user: call Get Entra user to read it. A user deleted in the last 30 days is not found by Get Entra user. Before a step that deletes something or removes access, read the user again with Get Entra user, and go on only when it shows the change.
A runbook that changes the user it was started for, for example with Update Entra user, starts this trigger again. Check a field that the first run set before you change the user again.
Microsoft can put several notifications in one request, so Users is a list. Read every user in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice, so a workflow that must act once checks the User ID first.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: User.Read.All
Output
| Field Name | Type | Description |
|---|---|---|
users | Object[] | The users that changed: user_id |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
Deleted Entra user
Starts a workflow when a user is deleted permanently from Microsoft Entra ID. Microsoft Graph sends a change notification, so nothing polls the directory.
Microsoft keeps a deleted user for 30 days, and this trigger fires when the user is deleted for good: when the 30 days end, or when an administrator deletes the user from the deleted users list. A user deleted in a way that can still be restored starts New or updated Entra user instead.
Microsoft can put several notifications in one request, so Users is a list. Read every user in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: User.Read.All
Output
| Field Name | Type | Description |
|---|---|---|
users | Object[] | The deleted users: user_id |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
New Entra group
Starts a workflow when a group is created in Microsoft Entra ID. Microsoft Graph sends a change notification, so nothing polls the directory.
Microsoft Graph sends the same notification for a new group, a changed group and a deleted group that can still be restored. When a notification arrives, this trigger asks Microsoft Graph when each group was created, and keeps the groups created in the last 60 minutes. Microsoft sends a notification that was not accepted again for up to 4 hours, so after an iPaaS outage longer than 60 minutes, a group created more than 60 minutes before the outage ended is not reported. Each new group is reported once, even when it changes again in that hour, unless two notifications about it arrive at the same moment. When more than 300 objects change in one delivery, only the first 300 are checked. A deleted group is not reported, and the log of the trigger event names its ID. When Microsoft Graph does not show a group yet, the trigger asks Microsoft to send the notification again, for up to 5 minutes. After that, the group is not reported, and the log names its ID. A notification carries the group ID, not the group: call Get Entra group by ID to read the group.
Microsoft can put several notifications in one request, so Groups is a list. Read every group in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice, so a workflow that must act once checks the Group ID first. When this trigger cannot ask Microsoft Graph in time, it answers with an error, and Microsoft sends the notifications again later.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: Group.Read.All
Output
| Field Name | Type | Description |
|---|---|---|
groups | Object[] | The new groups: group_id and created_date_time |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
New or updated Entra group
Starts a workflow when a group in Microsoft Entra ID is created, changed, or deleted in a way that can still be restored. Microsoft Graph sends a change notification, so nothing polls the directory.
A notification carries the group ID, not the group: call Get Entra group by ID to read it. Before a step that deletes something or removes access, read the group again with Get Entra group by ID, and go on only when it shows the change.
A runbook that changes the group it was started for, for example with Update Entra group or Add member to Entra group, starts this trigger again. Check a field that the first run set before you change the group again.
Microsoft can put several notifications in one request, so Groups is a list. Read every group in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice, so a workflow that must act once checks the Group ID first.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: Group.Read.All
Output
| Field Name | Type | Description |
|---|---|---|
groups | Object[] | The groups that changed: group_id |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
New or updated Entra group member
Starts a workflow when the members of one Microsoft Entra group change. Microsoft Graph sends a change notification, so nothing polls the directory.
A notification names each member who joined or left the group by object ID only. It does not say whether the member is a user, a group, a device or another directory object. Call Retrieve Entra group members to read the type of a member who joined. If a notification names no member, the trigger skips it. Before a step that deletes something or removes access, read the members again with Retrieve Entra group members, and go on only when they show the change.
A runbook that adds a member to or removes a member from the group it watches starts this trigger again. Check whether the change came from the runbook itself before you change the members again.
Microsoft can put several notifications in one request, so Changes is a list. Read every change in it with the Flow connector's Loop action. Microsoft can deliver the same notification twice, so a workflow that must act once checks the Member ID first.
One trigger watches one group. Microsoft allows 100 user and group subscriptions per application in a tenant, and each trigger of this kind takes one of them.
Required: the Renew directory subscriptions action, in its own runbook on a Scheduler trigger every 15 minutes, creates this trigger's subscription within 15 minutes of a deploy and keeps it alive. Leave URL postfix empty. Deprovision the trigger before you delete its runbook.
Permissions required: Group.Read.All
Configuration
| Field | Required | Description |
|---|---|---|
| Group ID | Yes | Object ID (GUID) of the group to watch |
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | The group this trigger watches |
changes | Object[] | One row per member who joined or left, in the order Microsoft sent them: member_id, and removed, which is true when the member left the group. A member who joined and then left has two rows |
subscription_id | String | The Microsoft Graph subscription that sent the notification |
Actions
Entra group ID from name
Retrieves Microsoft Entra group IDs for a list of display names in a single request via Microsoft Graph's group list API.
Use case: convert human-readable group names to their IDs before calling other actions (e.g. Retrieve Entra group members). Also useful to validate that a group exists in the tenant.
Permissions required: GroupMember.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_names | String[] | Yes | - | Up to 10 Entra group display names to look up |
Example Input
{
"group_names": ["IT Administrators", "Sales Team", "Marketing Department"]
}
Output
| Field Name | Type | Description |
|---|---|---|
results | Object[] | One object per matched group. See Result object fields below. |
Result object fields
| Field Name | Type | Description |
|---|---|---|
display_name | String | Group display name as stored in Entra |
group_id | String | Entra group object ID (GUID) |
Example Output
{
"results": [
{
"display_name": "IT Administrators",
"group_id": "12345678-1234-1234-1234-123456789012"
}
]
}
Error Handling
The job fails without retry on 400 / 401 / 403 responses (invalid input or credential / permission issue). On 429 (rate limited) or 503 (service unavailable), the connector waits for the time in Retry-After and retries the request.
Operational notes
- Call at the start of runbooks that operate on groups by name. Pass the returned IDs to Retrieve Entra group members or other group actions.
- Group display names are case-sensitive and must match the value stored in Entra (e.g.
it administratorswill not match a group namedIT Administrators). - The connector deduplicates
group_namesbefore calling Microsoft Graph, so input length minus distinct-output length is the count of misses. - Groups not found in Entra are omitted from the results.
Retrieve Entra group members
Retrieves all members of a Microsoft Entra ID group with pagination support via Microsoft Graph's group members API. Members may be users, devices, or other directory objects.
Use case: audit group memberships, synchronize group data with other systems, or process group members in workflows that need user or device information. Pair with Entra group ID from name to resolve the group_id from a friendly name first.
Permissions required: GroupMember.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Entra group ID (obtained from the Entra group ID from name action) |
| page_size | Integer | No | 100 | Number of members per page (1-999) |
Example Input
{
"group_id": "12345678-1234-1234-1234-123456789012",
"page_size": 50
}
Output
| Field Name | Type | Description |
|---|---|---|
odata_count | Integer | Total members in the group. Microsoft Graph only populates this when the request includes $count=true and ConsistencyLevel: eventual; expect null otherwise. |
has_next_page | Boolean | true while more pages remain. Re-invoke the action until false. |
members | Object[] | One object per member. See Member object fields below. |
Member object fields
| Field Name | Type | Description |
|---|---|---|
member_id | String | Entra object ID of the member (user, device, etc.) |
device_id | String | Entra device ID (the AAD-side deviceId). Populated only when the member is a device. Distinct from the Intune managed-device ID returned by Managed devices from Intune in the Microsoft Intune connector. |
odata_type | String | Microsoft Graph type of the member (e.g. #microsoft.graph.user, #microsoft.graph.device) |
Example Output
{
"members": [
{
"member_id": "87654321-4321-4321-4321-210987654321",
"device_id": null,
"odata_type": "#microsoft.graph.user"
},
{
"member_id": "98765432-5432-5432-5432-321098765432",
"device_id": "device123",
"odata_type": "#microsoft.graph.device"
}
]
}
Error Handling
The job fails without retry on 400 / 401 / 403 responses (invalid input or credential / permission issue), or when a member's required fields are missing. On 429 (rate limited) or 503 (service unavailable), the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Graph v1.0 does not return service principals as members (known issue). If your runbook depends on service principal membership, follow the workaround in the linked doc.
Operational notes
- Pair with Entra group ID from name to resolve
group_idfrom a friendly group name. - Paginate to completion: call until
has_next_pageisfalse. - Branch on
odata_typeto detect member kind, not ondevice_idpresence (#microsoft.graph.uservs.#microsoft.graph.device). - For large groups, raise
page_sizetoward the max (999) to reduce round-trips.
Get Entra user
Reads one Microsoft Entra user by object ID or user principal name through Microsoft Graph's get user API.
Use case: look up a user's name, job details, account status and usage location before you update, license or remove them.
Permissions required: User.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
Example Input
{ "user_id": "adele.vance@contoso.com" }
Output
| Field Name | Type | Description |
|---|---|---|
user | Object | The user. See User object fields below. |
User object fields
| Field Name | Type | Description |
|---|---|---|
user_id | String | Object ID (GUID) |
display_name | String | Display name |
given_name | String | First name |
surname | String | Last name |
user_principal_name | String | User principal name (sign-in name) |
mail | String | Primary SMTP address |
job_title | String | Job title |
department | String | Department |
office_location | String | Office location |
mobile_phone | String | Mobile phone number |
business_phones | String[] | Business phone numbers |
account_enabled | Boolean | true when the account can sign in |
usage_location | String | Two-letter country code. Required before a license can be assigned. |
employee_id | String | Employee ID |
company_name | String | Company name |
city | String | City |
country | String | Country or region |
created_date_time | DateTime | When the user was created |
Example Output
{
"user": {
"user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
"display_name": "Adele Vance",
"user_principal_name": "adele.vance@contoso.com",
"account_enabled": true,
"usage_location": "US"
}
}
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Search Entra users
Lists Microsoft Entra users that match a filter or a display name search, one page at a time, through Microsoft Graph's list users API.
Use case: find the users of a department, the disabled accounts, or a user whose name you know only in part.
Permissions required: User.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| filter | String | No | - | OData filter, for example department eq 'Sales' or accountEnabled eq false |
| search | String | No | - | Text to look for in the display name |
| page_size | Integer | No | 100 | Number of users per page (1-999) |
Example Input
{ "filter": "department eq 'Sales'", "search": "adele", "page_size": 50 }
Output
| Field Name | Type | Description |
|---|---|---|
odata_count | Integer | Total users that match |
has_next_page | Boolean | true while more pages remain. Re-invoke the action until false. |
users | Object[] | One object per user, with the same fields as Get Entra user |
Example Output
{
"odata_count": 1,
"has_next_page": false,
"users": [{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "display_name": "Adele Vance" }]
}
Error Handling
The job fails without retry on 400 / 401 / 403 responses. A 400 usually means the filter uses a property or operator that Microsoft Graph does not support. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Operational notes
- Leave both Filter and Search empty to list every user.
- Paginate to completion: call until
has_next_pageisfalse. - Microsoft Graph can take a short time to show users that were just created, updated or deleted.
Update Entra user
Changes the properties of one Microsoft Entra user through Microsoft Graph's update user API. Only the fields you set are sent. An empty field leaves the property as it is.
Use case: keep a user's job title, department, office and account status in step with Xurrent, or block sign-in for a leaver.
Permissions required: User.ReadWrite.All. Account enabled also needs User.EnableDisableAccount.All, and Mobile phone and Business phone also need User-Phone.ReadWrite.All. Changing the account status or phone of an administrator also needs an administrator role on the app.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| display_name | String | No | - | Display name |
| given_name | String | No | - | First name |
| surname | String | No | - | Last name |
| job_title | String | No | - | Job title |
| department | String | No | - | Department |
| office_location | String | No | - | Office location |
| company_name | String | No | - | Company name (up to 64 characters) |
| employee_id | String | No | - | Employee ID (up to 16 characters) |
| employee_type | String | No | - | Employee type, for example Employee or Contractor |
| mobile_phone | String | No | - | Mobile phone number |
| business_phone | String | No | - | Business phone number. Microsoft Entra keeps one. |
| city | String | No | - | City |
| state | String | No | - | State or province |
| country | String | No | - | Country or region |
| street_address | String | No | - | Street address |
| postal_code | String | No | - | Postal code |
| usage_location | String | No | - | Two-letter country code (ISO 3166). Required before a license can be assigned. |
| preferred_language | String | No | - | Preferred language, for example en-US |
| user_principal_name | String | No | - | New user principal name |
| mail_nickname | String | No | - | Mail alias |
| account_enabled | Boolean | No | - | false blocks sign-in, true allows it |
Example Input
{ "user_id": "adele.vance@contoso.com", "job_title": "Sales Lead", "account_enabled": true }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user that was updated, as given. After a rename of a user given by user principal name, the new user principal name |
updated_fields | String[] | The Microsoft Graph properties that were sent |
Example Output
{ "user_id": "adele.vance@contoso.com", "updated_fields": ["jobTitle", "accountEnabled"] }
Error Handling
The job fails when no field is set. It fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- The password cannot be changed with this action.
- A field cannot be cleared: an empty field is not sent.
- Properties of users synchronized from on-premises Active Directory may be read only.
Delete Entra user
Deletes one Microsoft Entra user through Microsoft Graph's delete user API. Microsoft keeps a deleted user for 30 days, with its mailbox, licenses and group memberships, and an administrator can restore it in that time. After 30 days the user is deleted permanently.
Use case: remove the account of a leaver at the end of an offboarding workflow.
Permissions required: User.ReadWrite.All. Deleting a user who holds an administrator role also needs an administrator role on the app.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
Example Input
{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd" }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user, as given |
existed | Boolean | false when Microsoft Graph had no such user, so nothing was deleted |
Example Output
{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "existed": true }
Error Handling
A 404 is not an error: existed is false. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Graph can take about 30 seconds to show a user that was just created or restored. In that time it answers 404, so
existedisfalseand nothing is deleted. When the user was created or restored a moment before, wait about 30 seconds and run the step again.
Get Entra user licenses
Reads the licenses of one Microsoft Entra user from the user's assignedLicenses and licenseAssignmentStates properties through Microsoft Graph's get user API.
Use case: check which licenses a user holds, and whether each one came from a group, before you assign or remove one.
Permissions required: User.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
Example Input
{ "user_id": "adele.vance@contoso.com" }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | Object ID of the user |
assigned_licenses | Object[] | Every license the user holds, direct or from a group: sku_id and disabled_plans |
license_assignment_states | Object[] | One row per assignment: sku_id, state (for example Active or Error), error, assigned_by_group (empty for a direct assignment) and disabled_plans |
Example Output
{
"user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
"assigned_licenses": [{ "sku_id": "c7df2760-2c81-4ef7-b578-5b5392b571df", "disabled_plans": [] }],
"license_assignment_states": [
{ "sku_id": "c7df2760-2c81-4ef7-b578-5b5392b571df", "state": "Active", "error": "None", "assigned_by_group": null, "disabled_plans": [] }
]
}
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Assign or remove Entra user licenses
Adds licenses to, and removes licenses from, one Microsoft Entra user in one request through Microsoft Graph's assign license API.
Use case: give a new hire their licenses, or take the licenses of a leaver back.
Permissions required: LicenseAssignment.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| add_sku_ids | String[] | No | - | SKU IDs (GUIDs) of the licenses to add |
| disabled_plan_ids | String[] | No | - | Service plan IDs (GUIDs) to turn off in every license that is added |
| remove_sku_ids | String[] | No | - | SKU IDs (GUIDs) of the licenses to remove |
Example Input
{ "user_id": "adele.vance@contoso.com", "add_sku_ids": ["c7df2760-2c81-4ef7-b578-5b5392b571df"], "remove_sku_ids": [] }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | Object ID of the user |
added_sku_ids | String[] | The SKU IDs that were added |
removed_sku_ids | String[] | The SKU IDs that were removed |
Example Output
{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "added_sku_ids": ["c7df2760-2c81-4ef7-b578-5b5392b571df"], "removed_sku_ids": [] }
Error Handling
The job fails when neither list holds a SKU ID, or when a value is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses. A 400 often means the user has no Usage location: set it with Update Entra user first. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Operational notes
- A license that a group gives cannot be removed from the user directly. Remove the user from the group instead.
Revoke Entra user sign-in sessions
Signs one Microsoft Entra user out of every application through Microsoft Graph's revoke sign-in sessions API. Every refresh token and browser session cookie of the user stops working, so the user must sign in again.
Use case: lock a leaver or a compromised account out at once, together with Update Entra user setting Account enabled to false.
Permissions required: User.RevokeSessions.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
Example Input
{ "user_id": "adele.vance@contoso.com" }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user, as given |
revoked | Boolean | true when Microsoft accepted the request |
Example Output
{ "user_id": "adele.vance@contoso.com", "revoked": true }
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft can take a few minutes to revoke the tokens.
- External (guest) users are not signed out, because they sign in through their home tenant.
Create Entra user
Creates one Microsoft Entra user with a first password through Microsoft Graph's create user API. Of the optional profile fields, only the ones you set are sent.
Use case: create the account of a new hire from a Xurrent request, before you give it a manager, licenses and groups.
Permissions required: User.Create. User.ReadWrite.All also works.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| display_name | String | Yes | - | Display name |
| user_principal_name | String | Yes | - | Sign-in name, alias@domain. The domain must be a verified domain of the tenant. |
| mail_nickname | String | Yes | - | Mail alias |
| password | Secret String | Yes | - | First password. It must meet the password rules of the tenant. |
| force_change_password_next_sign_in | Boolean | No | true | true makes the user choose a new password at the first sign-in |
| account_enabled | Boolean | No | true | false creates the account with sign-in blocked |
| given_name | String | No | - | First name |
| surname | String | No | - | Last name |
| job_title | String | No | - | Job title |
| department | String | No | - | Department |
| office_location | String | No | - | Office location |
| company_name | String | No | - | Company name (up to 64 characters) |
| employee_id | String | No | - | Employee ID (up to 16 characters) |
| employee_type | String | No | - | Employee type, for example Employee or Contractor |
| city | String | No | - | City |
| state | String | No | - | State or province |
| country | String | No | - | Country or region |
| street_address | String | No | - | Street address |
| postal_code | String | No | - | Postal code |
| usage_location | String | No | - | Two-letter country code (ISO 3166). Required before a license can be assigned. |
| preferred_language | String | No | - | Preferred language, for example en-US |
Example Input
{ "display_name": "Adele Vance", "user_principal_name": "adele.vance@contoso.com", "mail_nickname": "adele.vance", "password": "<secret>", "usage_location": "US" }
Output
| Field Name | Type | Description |
|---|---|---|
user | Object | The new user, with the fields that Microsoft returns when it creates a user: user_id, display_name, given_name, surname, user_principal_name, mail, job_title, office_location, mobile_phone and business_phones. Read the other fields with Get Entra user. |
Example Output
{ "user": { "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "display_name": "Adele Vance", "user_principal_name": "adele.vance@contoso.com" } }
Error Handling
The job fails without retry on 400 / 401 / 403 responses, and on 5xx responses: Microsoft may have created the user before it failed, so check for it with Get Entra user before you run the step again. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- The password is not part of the output.
- Phone numbers are not set by this action. Set them with Update Entra user after the user is created.
Set Entra user manager
Sets the manager of one Microsoft Entra user through Microsoft Graph's assign manager API. A user has one manager, so this replaces the current one.
Use case: put a new hire under the right manager, or move a user to a new manager after a team change in Xurrent.
Permissions required: User.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| manager_id | String | Yes | - | Object ID (GUID) of the manager: a user or an organizational contact |
Example Input
{ "user_id": "adele.vance@contoso.com", "manager_id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0" }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user, as given |
manager_id | String | Object ID of the manager |
Example Output
{ "user_id": "adele.vance@contoso.com", "manager_id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0" }
Error Handling
The job fails when the manager ID is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Restore deleted Entra user
Restores one deleted Microsoft Entra user through Microsoft Graph's restore deleted item API. Microsoft keeps a deleted user for 30 days. After 30 days the user is deleted permanently and cannot be restored. The action restores the ID only when it is a deleted user. When the ID is an active user, for example because an earlier run restored it, the action returns that user with already_restored set to true.
Use case: bring back the account of a user who was deleted by mistake, or of a leaver who returns within 30 days.
Permissions required: User.DeleteRestore.All and User.Read.All. Restoring a user who holds a privileged administrator role also needs User.ReadWrite.All and an administrator role on the app.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) of the deleted user |
| new_user_principal_name | String | No | - | New user principal name for the restored user, for example when another user now has the old one |
| auto_reconcile_proxy_conflict | Boolean | No | false | true removes the email addresses of the restored user that an active user now has, instead of failing |
Example Input
{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "auto_reconcile_proxy_conflict": true }
Output
| Field Name | Type | Description |
|---|---|---|
user | Object | The restored user, with the fields that Microsoft returns when it restores a user: user_id, display_name, given_name, surname, user_principal_name, mail, job_title, office_location, mobile_phone and business_phones. Read the other fields with Get Entra user. |
already_restored | Boolean | true when the ID was already an active user, so nothing was restored |
Example Output
{ "user": { "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "display_name": "Adele Vance", "user_principal_name": "adele.vance@contoso.com" }, "already_restored": false }
Error Handling
The job fails, and restores nothing, when the user ID is not a GUID, when the ID is a deleted object that is not a user, or when the ID is neither a deleted user nor an active user. It fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Graph can take about 30 seconds to catch up after a user is deleted or restored. In that time the job can fail with a 404, such as
Unable to read the company information from the directory. When the user was deleted or restored a moment before, wait about 30 seconds and run the step again. - Right after a delete, Microsoft Graph can still answer 404 when the action looks for the user in the deleted items, and still return the user as an active user. The action then returns
already_restoredset totrueand restores nothing. Wait about 30 seconds after a delete before you restore the user.
Operational notes
- A deleted user is found by its object ID only. New or updated Entra user reports the ID of a user deleted in a way that can still be restored.
Reset Entra user password
Sets a new password for one Microsoft Entra user by changing the user's password profile through Microsoft Graph's update user API.
Use case: give a locked-out user a new first password from a Xurrent request, or reset the password of a compromised account.
Permissions required: User-PasswordProfile.ReadWrite.All, and the app must also hold at least the User Administrator role in Microsoft Entra. Resetting the password of an administrator needs a higher role.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| password | Secret String | Yes | - | New password. It must meet the password rules of the tenant. |
| force_change_password_next_sign_in | Boolean | No | true | true makes the user choose a new password at the next sign-in |
Example Input
{ "user_id": "adele.vance@contoso.com", "password": "<secret>", "force_change_password_next_sign_in": true }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user, as given |
force_change_password_next_sign_in | Boolean | true when the user must choose a new password at the next sign-in |
Example Output
{ "user_id": "adele.vance@contoso.com", "force_change_password_next_sign_in": true }
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission and role the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- The password of a federated user cannot be reset with this action.
- The password is not part of the output.
Issue Entra Temporary Access Pass
Creates a Temporary Access Pass for one Microsoft Entra user through Microsoft Graph's create temporaryAccessPassMethod API. A Temporary Access Pass is a passcode with a time limit that the user signs in with, for example to set up a new phone or security key.
Use case: let a user who lost their phone sign in to register a new authentication method, after the service desk has checked who they are.
Permissions required: UserAuthMethod-TAP.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| lifetime_in_minutes | Integer | No | - | How long the pass works, from 10 to 43200 minutes (30 days). Empty uses the default of the tenant's Temporary Access Pass policy. |
| is_usable_once | Boolean | No | - | true makes the pass work for one sign-in only |
| start_date_time | DateTime | No | - | When the pass starts to work |
Example Input
{ "user_id": "adele.vance@contoso.com", "lifetime_in_minutes": 60, "is_usable_once": true }
Output
| Field Name | Type | Description |
|---|---|---|
method_id | String | ID of the pass as an authentication method |
temporary_access_pass | Secret String | The passcode |
start_date_time | DateTime | When the pass starts to work |
lifetime_in_minutes | Integer | How long the pass works |
is_usable_once | Boolean | true when the pass works for one sign-in only |
is_usable | Boolean | true when the pass can be used now |
method_usability_reason | String | Why the pass can or cannot be used now, for example NotYetValid |
created_date_time | DateTime | When the pass was created |
Example Output
{ "method_id": "6f1967b7-15e8-4935-ac26-d50770ed07a7", "temporary_access_pass": "<secret>", "lifetime_in_minutes": 60, "is_usable_once": true, "is_usable": true, "method_usability_reason": "EnabledByPolicy" }
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses, and on 5xx responses: Microsoft may have created the pass before it failed, so check for it with List Entra user authentication methods before you run the step again. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- A user can have only one Temporary Access Pass that is usable within its lifetime. A new pass deletes the current one, so running the step again makes a pass that was already handed out stop working.
List Entra user authentication methods
Lists the authentication methods that one Microsoft Entra user has registered, such as Microsoft Authenticator, phone numbers, security keys and Windows Hello for Business, through Microsoft Graph's list methods API.
Use case: see what a user has set up before you remove a lost phone or issue a Temporary Access Pass.
Permissions required: UserAuthenticationMethod.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
Example Input
{ "user_id": "adele.vance@contoso.com" }
Output
| Field Name | Type | Description |
|---|---|---|
methods | Object[] | One object per method. See Method object fields below. |
Method object fields
| Field Name | Type | Description |
|---|---|---|
method_id | String | ID of the method |
odata_type | String | Kind of method, for example #microsoft.graph.phoneAuthenticationMethod. Remove Entra user authentication method takes it as the method type. |
display_name | String | Name of the app, key or device, for Microsoft Authenticator, security keys and Windows Hello for Business |
phone_number | String | Phone number, for a phone method |
phone_type | String | mobile, alternateMobile or office, for a phone method |
email_address | String | Email address, for an email method |
Example Output
{ "methods": [{ "method_id": "3179e48a-750b-4051-897c-87b9720928f7", "odata_type": "#microsoft.graph.phoneAuthenticationMethod", "phone_number": "+1 5555551234", "phone_type": "mobile" }] }
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Operational notes
- The password is listed as a method too. It cannot be removed: change it with Reset Entra user password.
Remove Entra user authentication method
Removes one authentication method of one Microsoft Entra user, for example a lost phone, an old Microsoft Authenticator app or a security key. Microsoft Graph removes each kind of method through its own API, such as delete phoneAuthenticationMethod, so the action takes the type of the method as well as its ID.
Use case: remove a lost or stolen device from the sign-in methods of a user. To remove every method, loop over the list from List Entra user authentication methods and skip the password and QR code PIN methods.
Permissions required: UserAuthenticationMethod.ReadWrite.All. For security keys (FIDO2), UserAuthMethod-Passkey.ReadWrite.All is enough.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) or user principal name of the user |
| method_id | String | Yes | - | method_id from List Entra user authentication methods |
| method_type | String | Yes | - | odata_type from List Entra user authentication methods, for example #microsoft.graph.microsoftAuthenticatorAuthenticationMethod |
Example Input
{ "user_id": "adele.vance@contoso.com", "method_id": "3179e48a-750b-4051-897c-87b9720928f7", "method_type": "#microsoft.graph.phoneAuthenticationMethod" }
Output
| Field Name | Type | Description |
|---|---|---|
user_id | String | The user, as given |
method_id | String | ID of the method |
existed | Boolean | false when the user had no such method, so nothing was removed |
Example Output
{ "user_id": "adele.vance@contoso.com", "method_id": "3179e48a-750b-4051-897c-87b9720928f7", "existed": true }
Error Handling
The job fails when the method type is the password or a type that this action does not know. A 404 is not an error: existed is false. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- These types can be removed: Microsoft Authenticator, phone, FIDO2 security key, software OATH token, email, Temporary Access Pass, Windows Hello for Business, platform credential, external authentication method and resource account key.
existedis alsofalsewhen the user does not exist.- The password cannot be removed. Change it with Reset Entra user password.
- A QR code PIN method cannot be removed: Microsoft Graph offers that only in beta, at
/beta/users/{id}/authentication/qrCodePinMethod. The job fails for that type, so a loop over the methods of a user stops there. - A phone number that is the default multifactor authentication method of the user cannot be removed.
- A mobile number cannot be removed while the user has an alternate mobile number.
- Microsoft Graph can take about 30 seconds to show a method that was just added, such as a new Temporary Access Pass. In that time it answers 404, so
existedisfalseand nothing is removed. When the method was added a moment before, wait about 30 seconds and run the step again.
Invite Entra guest user
Invites one external person to the tenant as a guest user through Microsoft Graph's create invitation API. Microsoft creates the guest user at once, and the person redeems the invitation to sign in.
Use case: give a partner or contractor access from a Xurrent request, then add the guest user to a group.
Permissions required: User.Invite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| email_address | String | Yes | - | Email address of the person to invite |
| redirect_url | String | Yes | - | Address the person lands on after redeeming the invitation, for example https://myapps.microsoft.com |
| display_name | String | No | - | Display name of the guest user |
| send_invitation_message | Boolean | No | false | true makes Microsoft send the invitation email |
Example Input
{ "email_address": "megan@fabrikam.com", "redirect_url": "https://myapps.microsoft.com", "display_name": "Megan Bowen", "send_invitation_message": true }
Output
| Field Name | Type | Description |
|---|---|---|
invitation_id | String | ID of the invitation |
user_id | String | Object ID of the guest user that Microsoft created |
invite_redeem_url | String | Address the person uses to redeem the invitation |
status | String | PendingAcceptance, Completed, InProgress or Error |
invited_user_type | String | Type of the new user, Guest by default |
Example Output
{ "invitation_id": "9071bfde-35e0-47d2-a582-d244ab1b4af6", "user_id": "cbb896f9-8306-49d0-b56b-b8e39cd28825", "status": "PendingAcceptance", "invited_user_type": "Guest" }
Error Handling
The job fails without retry on 400 / 401 / 403 responses, and on 5xx responses: Microsoft may have created the guest user before it failed, so check for it with Search Entra users before you run the step again. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- The action does not work when B2B invitations are turned off in the tenant.
Create Entra group
Creates a Microsoft Entra security group or Microsoft 365 group through Microsoft Graph's create group API, optionally with its owners and members.
Use case: create the access group of a new project or team from a Xurrent request.
Permissions required: Group.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| display_name | String | Yes | - | Group name (up to 256 characters) |
| mail_nickname | String | Yes | - | Mail alias (up to 64 characters, no spaces or @ ( ) \ [ ] " ; : < > ,) |
| description | String | No | - | Group description |
| group_type | String | No | Security | Security or Microsoft 365 |
| visibility | String | No | - | Private, Public or HiddenMembership |
| owner_ids | String[] | No | - | Object IDs (GUIDs) of the owners |
| member_ids | String[] | No | - | Object IDs (GUIDs) of the first members |
Example Input
{ "display_name": "Project Falcon", "mail_nickname": "project-falcon", "group_type": "Security", "owner_ids": ["87d349ed-44d7-43e1-9a83-5f2406dee5bd"] }
Output
| Field Name | Type | Description |
|---|---|---|
group | Object | The new group. See Group object fields below. |
Group object fields
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID (GUID) |
display_name | String | Group name |
description | String | Group description |
mail_nickname | String | Mail alias |
mail | String | Email address, for a mail-enabled group |
mail_enabled | Boolean | true for a Microsoft 365 group |
security_enabled | Boolean | true for a security group |
group_types | String[] | Unified for a Microsoft 365 group, DynamicMembership for a dynamic group |
visibility | String | Private, Public or HiddenMembership |
is_assignable_to_role | Boolean | true when the group can be assigned to a Microsoft Entra role, so its members get that role. Microsoft Graph leaves it empty for other groups. |
created_date_time | DateTime | When the group was created |
Example Output
{ "group": { "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "display_name": "Project Falcon", "security_enabled": true } }
Error Handling
The job fails when owners and members together are more than 20, or when an ID is not a GUID. It fails without retry on 400 / 401 / 403 responses, and on 5xx responses: Microsoft may have created the group before it failed, so check for it with Entra group ID from name before you run the step again. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Operational notes
- Set at least one owner. Microsoft creates a group that has no owner anonymously, and that group cannot be changed afterwards.
- Mail-enabled security groups and distribution groups cannot be created through Microsoft Graph.
Update Entra group
Changes the name, description, mail alias or visibility of one Microsoft Entra group through Microsoft Graph's update group API. Only the fields you set are sent.
Use case: rename a group, or change its description, when the team or project it serves changes.
Permissions required: Group.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
| display_name | String | No | - | Group name |
| description | String | No | - | Group description |
| mail_nickname | String | No | - | Mail alias |
| visibility | String | No | - | Private, Public or HiddenMembership |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "description": "Members of Project Falcon" }
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID of the group |
updated_fields | String[] | The Microsoft Graph properties that were sent |
Example Output
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "updated_fields": ["description"] }
Error Handling
The job fails when no field is set, or when the group ID is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Delete Entra group
Deletes one Microsoft Entra group through Microsoft Graph's delete group API. Microsoft 365 groups and security groups can be restored for 30 days and are then deleted permanently. Distribution groups are deleted permanently at once.
Use case: remove the access group of a project that has ended.
Permissions required: Group.ReadWrite.All. A group that can be assigned to a role also needs RoleManagement.ReadWrite.Directory, unless the app owns the group.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315" }
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID of the group |
existed | Boolean | false when Microsoft Graph had no such group, so nothing was deleted |
Example Output
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "existed": true }
Error Handling
A 404 is not an error: existed is false. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Graph can take about 30 seconds to show a group that was just created or restored. In that time it answers 404, so
existedisfalseand nothing is deleted. When the group was created or restored a moment before, wait about 30 seconds and run the step again.
Get Entra group by ID
Reads one Microsoft Entra group by object ID through Microsoft Graph's get group API.
Use case: read a group's name, type and visibility before you change it or its members.
Permissions required: Group.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315" }
Output
| Field Name | Type | Description |
|---|---|---|
group | Object | The group, with the same fields as Create Entra group returns |
Example Output
{ "group": { "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "display_name": "Project Falcon", "security_enabled": true } }
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Add member to Entra group
Adds one user, group, device or other directory object to a Microsoft Entra group through Microsoft Graph's add members API.
Use case: give a user the access that comes with a group, for example when a Xurrent request is approved.
Permissions required: GroupMember.ReadWrite.All. Adding a device also needs Device.ReadWrite.All. A group that can be assigned to a role also needs RoleManagement.ReadWrite.Directory.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
| member_id | String | Yes | - | Object ID (GUID) of the user, group or device to add |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd" }
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID of the group |
member_id | String | Object ID of the member |
already_member | Boolean | true when the object was already a member, so nothing was added |
Example Output
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "already_member": false }
Error Handling
The job fails when an ID is not a GUID. A 400 that says the object is already a member is not an error: already_member is true, and the job log says that nothing changed. The job fails without retry on other 400 responses and on 401 / 403 / 404 responses. Microsoft Graph answers 404 when the object or the group does not exist. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- A Microsoft 365 group takes only users as members.
- Members cannot be added to a group with dynamic membership.
Remove member from Entra group
Removes one member from a Microsoft Entra group through Microsoft Graph's remove member API. The member object itself is not deleted.
Use case: take away the access that comes with a group when a user changes role or leaves.
Permissions required: GroupMember.ReadWrite.All, and GroupMember.Read.All, which Microsoft lists for reading a group, to check the group after a 404. A group that can be assigned to a role also needs RoleManagement.ReadWrite.Directory.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
| member_id | String | Yes | - | Object ID (GUID) of the member to remove |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd" }
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID of the group |
member_id | String | Object ID of the member |
existed | Boolean | false when the object was not a member of the group, so nothing was removed |
Example Output
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "existed": true }
Error Handling
On a 404, the action reads the group. When the group exists, existed is false: the object was not a direct member, or a delete that was sent again had already removed it. When Microsoft Graph has no group with that ID, the job fails. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Members cannot be removed from a group with dynamic membership.
- Only a direct member is removed. A member through a group inside this group keeps the access. Call Search transitive Entra group members to see who still gets it.
- Microsoft Graph can take about 30 seconds to show a group that was just created. In that time the job fails with "Microsoft Graph has no group with ID". Run the step again after about 30 seconds.
- Microsoft Graph can take about 30 seconds to show a member that was just added. In that time it answers 404, so
existedisfalseand nothing is removed. When the member was added a moment before, wait about 30 seconds and run the step again.
Add Entra group owner
Adds one user or service principal as an owner of a Microsoft Entra group through Microsoft Graph's add owners API.
Use case: hand a group to the manager of a new team, or add a second owner so that the group keeps an owner when one leaves.
Permissions required: Group.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
| owner_id | String | Yes | - | Object ID (GUID) of the user or service principal to add as an owner |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "owner_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd" }
Output
| Field Name | Type | Description |
|---|---|---|
group_id | String | Object ID of the group |
owner_id | String | Object ID of the owner |
already_owner | Boolean | true when the object was already an owner, so nothing was added |
Example Output
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "owner_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "already_owner": false }
Error Handling
The job fails when an ID is not a GUID. A 400 that says the object is already an owner is not an error: already_owner is true. The job fails without retry on other 400 responses and on 401 / 403 / 404 responses. Microsoft Graph answers 404 when the object does not exist. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Teams can take up to 2 hours to show a new owner of the group of a team.
Search transitive Entra group members
Lists every member of a Microsoft Entra group, including the members of the groups inside it, one page at a time, through Microsoft Graph's list transitive members API.
Use case: find everyone who gets a group's access, also through nested groups, for an access review.
Permissions required: GroupMember.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| group_id | String | Yes | - | Object ID (GUID) of the group |
| member_type | String | No | All | All, Users, Groups or Devices |
| search | String | No | - | Text to look for in the display name |
| page_size | Integer | No | 100 | Number of members per page (1-999) |
Example Input
{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_type": "Users", "page_size": 200 }
Output
| Field Name | Type | Description |
|---|---|---|
odata_count | Integer | Total members that match |
has_next_page | Boolean | true while more pages remain. Re-invoke the action until false. |
members | Object[] | One object per member: member_id, odata_type (for example #microsoft.graph.user), display_name, and for users user_principal_name and mail |
Example Output
{
"odata_count": 1,
"has_next_page": false,
"members": [{ "member_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "odata_type": "#microsoft.graph.user", "display_name": "Adele Vance" }]
}
Error Handling
The job fails without retry on 400 / 401 / 403 / 404 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Operational notes
- Paginate to completion: call until
has_next_pageisfalse. - Without permission to read a kind of member, Microsoft Graph returns those members with only their ID and type.
Assign Entra enterprise app to user
Assigns one user, security group or service principal to an enterprise application, with one of the app's roles, through Microsoft Graph's grant appRoleAssignment API.
Use case: give a user access to an application that signs in through Microsoft Entra, when a Xurrent request is approved.
Permissions required: AppRoleAssignment.ReadWrite.All and Application.Read.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| service_principal_id | String | Yes | - | Object ID (GUID) of the enterprise application (its service principal) |
| principal_id | String | Yes | - | Object ID (GUID) of the user, security group or service principal to assign |
| app_role_id | String | No | 00000000-0000-0000-0000-000000000000 | ID (GUID) of the app role to give. The default assigns an app that declares no roles. |
Example Input
{ "service_principal_id": "9028d19c-26a9-4809-8e3f-20ff73e2d75e", "principal_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "app_role_id": "ef7437e6-4f94-4a0a-a110-a439eb2aa8f7" }
Output
| Field Name | Type | Description |
|---|---|---|
assignment_id | String | ID of the assignment. Remove Entra enterprise app assignment takes it. |
app_role_id | String | The app role that was given |
principal_id | String | Object ID of the user, group or service principal |
principal_type | String | User, Group or ServicePrincipal |
principal_display_name | String | Name of the user, group or service principal |
resource_id | String | Object ID of the enterprise application |
resource_display_name | String | Name of the enterprise application |
created_date_time | DateTime | When the assignment was made |
Example Output
{ "assignment_id": "-WmtM5na7Uus0D8kI1yylpU9Mdo0Pb9OoBJvd3T5eKc", "app_role_id": "ef7437e6-4f94-4a0a-a110-a439eb2aa8f7", "principal_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd", "principal_type": "User", "resource_display_name": "Fabrikam App" }
Error Handling
The job fails when an ID is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses, and on 5xx responses: Microsoft may have made the assignment before it failed. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- Assigning a group needs a Microsoft Entra ID P1 or P2 license. Members of groups inside the assigned group get no access.
- Running the step again fails the job when the assignment already exists.
Remove Entra enterprise app assignment
Removes one assignment of a user, group or service principal from an enterprise application through Microsoft Graph's delete appRoleAssignedTo API.
Use case: take away the access of a leaver to an application that signs in through Microsoft Entra.
Permissions required: AppRoleAssignment.ReadWrite.All
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| service_principal_id | String | Yes | - | Object ID (GUID) of the enterprise application (its service principal) |
| assignment_id | String | Yes | - | assignment_id from Assign Entra enterprise app to user |
Example Input
{ "service_principal_id": "9028d19c-26a9-4809-8e3f-20ff73e2d75e", "assignment_id": "-WmtM5na7Uus0D8kI1yylpU9Mdo0Pb9OoBJvd3T5eKc" }
Output
| Field Name | Type | Description |
|---|---|---|
service_principal_id | String | Object ID of the enterprise application |
assignment_id | String | ID of the assignment |
existed | Boolean | false when the application had no such assignment, so nothing was removed |
Example Output
{ "service_principal_id": "9028d19c-26a9-4809-8e3f-20ff73e2d75e", "assignment_id": "-WmtM5na7Uus0D8kI1yylpU9Mdo0Pb9OoBJvd3T5eKc", "existed": true }
Error Handling
The job fails when the enterprise application ID is not a GUID, and when Microsoft Graph answers 404 because it has no enterprise application with that ID. A 404 about the assignment is not an error: existed is false. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- Microsoft Graph can take about 30 seconds to show an assignment that was just made. In that time it answers 404, so
existedisfalseand the assignment stays in place. When the assignment was made a moment before, wait about 30 seconds and run the step again.
Request Entra access package assignment
Assigns one user to an access package of Microsoft Entra entitlement management, as an administrator request, through Microsoft Graph's create assignmentRequest API. The access package then gives the user its resources, under the rules of the chosen policy.
Use case: give a user the set of groups, apps and sites that an access package holds, when a Xurrent request is approved.
Permissions required: EntitlementManagement.ReadWrite.All. Instead of that permission, the app can hold the Access package assignment manager role. The users it assigns need a Microsoft Entra ID P2 or Microsoft Entra ID Governance license.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_id | String | Yes | - | Object ID (GUID) of the user to assign |
| access_package_id | String | Yes | - | ID (GUID) of the access package |
| assignment_policy_id | String | Yes | - | ID (GUID) of the access package policy to assign under |
| justification | String | No | - | Reason for the request |
Example Input
{ "user_id": "46184453-e63b-4f20-86c2-c557ed5d5df9", "access_package_id": "a914b616-e04e-476b-aa37-91038f0b165b", "assignment_policy_id": "2264bf65-76ba-417b-a27d-54d291f0cbc8" }
Output
| Field Name | Type | Description |
|---|---|---|
request_id | String | ID of the request |
request_type | String | adminAdd |
state | String | How far the request got, for example submitted, delivering or delivered |
status | String | More detail on the state, for example Accepted |
Example Output
{ "request_id": "c0a2d3e1-6f2b-4a8e-9b4d-1e7f3a2c5d60", "request_type": "adminAdd", "state": "submitted", "status": "Accepted" }
Error Handling
The job fails when an ID is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses, and on 5xx responses: Microsoft may have accepted the request before it failed. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- Running the step again for a user who already has the assignment fails the job.
Operational notes
- Microsoft accepts the request first and delivers the access after that, so
statecan still besubmittedwhen the step ends.
Assign Entra directory role
Gives one user, service principal or role-assignable group a Microsoft Entra directory role, such as Helpdesk Administrator, as an active assignment through Microsoft Graph's create unifiedRoleAssignment API.
Use case: give a new service desk member the role they need, from an approved Xurrent request.
Permissions required: RoleManagement.ReadWrite.Directory
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| principal_id | String | Yes | - | Object ID (GUID) of the user, service principal or group |
| role_definition_id | String | Yes | - | ID (GUID) of the role: the role template ID or the role definition ID of the tenant |
| directory_scope_id | String | No | / | Where the role applies: / for the whole tenant, or /administrativeUnits/{id} for one administrative unit |
Example Input
{ "principal_id": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d", "role_definition_id": "c2cf284d-6c41-4e6b-afac-4b80928c9034" }
Output
| Field Name | Type | Description |
|---|---|---|
assignment_id | String | ID of the assignment. Remove Entra directory role assignment takes it. |
role_definition_id | String | The role |
principal_id | String | Object ID of the user, service principal or group |
directory_scope_id | String | Where the role applies |
Example Output
{ "assignment_id": "YUb1sHQtUEyvox7IA_Eu_mm3jqnUe4lEhvatluHVi2I-1", "role_definition_id": "c2cf284d-6c41-4e6b-afac-4b80928c9034", "principal_id": "f8ca5a85-489a-49a0-b555-0a6d81e56f0d", "directory_scope_id": "/" }
Error Handling
The job fails when an ID is not a GUID. It fails without retry on 400 / 401 / 403 / 404 responses, and on 5xx responses: Microsoft may have made the assignment before it failed. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- Running the step again for the same principal, role and scope fails the job, because the assignment already exists.
Operational notes
- For an administrator role, Create Entra PIM eligible role assignment lets the user turn the role on only when they need it.
Create Entra PIM eligible role assignment
Makes one user, service principal or role-assignable group eligible for a Microsoft Entra directory role in Privileged Identity Management (PIM), through Microsoft Graph's create roleEligibilityScheduleRequest API. An eligible user does not hold the role until they turn it on in PIM.
Use case: let an administrator turn on a role when they need it, instead of holding it all the time.
Permissions required: RoleEligibilitySchedule.ReadWrite.Directory. The tenant needs a Microsoft Entra ID P2 or Microsoft Entra ID Governance license.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| principal_id | String | Yes | - | Object ID (GUID) of the user, service principal or group |
| role_definition_id | String | Yes | - | ID (GUID) of the role: the role template ID or the role definition ID of the tenant |
| directory_scope_id | String | No | / | Where the role applies: / for the whole tenant, or /administrativeUnits/{id} for one administrative unit |
| justification | String | No | - | Reason for the assignment. The role settings in PIM can require it. |
| start_date_time | DateTime | No | - | When the eligibility starts. Empty means now. |
| end_date_time | DateTime | No | - | When the eligibility ends. Empty asks for an eligibility that does not end, which the role settings in PIM can refuse. |
Example Input
{ "principal_id": "071cc716-8147-4397-a5ba-b2105951cc0b", "role_definition_id": "8424c6f0-a189-499e-bbd0-26c1753c96d4", "justification": "On-call rota", "end_date_time": "2027-04-10T00:00:00Z" }
Output
| Field Name | Type | Description |
|---|---|---|
request_id | String | ID of the request |
status | String | State of the request, for example Provisioned |
principal_id | String | Object ID of the user, service principal or group |
role_definition_id | String | The role |
directory_scope_id | String | Where the role applies |
target_schedule_id | String | ID of the eligibility schedule that the request made |
Example Output
{ "request_id": "50877283-9d40-433c-bab8-7986dc10458a", "status": "Provisioned", "principal_id": "071cc716-8147-4397-a5ba-b2105951cc0b", "role_definition_id": "8424c6f0-a189-499e-bbd0-26c1753c96d4", "directory_scope_id": "/", "target_schedule_id": "50877283-9d40-433c-bab8-7986dc10458a" }
Error Handling
The job fails when an ID is not a GUID, and when Microsoft answers with the request in status Canceled, Denied, Failed or Revoked. It fails without retry on 400 / 401 / 403 / 404 responses, and on 5xx responses: Microsoft may have accepted the request before it failed. A 403 gives Microsoft's reason and names the permission the action needs. On 429, the connector waits for the time in Retry-After and retries the request.
Limitations
- Running the step again for the same principal, role and scope fails the job, because the eligibility already exists.
Remove Entra directory role assignment
Removes one active Microsoft Entra directory role assignment through Microsoft Graph's delete unifiedRoleAssignment API.
Use case: take an administrator role away from a user who changes job or leaves.
Permissions required: RoleManagement.ReadWrite.Directory
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| assignment_id | String | Yes | - | assignment_id from Assign Entra directory role |
Example Input
{ "assignment_id": "lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1" }
Output
| Field Name | Type | Description |
|---|---|---|
assignment_id | String | ID of the assignment |
existed | Boolean | false when Microsoft Graph had no such assignment, so nothing was removed |
Example Output
{ "assignment_id": "lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1", "existed": true }
Error Handling
A 404 is not an error: existed is false. The job fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Limitations
- An eligible assignment from Create Entra PIM eligible role assignment is not an active assignment, so this action does not remove it.
- Microsoft Graph can take about 30 seconds to show an assignment that was just made. In that time it answers 404, so
existedisfalseand the assignment stays in place. When the assignment was made a moment before, wait about 30 seconds and run the step again.
Confirm Entra user compromised
Marks one or more Microsoft Entra users as compromised in Microsoft Entra ID Protection through Microsoft Graph's confirm compromised API. Microsoft sets the risk level of each user to high.
Use case: record it in Microsoft Entra when a Xurrent security incident confirms that an account was taken over.
Permissions required: IdentityRiskyUser.ReadWrite.All. The tenant needs a Microsoft Entra ID P2 license.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_ids | String[] | Yes | - | Object IDs (GUIDs) of the users |
Example Input
{ "user_ids": ["29f270bb-4d23-4f68-8a57-dc73dc0d4caf"] }
Output
| Field Name | Type | Description |
|---|---|---|
user_ids | String[] | The users that were marked as compromised |
Example Output
{ "user_ids": ["29f270bb-4d23-4f68-8a57-dc73dc0d4caf"] }
Error Handling
The job fails when no user ID is set, or when an ID is not a GUID. It fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Dismiss Entra user risk
Dismisses the risk of one or more Microsoft Entra users in Microsoft Entra ID Protection through Microsoft Graph's dismiss API. Microsoft sets the risk level of each user to none.
Use case: close a risk alert after the security team has checked the sign-ins and found nothing wrong, or after the password of the user was reset.
Permissions required: IdentityRiskyUser.ReadWrite.All. The tenant needs a Microsoft Entra ID P2 license.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| user_ids | String[] | Yes | - | Object IDs (GUIDs) of the users |
Example Input
{ "user_ids": ["04487ee0-f4f6-4e7f-8999-facc5a30e232"] }
Output
| Field Name | Type | Description |
|---|---|---|
user_ids | String[] | The users whose risk was dismissed |
Example Output
{ "user_ids": ["04487ee0-f4f6-4e7f-8999-facc5a30e232"] }
Error Handling
The job fails when no user ID is set, or when an ID is not a GUID. It fails without retry on 400 / 401 / 403 responses. A 403 gives Microsoft's reason and names the permission the action needs. On 429 or 503, the connector waits for the time in Retry-After and retries the request.
Renew directory subscriptions
Creates and keeps alive every Microsoft Graph subscription that the triggers on this connection depend on, through the subscription API.
Put this action in a runbook of its own, on a Scheduler trigger that runs every 15 minutes, and set that runbook's concurrency to one run at a time. The triggers of this connector do not work without it. Each run lists the subscriptions Microsoft holds for this application, deletes any that points at a trigger of this connection but is not recorded, creates the subscription of every recorded trigger that has none, and renews, in batches of 20, every subscription that ends within a day. Microsoft ends a user or group subscription after 29 days unless it is renewed.
Permissions required: User.Read.All for the user triggers, Group.Read.All for the group triggers.
Input Parameters
None.
Output
| Field Name | Type | Description |
|---|---|---|
results | Object[] | One row per subscription the run touched: runbook_id, resource, change_type, subscription_id, expires_at, outcome (created, renewed, removed, skipped or failed) and error |
created | Integer | Subscriptions created |
renewed | Integer | Subscriptions renewed |
removed | Integer | Subscriptions deleted because no trigger records them |
Example Output
{
"created": 1,
"renewed": 0,
"removed": 0,
"results": [{ "runbook_id": "01a13544-c2d4-7cc7-8726-e73182d73e05", "resource": "users", "change_type": "updated", "subscription_id": "0fc0f4a5-3f6e-4bc5-9d1a-52e2c5b81e0c", "outcome": "created" }]
}
Error Handling
A run with nothing to do ends quietly. A run in which a subscription could not be created or renewed fails after it has handled every other row, and its log names the trigger and what Microsoft answered. The next run tries again.
Operational notes
- Use the connection the triggers use. A run on another connection finds nothing to keep alive.
- Deprovision a trigger before you delete its runbook, or this action keeps its subscription alive.
Call Microsoft Graph
Sends one request to any Microsoft Graph v1.0 endpoint with this connection's credentials, for what the other actions do not cover.
Use case: read or change a directory object that has no action of its own, for example a user's manager (/users/{id}/manager).
Permissions required: the application permission that the endpoint's Microsoft Graph page lists.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| method | String | Yes | GET | GET, POST, PATCH, PUT or DELETE |
| path | String | Yes | - | Path after the Graph address, starting with /, for example /users/adele.vance@contoso.com/manager |
| query | Object[] | No | - | Query parameters, each with name and value, for example $select = id,displayName |
| body | String | No | - | Request body as JSON |
| advanced_query | Boolean | No | false | Sends ConsistencyLevel: eventual, which $search, $count and some filters need |
Example Input
{ "method": "GET", "path": "/users/adele.vance@contoso.com/manager", "query": [{ "name": "$select", "value": "id,displayName" }] }
Output
| Field Name | Type | Description |
|---|---|---|
status | Integer | HTTP status of the answer |
body | String | Body of the answer as text. Usually JSON. |
Example Output
{ "status": 200, "body": "{\"id\":\"0b2e1b59-2b8c-4b36-8d2b-5f6a5d4e1a2b\",\"displayName\":\"Megan Bowen\"}" }
Error Handling
The job fails when the path does not start with one /, or holds .., ://, \, # or spaces, and when the body is not JSON. It fails without retry on any status from 400 up, and the message gives Microsoft's error. On a 403, the message also names the permission that the endpoint's Microsoft Graph page lists, and says that it needs admin consent. On 429, the connector waits for the time in Retry-After and retries the request. On 503, it does so for GET and DELETE only.
Operational notes
- The request always goes to the Graph address of this connection, so the credentials are never sent to another host.
- A
POST,PATCHorPUTis sent again only after a 429, which Microsoft answers before it runs the request. - The job log shows the body and the answer as text. Use the dedicated actions, such as Issue Entra Temporary Access Pass, for a request that sends or returns a secret.
Rate Limiting
Microsoft Graph throttles requests per tenant and per app and returns 429 Too Many Requests with a Retry-After header when the threshold is exceeded (reference). The connector retries on 429 and 503 responses.
| HTTP status | Connector behavior |
|---|---|
| 429 Too Many Requests | Wait for the value of the Retry-After header (seconds or HTTP date), then retry. If the header is absent, the connector applies a default backoff. |
| 503 Service Unavailable | Retry with backoff. |
| 401 / 403 | Fail without retry. The message gives Microsoft's reason, such as a wrong credential, a missing permission or license, or a tenant setting. |
| 400 | Fail without retry. Invalid input. |
Notes:
- Microsoft's throttling guidance recommends exponential backoff when
Retry-Afteris absent. - 503 is treated as a transient error; it is not part of Microsoft Graph's documented throttling contract.
Best Practices
- Resolve IDs at runbook start: Call Entra group ID from name to convert friendly group names into IDs. Don't hard-code GUIDs that may change.
- Paginate to completion: Retrieve Entra group members, Search Entra users and Search transitive Entra group members are iterator actions. Call until
has_next_pageisfalse. - Scope permissions minimally: Grant only the permissions that the actions and triggers you use list. Don't grant broader scopes.
- Keep subscriptions alive: Run Renew directory subscriptions every 15 minutes in its own runbook whenever a trigger of this connector is deployed.
- Check before you create again: Create Entra user does not retry when Microsoft answers with a server error, because the user may exist. Call Get Entra user with the user principal name before you run it again.
- Remove sign-in methods one at a time: Remove Entra user authentication method removes one method. Loop over the
methodsof List Entra user authentication methods and pass eachmethod_idandodata_type. Skip#microsoft.graph.passwordAuthenticationMethodand#microsoft.graph.qrCodePinAuthenticationMethod, which this action cannot remove. - Prefer eligible administrator roles: Create Entra PIM eligible role assignment gives a role that the user turns on only when needed. Keep Assign Entra directory role for roles that must stay active.
- Keep privileged IDs fixed: Set the role definition ID and directory scope of Assign Entra directory role and Create Entra PIM eligible role assignment, the enterprise application ID and app role ID of Assign Entra enterprise app to user, and the access package ID and policy ID of Request Entra access package assignment, as fixed values in the runbook. Do not map them from what a requester typed.
- Check for role-assignable groups: A member of a group that can be assigned to a role gets the roles of the group, Global Administrator included. When the connection holds
RoleManagement.ReadWrite.Directory, Add member to Entra group can add a requester to such a group. Before you add a requester, call Get Entra group by ID and stop whenis_assignable_to_roleistrue. An owner of such a group can add members to it, so do the same check before Add Entra group owner. Keep the directory role actions on an app registration of their own, so that the app registration behind Add member to Entra group does not hold that permission.
Common Use Cases
- Group-based access workflows: Entra group ID from name → Retrieve Entra group members → provision or revoke Xurrent access based on membership changes.
- User onboarding: New Entra user → Get Entra user → Update Entra user (usage location) → Assign or remove Entra user licenses → Add member to Entra group.
- User offboarding: Update Entra user (account enabled
false) → Revoke Entra user sign-in sessions → Remove member from Entra group → Delete Entra user. - New hire from a Xurrent request: Create Entra user (usage location set) → Set Entra user manager → Assign or remove Entra user licenses → Add member to Entra group.
- Rehire within 30 days: Restore deleted Entra user → Update Entra user (account enabled
true, new job title) → Set Entra user manager. - Lost phone: List Entra user authentication methods → Remove Entra user authentication method (the lost phone) → Issue Entra Temporary Access Pass so the user can register a new one.
- Compromised account: Confirm Entra user compromised → Revoke Entra user sign-in sessions → Reset Entra user password → Dismiss Entra user risk when the incident is closed.
- Guest access: Invite Entra guest user → Add member to Entra group or Assign Entra enterprise app to user.
- Access requests: Request Entra access package assignment for a bundle of access, or Assign Entra enterprise app to user for one application. Remove Entra enterprise app assignment takes it back.
- Administrator access: Create Entra PIM eligible role assignment, or Assign Entra directory role and later Remove Entra directory role assignment.
References
API Reference
- Microsoft Graph REST API (v1.0)
- List groups (Microsoft Graph API)
- List group members (Microsoft Graph API)
- user resource type
- group resource type
- subscription resource type
- Change notifications overview
Concepts
- Advanced query capabilities on directory objects
- Microsoft Graph throttling
- OAuth 2.0 client credentials flow
- Microsoft Graph permissions reference



.webp)










.webp)

















