Skip to main content

Cyware Orchestrate

Microsoft Entra ID

App Vendor: Microsoft

App Category: Directory Service

Connector Version: 1.5.0

App Version in Orchestrate: 2.0.0

API version: 1.0.0

About App     

Microsoft Entra ID, formerly known as Azure Active Directory, is Microsoft's enterprise cloud-based identity and access management (IAM) solution. This app allows admins to manage users and control their access to ensure that the intended users have the correct level of access to the right resources. This helps organizations manage their users and resources, and perform orchestration workflows to respond to potential threats and improve overall efficiency.

The Azure AD app in the Orchestrate application performs the following actions:

Action

Description

Get Particular Risky User

This action retrieves the details of a particularly risky user.

List Risky Users

This action retrieves the list of all the risky users.

Get Direct Reports of A User

This action retrieves the direct reports of a user.

Assign Manager To A User

This action assigns a manager to a specific user.

Fetch Manager of a User

This action retrieves the manager details of a user.

List Owned Devices By A User

This action lists the devices owned by a user.

Revoke Session of a User

This action revokes a session of a user.

Fetch Newly Created Updated Deleted User

This action retrieves details of all the newly created, updated, and deleted users.

Delete User

This action deletes a user.

Update User

This action updates the details of a particular user.

Get User Details

The action retrieves details of a particular user.

List Users

The action retrieves the list of all the users.

List Groups

This action lists the groups in an organization.

Get Group Details

This action retrieves the properties and relationships of a group.

List Group Members

This action retrieves a list of the group's direct members.

Get Group Settings

This action retrieves the settings of a group.

Update Group Settings

This action updates the settings of a group.

Get Result From Next Link

This action retrieve the results from the next page link.

Get Sign-in Details

This action retrieves the details of a sign-in using the audit logs API.

List Sign-ins

This action retrieves a list of sign-ins using the audit logs API.

Configuration Parameters

The following configuration parameters are required for the Microsoft Entra ID app to communicate with the Microsoft Entra ID enterprise application. The parameters can be configured by creating instances in the app.

Parameter

Description

Field Type

Required/Optional

Comments

Tenant ID

Enter the tenant ID.

Text

Required

Client Secret

Enter the secret key of the client.

Password

Required

Client ID

Enter the GUID that was assigned to your client application during the registration, also known as an application ID.

Text

Required

Action: Get Particular Risky User

The action retrieves the details of a specific risky user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to retrieve the details of the user identified as risky.

Example:

018005a6-6592-4668-b879-acc2fb264160

Text

Required

You can retrieve the user ID of the risky user using the action List Risky Users.

Example Request

[
    {
        "userid": "018005a6-6592-4668-b879-acc2fb264160"
  
    }
]
Action: Get Direct Reports of a User

This action retrieves all the direct reports of a specified user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to retrieve direct reports of the user.

Example:

018005a6-6592-4668-b879-acc2fb264160

Text

Required

You can retrieve the User ID using the List Users action.

Example Request

[
    {
        "userid": "018005a6-6592-4668-b879-acc2fb264160"
  
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The context URL for the OData metadata. Example: "https://graph.microsoft.com/v1.0/$metadata#directoryObjects"

app_instance.value

Array

A list of directory objects. Each object contains user details.

app_instance.value.@odata.type

String

The type of directory object. Example: "#microsoft.graph.user"

app_instance.value.id

String

Unique identifier for the user. Example: "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"

app_instance.value.businessPhones

Array

List of business phone numbers for the user.

app_instance.value.displayName

String

Display name of the user. Example: "Conf Room Adams"

app_instance.value.givenName

String

Given name of the user.

app_instance.value.jobTitle

String

Job title of the user.

app_instance.value.mail

String

Email address of the user. Example: "Adams@contoso.com"

app_instance.value.mobilePhone

String

Mobile phone number of the user.

app_instance.value.officeLocation

String

Office location of the user.

app_instance.value.preferredLanguage

String

Preferred language of the user.

app_instance.value.surname

String

Surname of the user.

app_instance.value.userPrincipalName

String

User Principal Name (UPN) of the user. Example: "Adams@contoso.com"

Action: List Risky Users

This action retrieves the list of all risky users.

Action Input Parameters

Parameter

Description 

Field Type 

Required/Optional 

Comments 

Filters

Enter the filters to retrieve the list of users identified as risky.

Example:

filter=startsWith(displayName,'J')

Text

Optional

Example Request

[
    {
        "filters": "filter=startsWith(displayName,'J')"
    }
]
Action: Assign Manager to a User

This action assigns a manager to a specific user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to assign a manager to the user.

Example:

ea1f3fcf-b9cf-4da0-98f6-dc8b669d0692

Text

Required

You can retrieve the User ID using the List Users action.

Manager ID

Enter the manager ID.

Example:

c35a21fd-38dc-403d-94bd-7196c90df51c

Text

Required

Example Request

[
    {
        "userid": "ea1f3fcf-b9cf-4da0-98f6-dc8b669d0692",
        "manager_id": "c35a21fd-38dc-403d-94bd-7196c90df51c"
    }
]
Action: Fetch Manager of a User

This action retrieves the manager details of a user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to retrieve the manager details of a user.

Example:

ea1f3fcf-b9cf-4da0-98f6-dc8b669d0692

Text

Required

You can retrieve the User ID using the List Users action.

Example Request

[
    {
        "userid": "ea1f3fcf-b9cf-4da0-98f6-dc8b669d0692"
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.id

String

Unique identifier for the application instance. Example: "7d54cb02-aaa3-4016-9f9c-a4b49422dd9b"

app_instance.displayName

String

Display name of the user. Example: "Sara Davis"

app_instance.jobTitle

String

Job title of the user. Example: "Finance VP"

app_instance.mail

String

Email address of the user. Example: "SaraD@contoso.com"

app_instance.userPrincipalName

String

User Principal Name (UPN) of the user. Example: "SaraD@contoso.com"

Action: List Owned Devices by a User

This action lists the devices owned by a user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to list the devices owned by the user.

Example:

eb61a8b6-a72f-4024-a694-44a7f9e8b1e8

Text

Required

You can retrieve the User ID using the List Users action.

Example Request

[
    {
        "userid": "eb61a8b6-a72f-4024-a694-44a7f9e8b1e8"
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.value

Array

A list of objects containing IDs. Example: [{"id": "id-value"}]

app_instance.value.id

String

The unique identifier for each device. Example: "id-value"

Action: Revoke Session of a User

The action revokes a user session. It invalidates all the refresh tokens issued to applications for a user (as well as session cookies in a user's browser), by resetting the signInSessionsValidFromDateTime user property to the current date-time. Typically, this operation is performed (by the user or an administrator) if the user has a lost or stolen device. This operation prevents access to the organization's data through applications on the device by requiring the user to sign in again to all applications that they have previously consented to, independent of device.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to revoke a session for the user.

Example:

eb61a8b6-a72f-4024-a694-44a7f9e8b1e8

Text

Required

You can retrieve the User ID using the List Users action.

Example Request

[
    {
        "userid": "eb61a8b6-a72f-4024-a694-44a7f9e8b1e8"
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The OData context URL. Example: "https://graph.microsoft.com/v1.0/$metadata#Edm.Boolean"

app_instance.value

Boolean

The boolean value returned by the API. Example: true

Action: Fetch Newly Created Updated Deleted User

The action retrieves the details of the newly created, updated, and deleted users such as name, ID, email, and other contact details.

Action Input Parameters

This action does not require any input parameters.

Action: Delete User

This action deletes a specific user based on the user ID. When deleted, user resources are moved to a temporary container and can be restored within 30 days. After that time, they are permanently deleted. You must have the User.ReadWrite.All permission to delete users.

Action Input Parameters 

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to delete a user.

Example:

9797b127-13f2-4b0d-bfa0-446b3269b537

Text

Required

You can retrieve the User ID using the List Users action.

Example Request 

[
    {
        "userid": "9797b127-13f2-4b0d-bfa0-446b3269b537"
    }
]

Action Response Parameters

Parameter

Type

Description

HTTP/1.1 204 No Content

Status Code

Indicates that the request was successful but there is no content to send in the response.

Action: Update User

This action updates the user's details based on the user ID and the update fields.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the user ID to update the details of the user.

Example:

c514ef5a-4da0-487a-9a84-507b27d58742

Text

Required

You can retrieve the User ID using the List Users action.

Update User Dictionary

Enter the fields and the corresponding values to be updated for the user.

Example:

jobTitle:Manager

Key Value

Optional

Allowed fields for updating are aboutMe, accountEnabled, ageGroup, birthday, businessPhones, city, companyName, consentProvidedForMinor, country, customSecurityAttributes, department, displayName, employeeId, employeeType, givenName, employeeHireDate, employeeLeaveDateTime, employeeOrgData, interests, jobTitle, mail, mailNickname, mobilePhone, mySite, officeLocation, onPremisesExtensionAttributes, onPremisesImmutableId, otherMails, passwordPolicies, passwordProfile, pastProjects, postalCode, preferredLanguage, responsibilities, schools, skills, state, streetAddress, surname, usageLocation, userPrincipalName, and userType.

Example Request

[
    {
        "userid": "c514ef5a-4da0-487a-9a84-507b27d58742",
        "update_user": {
            "jobTitle": "Manager"
        }
    }
]

Action Response Parameters

Parameter

Type

Description

HTTP/1.1 204 No Content

Status Code

The server successfully processed the request, but is not returning any content.

Action: Get User Details

The action retrieves the details of a user.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

User ID

Enter the User ID or user principal name.

Examples:

  • 018005a6-6592-4668-b879-acc2fb264160

  • john@testdomain.com

Text

Required

You can retrieve the User ID using the List Users action.

Example Request

[
    {
        "userid": "john@testdomain.com"
    }
]

Action Input Parameters

Parameter

Type

Description

{app_instance} 

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.response 

Object

Contains a detailed response from the Microsoft Entra ID API.

app_instance.response.businessPhones 

Array

List the user's business phone numbers.

app_instance.response.displayName 

String

Display name of the user. Example: "John Doe".

app_instance.response.givenName 

String

Given name of the user. Example: "John".

app_instance.response.id 

String

Unique identifier of the user. Example: "857fa008-db40-4264-a1a2-953c43ca60a4".

app_instance.response.jobTitle 

String

Job title of the user. Example: Security Analyst.

app_instance.response.mail 

String

Email address of the user. Example: "johndoe@exampledomain.onmicrosoft.com".

app_instance.response.mobilePhone 

String

Mobile phone number of the user. Example: “+1 425 555 0109”

app_instance.response.officeLocation 

String

Office location of the user. Example: “18/2111”

app_instance.response.preferredLanguage 

String

Preferred language of the user. Example: “en-US”.

app_instance.response.surname 

String

Surname of the user. Example: “Doe”.

app_instance.response.userPrincipalName 

String

User principal name (UPN) of the user. Example: "johndoe@exampledomain.onmicrosoft.com".

app_instance.status_code 

Integer

HTTP status code of the response. Example: 200.

Action: List Users

The action retrieves the list of all the users.

Action Input Parameters

Parameter 

Description 

Field Type 

Required/Optional 

Comments 

Filter

Enter the filters to list users.

Example:

startswith(displayName, 'a')

Text

Optional

Limit

Enter a limit to set the page size of results.

Example:

1

Integer

Optional

Select

Enter select to filter properties of a user.

Example:

from,subject

Text

Optional

Orderby

Enter orderby to sort order of the items.

Example:

displayName

Text

Optional

Default value: asc

Example Request

[
    {
        "filters": "startswith(displayName, 'a')",
        "limit": 1,
        "select": "from,subject",
        "orderby": "displayName"
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The OData context URL. Example: https://graph.microsoft.com/v1.0/$metadata#users

app_instance.value

Array

A list of user objects.

app_instance.value.businessPhones

Array

List of business phone numbers.

app_instance.value.displayName

String

The display name of the user. Example: "Joe Adams"

app_instance.value.givenName

String

The given name (first name) of the user.

app_instance.value.jobTitle

String

The job title of the user. Example: null

app_instance.value.mail

String

The email address of the user. Example: "Adams@contoso.com"

app_instance.value.mobilePhone

String

The mobile phone number of the user.

app_instance.value.officeLocation

String

The office location of the user.

app_instance.value.preferredLanguage

String

The preferred language of the user.

app_instance.value.surname

String

The surname (last name) of the user.

app_instance.value.userPrincipalName

String

The user principal name (UPN) of the user. Example: "Adams@contoso.com"

app_instance.value.id

String

The unique identifier of the user. Example: "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"

Action: List Groups

This action lists the groups in an organization.

Action Input Parameters

Parameter 

Description 

Field Type 

Required/Optional 

Comments 

Filter

Enter the filter to list groups.

Example:

startswith(displayName, 'a')

Text

Optional

Limit

Enter a limit to set the page size of results.

Example:

1

Integer

Optional

Select

Enter select to filter properties of group.

Example:

from,subject

Text

Optional

Orderby

Enter the value to sort the order of items.

Example:

desc

Text

Optional

Allowed values:

  • asc

  • desc

Default value:

asc

Example Request

[
    {
        "filters": "startswith(displayName, 'a')",
        "limit": 1,
        "select": "from,subject",
        "orderby": "desc"
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The OData context URL. Example: "https://graph.microsoft.com/v1.0/$metadata#groups"

app_instance.value

Array

A list of group objects. Example: [{"id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4", "displayName": "Golf Assist", "mail": "golfassist@contoso.com"}]

app_instance.value.id

String

The unique identifier for the group. Example: "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4"

app_instance.value.deletedDateTime

DateTime

The date and time when the group was deleted.

app_instance.value.classification

String

The classification of the group.

app_instance.value.createdDateTime

DateTime

The date and time when the group was created. Example: "2018-12-22T02:21:05Z"

app_instance.value.description

String

The description of the group. Example: "Self help community for golf"

app_instance.value.displayName

String

The display name of the group. Example: "Golf Assist"

app_instance.value.expirationDateTime

DateTime

The date and time when the group will expire.

app_instance.value.groupTypes

Array

The group types. Example: ["Unified"]

app_instance.value.isAssignableToRole

Boolean

Indicates if the group can be assigned to a role.

app_instance.value.mail

String

The email address of the group. Example: "golfassist@contoso.com"

app_instance.value.mailEnabled

Boolean

Indicates if the group is mail-enabled. Example: true

app_instance.value.mailNickname

String

The mail nickname of the group. Example: "golfassist"

app_instance.value.membershipRule

String

The membership rule of the group.

app_instance.value.membershipRuleProcessingState

String

The membership rule processing state.

app_instance.value.onPremisesLastSyncDateTime

DateTime

The date and time of the last on-premises sync.

app_instance.value.onPremisesSecurityIdentifier

String

The on-premises security identifier.

app_instance.value.onPremisesSyncEnabled

Boolean

Indicates if on-premises sync is enabled.

app_instance.value.preferredDataLocation

String

The preferred data location. Example: "CAN"

app_instance.value.preferredLanguage

String

The preferred language.

app_instance.value.proxyAddresses

Array

The proxy addresses of the group. Example: ["smtp:golfassist@contoso.com", "SMTP:golfassist@contoso.com"]

app_instance.value.renewedDateTime

DateTime

The date and time when the group was last renewed. Example: "2018-12-22T02:21:05Z"

app_instance.value.resourceBehaviorOptions

Array

The resource behavior options.

app_instance.value.resourceProvisioningOptions

Array

The resource provisioning options.

app_instance.value.securityEnabled

Boolean

Indicates if the group is security-enabled. Example: false

app_instance.value.theme

String

The theme of the group.

app_instance.value.visibility

String

The visibility of the group. Example: "Public"

app_instance.value.onPremisesProvisioningErrors

Array

The on-premises provisioning errors.

Action: Get Group Details

This action retrieves the properties and relationships of a group object.

Input Parameters 

Parameters 

Description 

Field Type 

Required/Optional 

Comments 

Group ID

Enter the group ID to retrieve the group details.

Example:

8ff2a417-4d3f-44a5-94a3-1faf73515c01

Text

Required

Example Request  

[
    {
        "groupid": "8ff2a417-4d3f-44a5-94a3-1faf73515c01"    
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Group

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The OData context URL. Example: "https://graph.microsoft.com/v1.0/$metadata#groups"

app_instance.value

Array

A list of group objects. Example: [{"id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4", "displayName": "Golf Assist", "mail": "golfassist@contoso.com"}]

app_instance.value.id

String

The unique identifier for the group. Example: "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4"

app_instance.value.deletedDateTime

DateTime

The date and time when the group was deleted.

app_instance.value.classification

String

The classification of the group.

app_instance.value.createdDateTime

DateTime

The date and time when the group was created. Example: "2018-12-22T02:21:05Z"

app_instance.value.description

String

The description of the group. Example: "Self help community for golf"

app_instance.value.displayName

String

The display name of the group. Example: "Golf Assist"

app_instance.value.expirationDateTime

DateTime

The date and time when the group will expire.

app_instance.value.groupTypes

Array

The group types. Example: ["Unified"]

app_instance.value.isAssignableToRole

Boolean

Indicates if the group can be assigned to a role.

app_instance.value.mail

String

The email address of the group. Example: "golfassist@contoso.com"

app_instance.value.mailEnabled

Boolean

Indicates if the group is mail-enabled. Example: true

app_instance.value.mailNickname

String

The mail nickname of the group. Example: "golfassist"

app_instance.value.membershipRule

String

The membership rule of the group.

app_instance.value.membershipRuleProcessingState

String

The membership rule processing state.

app_instance.value.onPremisesLastSyncDateTime

DateTime

The date and time of the last on-premises sync.

app_instance.value.onPremisesSecurityIdentifier

String

The on-premises security identifier.

app_instance.value.onPremisesSyncEnabled

Boolean

Indicates if on-premises sync is enabled.

app_instance.value.preferredDataLocation

String

The preferred data location. Example: "CAN"

app_instance.value.preferredLanguage

String

The preferred language.

app_instance.value.proxyAddresses

Array

The proxy addresses of the group. Example: ["smtp:golfassist@contoso.com", "SMTP:golfassist@contoso.com"]

app_instance.value.renewedDateTime

DateTime

The date and time when the group was last renewed. Example: "2018-12-22T02:21:05Z"

app_instance.value.resourceBehaviorOptions

Array

The resource behavior options.

app_instance.value.resourceProvisioningOptions

Array

The resource provisioning options.

app_instance.value.securityEnabled

Boolean

Indicates if the group is security-enabled. Example: false

app_instance.value.theme

String

The theme of the group.

app_instance.value.visibility

String

The visibility of the group. Example: "Public"

app_instance.value.onPremisesProvisioningErrors

Array

The on-premises provisioning errors.

Action: List Group Members

This action lists the direct members of the group.

Action Input Parameters

Parameter 

Description 

Field Type 

Required/Optional 

Comments 

Group ID

Enter the group ID to get the group members.

Example:

8ff2a417-4d3f-44a5-94a3-1faf73515c01

Text

Required

Filter

Enter the filters to list group members.

Example:

startsWith(displayName,'J')

Text

Optional

Limit

Enter a limit to set the page size of results.

Example:

1

Integer

Optional

Example Request

[
    {
        "groupid": "8ff2a417-4d3f-44a5-94a3-1faf73515c01",
        "filters": "startsWith(displayName,'J')",
        "limit": 1
    }
]

Action Response Parameters

Parameter

Type

Description

{app_instance}

Object

This parameter indicates the ID of the app instance configured in Orchestrate from which the response is retrieved.

app_instance.@odata.context

String

The OData context URL. Example: "https://graph.microsoft.com/v1.0/$metadata#directoryObjects"

app_instance.value

Array

A list of directory object objects. Example: [{"id": "11111111-2222-3333-4444-555555555555", "mail": "user1@contoso.com"}]

app_instance.value.id

String

The unique identifier for the directory object. Example: "11111111-2222-3333-4444-555555555555"

app_instance.value.mail

String

The email address associated with the directory object. Example: "user1@contoso.com"

Action: Get Group Settings

This action retrieves the settings of a group.

Input Parameters 

Parameter 

Description 

Field Type 

Required/Option 

Comments 

Group ID

Enter the group ID to retrieve the group settings.

Example:

8ff2a417-4d3f-44a5-94a3-1faf73515c01

Text

Required

Example Parameters 

[
    {
        "groupid": "8ff2a417-4d3f-44a5-94a3-1faf73515c01"
    }
]
Action: Update Group Settings

This action updates the settings of a group.

Action Input Parameters

Parameter 

Description 

Field Type 

Required/Optional 

Comments 

Group ID

Enter the group ID to update the tenant-wide group settings.

Example:

8ff2a417-4d3f-44a5-94a3-1faf73515c01

Text

Required

Name

Enter the name of the setting.

Example:

AllowToAddGuests

Text

Required

Value

Enter the value of the setting to be updated.

Example:

sample value

Text

Required

Example Request

[
    {
        "text": "8ff2a417-4d3f-44a5-94a3-1faf73515c01",
        "name": "AllowToAddGuests",
        "value": "sample value"
    }
]
List Sign-ins

This action retrieves a list of sign-ins using the audit logs API.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

Filter

Enter the filters to apply in the search response.

Example:

userDisplayName eq ‘Isabella Simonsen’

Text

Optional

Limit

Enter the number of results to retrieve.

Example:

1000

Integer

Optional

Example Request

[
    {
        "filter": "userDisplayName eq 'Isabella Simonsen'",
        "top": 1000
    }
]
Get Sign-in Details

This action retrieves the details of a sign-in using the audit logs API.

Action Input Parameters

Parameter

Description

Field Type

Required/Optional

Comments

SignIn ID

Enter a sign-in ID.

Example:

8ff2a417-4d3f-44a5-94a3-1faf73515c01

Text

Required

You can retrieve the sign-in ID using the List Sign-ins action.

Example Request

[
    {
        "signin_id": "8ff2a417-4d3f-44a5-94a3-1faf73515c01"
    }
]