1. Help
  2. Integrations
  3. iPaaS
  4. connector-documentation
  5. Microsoft Entra Connector

‍

purple icon for coordination.
We’ve moved!
Our Help Center has a new home and our URLs have changed. Please update your bookmark to this page before April 30, 2026

Microsoft Entra Connector

Create and manage Entra users, groups, licenses, sign-in methods, app access and roles, and start workflows when users, groups or members change.

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 the device_id of members that are devices. Without it, Microsoft Graph returns a device member with its ID and type only, its device_id is empty, and the job fails with Not 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 needs User.EnableDisableAccount.All, and phone numbers also need User-Phone.ReadWrite.All.
    • User.Create: used by Create Entra user. User.ReadWrite.All also works.
    • User.DeleteRestore.All: used by Restore deleted Entra user. Restoring a user who holds a privileged administrator role also needs User.ReadWrite.All and 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 under GroupMember.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 needs Application.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.All and EntitlementManagement.ReadWrite.All let the app give itself, or anyone, more access: any directory role, any Microsoft Graph permission, or any access package. UserAuthMethod-TAP.ReadWrite.All and UserAuthenticationMethod.ReadWrite.All let 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_id and client_secret: sent in the token request body as form-encoded credentials.

Environment (optional): leave these blank to use the Microsoft global cloud.

FieldDefaultDescription
oauth2_endpoint (OAuth2 endpoint)https://login.microsoftonline.comBase URL of the token endpoint. The connector adds /{tenant_id}/oauth2/v2.0/token.
graph_endpoint (Graph API endpoint)https://graph.microsoft.com/v1.0Base 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 NameTypeDescription
usersObject[]The new users: user_id and created_date_time
subscription_idStringThe 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 NameTypeDescription
usersObject[]The users that changed: user_id
subscription_idStringThe 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 NameTypeDescription
usersObject[]The deleted users: user_id
subscription_idStringThe 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 NameTypeDescription
groupsObject[]The new groups: group_id and created_date_time
subscription_idStringThe 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 NameTypeDescription
groupsObject[]The groups that changed: group_id
subscription_idStringThe 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

FieldRequiredDescription
Group IDYesObject ID (GUID) of the group to watch

Output

Field NameTypeDescription
group_idStringThe group this trigger watches
changesObject[]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_idStringThe 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

ParameterTypeRequiredDefaultDescription
group_namesString[]Yes-Up to 10 Entra group display names to look up

Example Input

{
  "group_names": ["IT Administrators", "Sales Team", "Marketing Department"]
}

Output

Field NameTypeDescription
resultsObject[]One object per matched group. See Result object fields below.
Result object fields
Field NameTypeDescription
display_nameStringGroup display name as stored in Entra
group_idStringEntra 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 administrators will not match a group named IT Administrators).
  • The connector deduplicates group_names before 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Entra group ID (obtained from the Entra group ID from name action)
page_sizeIntegerNo100Number of members per page (1-999)

Example Input

{
  "group_id": "12345678-1234-1234-1234-123456789012",
  "page_size": 50
}

Output

Field NameTypeDescription
odata_countIntegerTotal members in the group. Microsoft Graph only populates this when the request includes $count=true and ConsistencyLevel: eventual; expect null otherwise.
has_next_pageBooleantrue while more pages remain. Re-invoke the action until false.
membersObject[]One object per member. See Member object fields below.
Member object fields
Field NameTypeDescription
member_idStringEntra object ID of the member (user, device, etc.)
device_idStringEntra 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_typeStringMicrosoft 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_id from a friendly group name.
  • Paginate to completion: call until has_next_page is false.
  • Branch on odata_type to detect member kind, not on device_id presence (#microsoft.graph.user vs. #microsoft.graph.device).
  • For large groups, raise page_size toward 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user

Example Input

{ "user_id": "adele.vance@contoso.com" }

Output

Field NameTypeDescription
userObjectThe user. See User object fields below.
User object fields
Field NameTypeDescription
user_idStringObject ID (GUID)
display_nameStringDisplay name
given_nameStringFirst name
surnameStringLast name
user_principal_nameStringUser principal name (sign-in name)
mailStringPrimary SMTP address
job_titleStringJob title
departmentStringDepartment
office_locationStringOffice location
mobile_phoneStringMobile phone number
business_phonesString[]Business phone numbers
account_enabledBooleantrue when the account can sign in
usage_locationStringTwo-letter country code. Required before a license can be assigned.
employee_idStringEmployee ID
company_nameStringCompany name
cityStringCity
countryStringCountry or region
created_date_timeDateTimeWhen 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

ParameterTypeRequiredDefaultDescription
filterStringNo-OData filter, for example department eq 'Sales' or accountEnabled eq false
searchStringNo-Text to look for in the display name
page_sizeIntegerNo100Number of users per page (1-999)

Example Input

{ "filter": "department eq 'Sales'", "search": "adele", "page_size": 50 }

Output

Field NameTypeDescription
odata_countIntegerTotal users that match
has_next_pageBooleantrue while more pages remain. Re-invoke the action until false.
usersObject[]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_page is false.
  • 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
display_nameStringNo-Display name
given_nameStringNo-First name
surnameStringNo-Last name
job_titleStringNo-Job title
departmentStringNo-Department
office_locationStringNo-Office location
company_nameStringNo-Company name (up to 64 characters)
employee_idStringNo-Employee ID (up to 16 characters)
employee_typeStringNo-Employee type, for example Employee or Contractor
mobile_phoneStringNo-Mobile phone number
business_phoneStringNo-Business phone number. Microsoft Entra keeps one.
cityStringNo-City
stateStringNo-State or province
countryStringNo-Country or region
street_addressStringNo-Street address
postal_codeStringNo-Postal code
usage_locationStringNo-Two-letter country code (ISO 3166). Required before a license can be assigned.
preferred_languageStringNo-Preferred language, for example en-US
user_principal_nameStringNo-New user principal name
mail_nicknameStringNo-Mail alias
account_enabledBooleanNo-false blocks sign-in, true allows it

Example Input

{ "user_id": "adele.vance@contoso.com", "job_title": "Sales Lead", "account_enabled": true }

Output

Field NameTypeDescription
user_idStringThe user that was updated, as given. After a rename of a user given by user principal name, the new user principal name
updated_fieldsString[]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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user

Example Input

{ "user_id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd" }

Output

Field NameTypeDescription
user_idStringThe user, as given
existedBooleanfalse 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user

Example Input

{ "user_id": "adele.vance@contoso.com" }

Output

Field NameTypeDescription
user_idStringObject ID of the user
assigned_licensesObject[]Every license the user holds, direct or from a group: sku_id and disabled_plans
license_assignment_statesObject[]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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
add_sku_idsString[]No-SKU IDs (GUIDs) of the licenses to add
disabled_plan_idsString[]No-Service plan IDs (GUIDs) to turn off in every license that is added
remove_sku_idsString[]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 NameTypeDescription
user_idStringObject ID of the user
added_sku_idsString[]The SKU IDs that were added
removed_sku_idsString[]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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user

Example Input

{ "user_id": "adele.vance@contoso.com" }

Output

Field NameTypeDescription
user_idStringThe user, as given
revokedBooleantrue 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

ParameterTypeRequiredDefaultDescription
display_nameStringYes-Display name
user_principal_nameStringYes-Sign-in name, alias@domain. The domain must be a verified domain of the tenant.
mail_nicknameStringYes-Mail alias
passwordSecret StringYes-First password. It must meet the password rules of the tenant.
force_change_password_next_sign_inBooleanNotruetrue makes the user choose a new password at the first sign-in
account_enabledBooleanNotruefalse creates the account with sign-in blocked
given_nameStringNo-First name
surnameStringNo-Last name
job_titleStringNo-Job title
departmentStringNo-Department
office_locationStringNo-Office location
company_nameStringNo-Company name (up to 64 characters)
employee_idStringNo-Employee ID (up to 16 characters)
employee_typeStringNo-Employee type, for example Employee or Contractor
cityStringNo-City
stateStringNo-State or province
countryStringNo-Country or region
street_addressStringNo-Street address
postal_codeStringNo-Postal code
usage_locationStringNo-Two-letter country code (ISO 3166). Required before a license can be assigned.
preferred_languageStringNo-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 NameTypeDescription
userObjectThe 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
manager_idStringYes-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 NameTypeDescription
user_idStringThe user, as given
manager_idStringObject 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) of the deleted user
new_user_principal_nameStringNo-New user principal name for the restored user, for example when another user now has the old one
auto_reconcile_proxy_conflictBooleanNofalsetrue 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 NameTypeDescription
userObjectThe 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_restoredBooleantrue 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_restored set to true and 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
passwordSecret StringYes-New password. It must meet the password rules of the tenant.
force_change_password_next_sign_inBooleanNotruetrue 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 NameTypeDescription
user_idStringThe user, as given
force_change_password_next_sign_inBooleantrue 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
lifetime_in_minutesIntegerNo-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_onceBooleanNo-true makes the pass work for one sign-in only
start_date_timeDateTimeNo-When the pass starts to work

Example Input

{ "user_id": "adele.vance@contoso.com", "lifetime_in_minutes": 60, "is_usable_once": true }

Output

Field NameTypeDescription
method_idStringID of the pass as an authentication method
temporary_access_passSecret StringThe passcode
start_date_timeDateTimeWhen the pass starts to work
lifetime_in_minutesIntegerHow long the pass works
is_usable_onceBooleantrue when the pass works for one sign-in only
is_usableBooleantrue when the pass can be used now
method_usability_reasonStringWhy the pass can or cannot be used now, for example NotYetValid
created_date_timeDateTimeWhen 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user

Example Input

{ "user_id": "adele.vance@contoso.com" }

Output

Field NameTypeDescription
methodsObject[]One object per method. See Method object fields below.
Method object fields
Field NameTypeDescription
method_idStringID of the method
odata_typeStringKind of method, for example #microsoft.graph.phoneAuthenticationMethod. Remove Entra user authentication method takes it as the method type.
display_nameStringName of the app, key or device, for Microsoft Authenticator, security keys and Windows Hello for Business
phone_numberStringPhone number, for a phone method
phone_typeStringmobile, alternateMobile or office, for a phone method
email_addressStringEmail 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) or user principal name of the user
method_idStringYes-method_id from List Entra user authentication methods
method_typeStringYes-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 NameTypeDescription
user_idStringThe user, as given
method_idStringID of the method
existedBooleanfalse 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.
  • existed is also false when 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
email_addressStringYes-Email address of the person to invite
redirect_urlStringYes-Address the person lands on after redeeming the invitation, for example https://myapps.microsoft.com
display_nameStringNo-Display name of the guest user
send_invitation_messageBooleanNofalsetrue 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 NameTypeDescription
invitation_idStringID of the invitation
user_idStringObject ID of the guest user that Microsoft created
invite_redeem_urlStringAddress the person uses to redeem the invitation
statusStringPendingAcceptance, Completed, InProgress or Error
invited_user_typeStringType 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

ParameterTypeRequiredDefaultDescription
display_nameStringYes-Group name (up to 256 characters)
mail_nicknameStringYes-Mail alias (up to 64 characters, no spaces or @ ( ) \ [ ] " ; : < > ,)
descriptionStringNo-Group description
group_typeStringNoSecuritySecurity or Microsoft 365
visibilityStringNo-Private, Public or HiddenMembership
owner_idsString[]No-Object IDs (GUIDs) of the owners
member_idsString[]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 NameTypeDescription
groupObjectThe new group. See Group object fields below.
Group object fields
Field NameTypeDescription
group_idStringObject ID (GUID)
display_nameStringGroup name
descriptionStringGroup description
mail_nicknameStringMail alias
mailStringEmail address, for a mail-enabled group
mail_enabledBooleantrue for a Microsoft 365 group
security_enabledBooleantrue for a security group
group_typesString[]Unified for a Microsoft 365 group, DynamicMembership for a dynamic group
visibilityStringPrivate, Public or HiddenMembership
is_assignable_to_roleBooleantrue 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_timeDateTimeWhen 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group
display_nameStringNo-Group name
descriptionStringNo-Group description
mail_nicknameStringNo-Mail alias
visibilityStringNo-Private, Public or HiddenMembership

Example Input

{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "description": "Members of Project Falcon" }

Output

Field NameTypeDescription
group_idStringObject ID of the group
updated_fieldsString[]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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group

Example Input

{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315" }

Output

Field NameTypeDescription
group_idStringObject ID of the group
existedBooleanfalse 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group

Example Input

{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315" }

Output

Field NameTypeDescription
groupObjectThe 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group
member_idStringYes-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 NameTypeDescription
group_idStringObject ID of the group
member_idStringObject ID of the member
already_memberBooleantrue 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group
member_idStringYes-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 NameTypeDescription
group_idStringObject ID of the group
member_idStringObject ID of the member
existedBooleanfalse 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group
owner_idStringYes-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 NameTypeDescription
group_idStringObject ID of the group
owner_idStringObject ID of the owner
already_ownerBooleantrue 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

ParameterTypeRequiredDefaultDescription
group_idStringYes-Object ID (GUID) of the group
member_typeStringNoAllAll, Users, Groups or Devices
searchStringNo-Text to look for in the display name
page_sizeIntegerNo100Number of members per page (1-999)

Example Input

{ "group_id": "02bd9fd6-8f93-4758-87c3-1fb73740a315", "member_type": "Users", "page_size": 200 }

Output

Field NameTypeDescription
odata_countIntegerTotal members that match
has_next_pageBooleantrue while more pages remain. Re-invoke the action until false.
membersObject[]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_page is false.
  • 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

ParameterTypeRequiredDefaultDescription
service_principal_idStringYes-Object ID (GUID) of the enterprise application (its service principal)
principal_idStringYes-Object ID (GUID) of the user, security group or service principal to assign
app_role_idStringNo00000000-0000-0000-0000-000000000000ID (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 NameTypeDescription
assignment_idStringID of the assignment. Remove Entra enterprise app assignment takes it.
app_role_idStringThe app role that was given
principal_idStringObject ID of the user, group or service principal
principal_typeStringUser, Group or ServicePrincipal
principal_display_nameStringName of the user, group or service principal
resource_idStringObject ID of the enterprise application
resource_display_nameStringName of the enterprise application
created_date_timeDateTimeWhen 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

ParameterTypeRequiredDefaultDescription
service_principal_idStringYes-Object ID (GUID) of the enterprise application (its service principal)
assignment_idStringYes-assignment_id from Assign Entra enterprise app to user

Example Input

{ "service_principal_id": "9028d19c-26a9-4809-8e3f-20ff73e2d75e", "assignment_id": "-WmtM5na7Uus0D8kI1yylpU9Mdo0Pb9OoBJvd3T5eKc" }

Output

Field NameTypeDescription
service_principal_idStringObject ID of the enterprise application
assignment_idStringID of the assignment
existedBooleanfalse 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
user_idStringYes-Object ID (GUID) of the user to assign
access_package_idStringYes-ID (GUID) of the access package
assignment_policy_idStringYes-ID (GUID) of the access package policy to assign under
justificationStringNo-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 NameTypeDescription
request_idStringID of the request
request_typeStringadminAdd
stateStringHow far the request got, for example submitted, delivering or delivered
statusStringMore 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 state can still be submitted when 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

ParameterTypeRequiredDefaultDescription
principal_idStringYes-Object ID (GUID) of the user, service principal or group
role_definition_idStringYes-ID (GUID) of the role: the role template ID or the role definition ID of the tenant
directory_scope_idStringNo/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 NameTypeDescription
assignment_idStringID of the assignment. Remove Entra directory role assignment takes it.
role_definition_idStringThe role
principal_idStringObject ID of the user, service principal or group
directory_scope_idStringWhere 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

ParameterTypeRequiredDefaultDescription
principal_idStringYes-Object ID (GUID) of the user, service principal or group
role_definition_idStringYes-ID (GUID) of the role: the role template ID or the role definition ID of the tenant
directory_scope_idStringNo/Where the role applies: / for the whole tenant, or /administrativeUnits/{id} for one administrative unit
justificationStringNo-Reason for the assignment. The role settings in PIM can require it.
start_date_timeDateTimeNo-When the eligibility starts. Empty means now.
end_date_timeDateTimeNo-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 NameTypeDescription
request_idStringID of the request
statusStringState of the request, for example Provisioned
principal_idStringObject ID of the user, service principal or group
role_definition_idStringThe role
directory_scope_idStringWhere the role applies
target_schedule_idStringID 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

ParameterTypeRequiredDefaultDescription
assignment_idStringYes-assignment_id from Assign Entra directory role

Example Input

{ "assignment_id": "lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1" }

Output

Field NameTypeDescription
assignment_idStringID of the assignment
existedBooleanfalse 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 existed is false and 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

ParameterTypeRequiredDefaultDescription
user_idsString[]Yes-Object IDs (GUIDs) of the users

Example Input

{ "user_ids": ["29f270bb-4d23-4f68-8a57-dc73dc0d4caf"] }

Output

Field NameTypeDescription
user_idsString[]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

ParameterTypeRequiredDefaultDescription
user_idsString[]Yes-Object IDs (GUIDs) of the users

Example Input

{ "user_ids": ["04487ee0-f4f6-4e7f-8999-facc5a30e232"] }

Output

Field NameTypeDescription
user_idsString[]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 NameTypeDescription
resultsObject[]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
createdIntegerSubscriptions created
renewedIntegerSubscriptions renewed
removedIntegerSubscriptions 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

ParameterTypeRequiredDefaultDescription
methodStringYesGETGET, POST, PATCH, PUT or DELETE
pathStringYes-Path after the Graph address, starting with /, for example /users/adele.vance@contoso.com/manager
queryObject[]No-Query parameters, each with name and value, for example $select = id,displayName
bodyStringNo-Request body as JSON
advanced_queryBooleanNofalseSends 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 NameTypeDescription
statusIntegerHTTP status of the answer
bodyStringBody 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, PATCH or PUT is 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 statusConnector behavior
429 Too Many RequestsWait 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 UnavailableRetry with backoff.
401 / 403Fail without retry. The message gives Microsoft's reason, such as a wrong credential, a missing permission or license, or a tenant setting.
400Fail without retry. Invalid input.

Notes:

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_page is false.
  • 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 methods of List Entra user authentication methods and pass each method_id and odata_type. Skip #microsoft.graph.passwordAuthenticationMethod and #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 when is_assignable_to_role is true. 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

Concepts

Setup