Microsoft Entra ID is a cloud-based identity and access management service to help users access internal and external resources.
D3 SOAR is providing REST operations to function with Microsoft Entra ID.
For example, Microsoft Entra ID is supporting restricted access to applications with Azure Multi-Factor Authentication (MFA) built-in, single sign-on (SSO), B2B collaboration controls, self-service password, and integration with Microsoft productivity and cloud storage (Office 365, OneDrive, etc) as well as 3rd party services.
Microsoft Entra ID v2.0 endpoint is not supported for cloud solution provider (CSP) apps. CSP apps must acquire tokens from the Microsoft Entra ID v1.0 endpoints to successfully call Microsoft Graph in their partner-managed customersD3 currently not using Microsoft Entra ID v2.0, but might have some commands being developed in the future. Please find more details on Microsoft Entra ID Known issues with the Microsoft Graph Applications page.
Microsoft Entra ID does not support creating a resource and open extension at the same time. You cannot specify an open extension at the same time you create an instance of administrativeUnit, device, group, organization or user. You must first create the instance and then specify the open extension data in a subsequent POST request on that instance. Please find more details on Microsoft Entra ID Known issues with the Microsoft Graph Extensions page.
Microsoft Entra ID has a limit of 100 schema extension property values allowed per resource instance. Please find more details on Microsoft Entra ID Known issues with the Microsoft Graph Extensions page.
To connect to Microsoft Entra ID from D3 SOAR, please follow this part to collect the required information below:
Parameter
Description
Example
Default
Tenant ID
The tenant ID to authenticate the API connection.
f62-***-***-***-kY8
Grant Type
The grant type to authentication method. If you select Authorization Code, you will only be able to access the signed-in user's mailbox. If you need to access any other user's email box in the organization, you must select Client Credentials.
Client Credentials
API Version
The version of the API to use for the connection.
v1.0
Grant Type: Client Credentials
Client ID
The client ID to authenticate the API connection.
9c8*************f8a
Client Secret
The client secret to authenticate the API connection.
o14*************817
Grant Type: Authorization Code
Client ID
The client ID to authenticate the API connection.
9sL*************B12
Client Secret
The client secret to authenticate the API connection.
Hl2**************J1a
Authentication Code
The authorization code used for the OAuth2.0 authorization code grant type. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.
2kP*************gAA
Callback URL
The callback URL is used for OAuth2.0 with the grant type of authorization code. Add this URL to your app's Redirect URIs. In the Azure portal, navigate to Microsoft Entra ID > App Registrations > Your App > Authentication.
https://***/***Callback.aspx
Refresh Token
The refresh token for authentication with the grant type of authorization code. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token.
This parameter is read-only and auto-generated.
0.AX************5Yg
Permission Requirements
Each endpoint in the Microsoft Entra ID API requires a certain permission scope.
Ensure your user account used to assign permissions have assigned properroles. For instructions, refer to Assign Microsoft Entra roles to users from Microsoft's documentation.
Due to Microsoft's frequent updates on the necessary permissions for each API endpoint, refer to the API documentation linked in the API reference column of the table below, corresponding to the command you intend to use. Within these documents, refer to the Permissions section, and ensure that the Least privileged permissions specified for the required API endpoints are enabled. Please note that multiple API permissions are required for some commands.
Reader Note
If you selected Authorization Code as the Grant Type, corresponding Delegated permissions are required to execute commands.
If you selected Client Credentials as the Grant Type, configure the required Application permissions instead.
Command
Permission
Roles
API Reference
Add Group Device
Delegated
Group.ReadWrite.All
Delegated
The calling user must have at least the Groups Admin role assigned.
The calling user must have at least the User Administrator role.
To delete users with privileged administrator roles in delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission, and the calling user must have a higher privileged administrator role. For users with additional roles, refer to the Privileged Role Permissions Matrix.
To enable/disable non-admin users, the acting user must have at least the Authentication Administrator role. For users with additional roles, refer to the Privileged Role Permissions Matrix.
Global Administrators with Directory.AccessAsUser.All permission can update sensitive user properties for all tenant administrators.
To enable/disable non-admin users, the calling user must have at least the Authentication Administrator role. For users with additional roles, refer to the Privileged Role Permissions Matrix.
Global Administrators with Directory.AccessAsUser.All permission can update sensitive user properties for all tenant administrators.
The command cannot be used with a connector authenticated through the Client Credentials grant type.
To run this command, an administrator must have either the Authentication Administrator or Privileged Authentication Administrator role in Microsoft Entra. Additionally, Admins with User Administrator, Helpdesk Administrator, or Password Administrator roles can reset passwords for non-admin users and certain admin roles as outlined in the Administrative Roles and Password Reset Permissions Table.
In the following table, the columns list the roles that can perform sensitive actions. The rows list the roles for which the sensitive action can be performed upon.
The following table is for roles assigned at the scope of a tenant. For roles assigned at the scope of an administrative unit, further restrictions apply.
Administrative Roles and Password Reset Permissions Table
In the following table, the columns list the roles that can reset passwords and invalidate refresh tokens. The rows list the roles for which their password can be reset. For example, a Password Administrator can reset the password for Directory Readers, Guest Inviter, Password Administrator, and users with no administrator role. If a user is assigned any other role, the Password Administrator cannot reset their password.
The following table is for roles assigned at the scope of a tenant. For roles assigned at the scope of an administrative unit, further restrictions apply.
Administrative Roles and Revoke Sign-In Session Permissions Table
In the following table, the columns list the roles that can revoke user sign-in sessions. The rows list the roles for which their sign-in sessions can be reset. For example, a Password Administrator can reset the password for users with no administrator role, Guest Inviter, Helpdesk Admin, Reports Reader, Password Admin, and their own account. If a user is assigned any other role, the Password Administrator cannot reset their password.
The following table is for roles assigned at the scope of a tenant.
Role that sign-in session can be revoked from
User
Password Admin
Helpdesk Admin
Security Admin
Auth Admin
User Admin
Privileged Auth Admin
Global Admin
User (no admin role)
✅
✅
✅
✅
✅
Auth Admin
✅
✅
✅
User Admin
✅
✅
✅
Groups Admin
✅
✅
✅
Privileged Auth Admin
✅
✅
Privileged Role Admin
✅
✅
Global Admin
✅
✅
Guest Inviter
✅
✅
✅
✅
✅
Helpdesk Admin
✅
✅
✅
✅
Reports Reader
✅
✅
✅
✅
✅
Global Reader
✅
✅
Security Admin
✅
✅
Password Admin
✅
✅
✅
✅
✅
Self
✅
✅
✅
✅
✅
✅
✅
✅
Configuring Microsoft Entra ID to Work with D3 SOAR
Navigate to the search bar at top and search "App registrations", then click App Registrations.
If you have already created Apps, you can use one of them and skip to step 6 to obtain the Client ID & Tenant ID.
If you do not have an App, click + New registration at the top left corner to create a new App.
Enter an App name. Choose the first option as your Supported account type if your target audience is internal within your organization. For a more detailed description of different options, you can click Help me choose…, then select Web from the Redirect URI dropdown list and paste the Callback URI you copied from the SOAR connection window into the URI field. Finally, click Register. Note: To copy the Callback URI from SOAR Connection Window, please refer to step 3h iv of Configuring D3 SOAR to Work with Microsoft Entra ID.
a. You can also add a redirect URI later. Click Overview on the navigation column, then click Add aRedirect URI.
b. Click Add Platform, then select Web.
c. Input your Redirect URIs and click Configure.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID for creating the SOAR connection.
Click Certificates & secrets on the left navigation column, then click + New client secret. Enter a descriptionfor the client secret, and select the client secret expiry period from the Expires dropdown menu. Please note that the client ID cannot access API resources if the client secret is expired. You MUST renew the client secret to keep the client ID effective. Click Add at the bottom.
Copy and save the Secret Value for the SOAR connection. Please note that you will only be able to view this Secret Value once after its initial creation. Store it in a secure location.
Configure the API permissions. Click API permissions on the left navigation column, then click + Add a permission. Click Microsoft Graph under the Microsoft APIs tab.
Select Delegated Permissions if you want to use the OAuth2 Authentication Code method. If you want to use the OAuth2 Client Credentials method, select Application permissions. For the Report Emails command, which will report an email as either spam or phishing, the permission must be the Delegated Permissions for the account.
Search for the permissions you need by using the search bar. Select your desired permissions, and choose Add permission.
Some permissions may need to be granted admin consent. Please check Grant admin consent for D3DevCyber to grant the API permissions. Ask your admin to grant consent if you do not have admin privileges.
Click Grant admin consent for D3DevCyber, then click Yes.
You will see a green checkmark under status. The permission is now successfully granted.
Configuring D3 SOAR to Work with Microsoft Entra ID
Log in to D3 SOAR.
Find the Microsoft Entra ID integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Microsoft Entra ID in the search box to find the integration, then click it to select it.
Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Entra ID.
Connection Name: The desired name for the connection.
Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
Description (Optional): Add your desired description for the connection.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
Click the Get Authorization button. You will be directed to the Microsoft Entra ID login page. Enter your email address and password. You will then see the page below:
Go back to D3 SOAR Connection window, click Get Refresh Token, and the hidden refresh token will be automatically pasted into the Refresh Token field.
The default API Version is v1.0. Please change the API Version based on your need. Note: The API version field has a default value of v1.0, which can be used for most D3 commands. Only the Reset Password command requires the beta API version. Choosing an incorrect API version will result in no found connection when running commands.
Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active. To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmarkappear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
Click OK to close the alert window.
Click +Add to create and add the configured connection.
Commands
Microsoft Entra ID includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.
List Devices command requires structured input arguments in Microsoft Entra ID designed query formats.
You should take either query parameter ($filter) for the search criteria depending on the use case.
$filter: Filter results based on defined operators, Microsoft Entra ID directory objects and their relationships.
Note for Time-related parameters
The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
Add Group Devices
Adds devices to a specified group. Note: Up to 20 devices can be added in a single request.
Reader Note
Group ID and Device IDs are required parametersto run this command.
Run the Get Group command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.value[*].id.
Run the List Devices command to obtain Device IDs. Device IDs can be found in the returned raw data at the path $.value[*].id.
Please note that the same device cannot be added twice to the group. Please make sure your input Devices are not in your input group. Otherwise, an error will be returned.
When you run the List Devices command, please note that the Device IDs in the request are the "id" property of the device, not the "deviceId" property in the returned Raw data. The "deviceId" in Key Fields corresponds to the value of "id", which can be used directly. An error will be returned if you use the wrong "deviceId".
Input
Input Parameter
Required /Optional
Description
Example
Group ID
Required
The ID of the group to add devices. Group IDs can be obtained using the List Groups command.
****************
Device IDs
Required
The IDs of the devices to add to the group. Devices IDs can be obtained using the List Devices command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Add Group Device failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid object identifier.
Error Sample Data
Add Group Device failed.
Status Code: 400.
Message: Invalid object identifier.
Add Group Members
Adds users to a specified group. Note: Up to 20 members can be added in a single request.
Reader Note
Group ID and User IDs are required parametersto run this command.
Run the List Groups command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.value[*].id.
Run the List Users command to obtain User IDs. User IDs can be found in the returned raw data at the path $.value[*].id.
Input
Input Parameter
Required /Optional
Description
Example
Group ID
Required
The ID of the group to add members. Group IDs can be obtained using the List Groups command.
**********************
User IDs
Required
The IDs of the users to add to the group. User IDs can be obtained using the List Users command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.TYPE
ID
BUSINESSPHONES
DISPLAYNAME
GIVENNAME
JOBTITLE
MAIL
MOBILEPHONE
OFFICELOCATION
PREFERREDLANGUAGE
SURNAME
USERPRINCIPALNAME
#microsoft.graph.user
***************************************
[]
D3 Support
D3
None
*****@*****.com
None
None
None
Support
*****@*****.com
#microsoft.graph.user
***************************************
[]
*****
None
None
None
None
None
None
None
*****@*****.com
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Add Group Member failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist.
Error Sample Data
Add Group Member failed.
Status Code: 404.
Message: Resource does not exist.
Create User
Creates a new user. The request body contains the user to create. At a minimum, you must specify the required properties for the user.
Reader Note
Please note that you must input a verified domain name in your organization for the User Principal Name field.
Input
Input Parameter
Required /Optional
Description
Example
Account Enabled
Required
The option to enable the created user account. Selecting True will enable the account.
True
Display Name
Required
The name to display in the address book for the user.
*****
Force Change Password Next Sign In
Optional
If set to true, the user must change their password upon the next login. If this field is left empty, the default value will be false.
False
Mail Nickname
Required
The mail alias for the user. If this field is not specified, the email name in the User Principal Name parameter will be used as Mail Nickname.
Doraemon
Password
Required
The password for the user account. This is a required field for creating a new user account. The password can be updated, but the user will be required to change their password upon the next login. The password must satisfy minimum requirements as specified by the user's passwordPolicies property. By default, a strong password is required.
P@ssw0rd
User Principal Name
Required
The user principal name (someuser@contoso.com). The user principal name follows the Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"userPrincipalName": "*****@*****.com"
}
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://graph.microsoft.com/v1*.*/***
id
***************************************
businessPhones
[]
displayName
*****
givenName
None
jobTitle
None
mail
None
mobilePhone
None
officeLocation
None
preferredLanguage
None
surname
None
userPrincipalName
*****@*****.com
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Create User failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Another object with the same value for property userPrincipalName already exists.
Error Sample Data
Create User failed.
Status Code: 400.
Message: Another object with the same value for property userPrincipalName already exists.
Delete Users
Deletes the specified user(s). When a user is deleted, the user resources are moved to a temporary container and can be restored within 30 days. After 30 days, the user resources are permanently deleted.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principle Names of the users to delete. User IDs and Principal Names can be obtained using the List Users command.
[ "*****@*****.com"]
Output
Raw Data
The primary response data from the API request.
SAMPLE DATA
JSON
[
{
"idOrPrincipalName": "*****@*****.com",
"actionResult": "Delete user successfully"
}
]
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
SAMPLE DATA
CODE
{
"UserPrincipalNames": [
"*****@*****.com"
]
}
Return Data
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
IDORPRINCIPALNAME
ACTIONRESULT
*****@*****.com
Delete user successfully
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Delete User failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Delete User failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Disable User
Disables the specified user accounts.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
To update sensitive user properties, such as accountEnabled, mobilePhone, and otherMails for users with privileged administrator roles:
In delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission and the calling user must have a higher privileged administrator role as indicated in the Privileged Role Permissions Matrix.
In app-only scenarios, the app must be assigned a higher privileged administrator role as indicated in the Privileged Role Permissions Matrix.
Your personal Microsoft account must be tied to a Microsoft Entra tenant to update your profile with the User.ReadWrite delegated permission on a personal Microsoft account.
Updating the identities property requires the User.Manageldentities.All permission. Also, adding a B2C local account to an existing user object is not allowed, unless the user object already contains a local account identity.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principle Names of the users to disable. User IDs and Principal Names can be obtained using the List Users command.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
USERPRINCIPALNAME
DISPLAYNAME
ID
ACCOUNTENABLED
https://graph.microsoft.com/v*.*/***
*****@*****.com
*****1
**************************************
False
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Disable User failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Error Sample Data
Disable User failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Enable Users
Enables the specified user accounts.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
To update sensitive user properties, such as accountEnabled, mobilePhone, and otherMails for users with privileged administrator roles:
In delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission and the calling user must have a higher privileged administrator role as indicated in the Privileged Role Permissions Matrix.
In app-only scenarios, the app must be assigned a higher privileged administrator role as indicated in the Privileged Role Permissions Matrix.
Your personal Microsoft account must be tied to a Microsoft Entra tenant to update your profile with the User.ReadWrite delegated permission on a personal Microsoft account.
Updating the identities property requires the User.Manageldentities.All permission. Also, adding a B2C local account to an existing user object is not allowed, unless the user object already contains a local account identity.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principle Names of the users to enable. User IDs and Principal Names can be obtained using the List Users command.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
USERPRINCIPALNAME
DISPLAYNAME
ID
ACCOUNTENABLED
https://graph.microsoft.com/v*.*/***
*****@*****.com
*****1
***************************************
True
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Enable User failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Error Sample Data
Enable User failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Get Device
Retrieves details of the specified device(s).
Reader Note
The parameter IDs or Device Names is required to run this command.
Run the List Devices command to obtain IDs or Device Names. Device IDs can be found in the returned raw data at the path $.value[*].id. Device Names can be found in the returned raw data at the path $.value[*].displayName.
When you run the List Devices command, please note that the IDs or Device Names in the request are the "id" property of the device, not the "deviceId" property in the returned Raw data. The "deviceId" in Key Fields corresponds to the value of "id", which can be used directly. An error will be returned if you use the wrong "deviceId".
Input
Input Parameter
Required /Optional
Description
Example
IDs or Device Names
Required
The IDs or names of the devices to retrieve details. IDs and device names can be obtained using the List Devices command. Note: The "id" in the request is the "id" property of the device, not the "deviceId" property.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Device failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: '***************************************' is not found.
Error Sample Data
Get Device failed.
Status Code: 404.
Message: '***************************************' is not found.
Get Device Locations
Retrieves the latest locations of devices since the specified sign in time to Microsoft Entra ID.
Reader Note
The parameter Device Names is required to run this command.
Run the List Devices command to obtain Device Names. Device Names can be found in the returned raw data at the path $.value[*].displayName.
Input
Input Parameter
Required /Optional
Description
Example
Device Names
Required
The names of the devices to search for sign-in logs. Device Names can be obtained using the List Devices command.
[ "*****" ]
Sign In Since
Required
The start time to filter the returned sign-in logs.
The data extracted from Raw Data is converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Device Locations failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Device is not found.
Error Sample Data
Get Device Locations failed.
Status Code: 404.
Message: Device is not found.
Get Groups
Retrieves the properties and relationships of the specified groups.
Reader Note
The parameter IDs Or Group Names is required to run this command.
Run the List Groups command to obtain IDs Or Group Names. Group IDs can be found in the returned raw data at the path $.value[*].id. Group Names can be found in the returned raw data at the path $.value[*].displayName.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Group Names
Required
The IDs or names of the groups to retrieve details. Group IDs and Group Names can be obtained using the List Groups command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Group failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Get Group failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Get Users
Retrieves the properties and relationships of user object(s).
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Select is an optional parameter to run this command.
The available properties you can select are businessPhones, displayName, givenName, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName, and id.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principal Names of the users to retrieve details. User IDs and Principal Names can be obtained using the List Users command.
[
"*****@*****.com", "************"
]
Select
Optional
The option to filter the returned user properties (columns). If this parameter is not defined, only the default properties will be returned. Non-default properties must be defined to be included in the returned results. The available properties are: businessPhones, displayName, givenName, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName, id. Please refer to user resource type - Microsoft Graph v1.0 for available properties.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
BUSINESSPHONES
DISPLAYNAME
GIVENNAME
JOBTITLE
MAIL
MOBILEPHONE
OFFICELOCATION
PREFERREDLANGUAGE
SURNAME
USERPRINCIPALNAME
ID
https://graph.microsoft.com/v1*.*/***
[]
D3 Support
D3
None
*****@*****.com
None
None
None
Support
*****@*****.com
***************************************
https://graph.microsoft.com/v1*.*/***
[]
Arpan Dadwal
None
None
None
None
None
None
None
*****@*****.com
************
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get Users failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Error Sample Data
Get Users failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects are not present.
Get User Activity Logs
Retrieves the audit logs of a specified Azure user. By default, the most recent audit logs are returned first. Only audit log that occurred within the Azure Active Directory (Azure AD) default retention period are available. For default Audit Log retention period, please check Microsoft Entra data retention - Microsoft Entra ID | Microsoft Learn.
Reader Note
The parameter User IDs Or User Principal Names is required to run this command.
Run the List Users command to obtain User IDs Or User Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
User ID or User Principal Name
Required
The User ID or Principal Name of the user to retrieve activity logs. User IDs and Principal Names can be obtained using the List Users command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get User Activity Logs failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: The user does not exist.
Error Sample Data
Get User Activity Logs failed.
Status Code: 404.
Message: The user does not exist.
Get User Groups
Retrieves groups, directory roles, and administrative units that the specified user(s) are direct members of.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principal Names of the users to retrieve group information. User IDs and Principal Names can be obtained using the List Users command.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get User Groups failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Get User Groups failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Get User Manager
Returns the user or organizational contact assigned as the user's direct reporting manager. If you want to get the specified users' manager chains up to the root node, use the Get User Manager Chain command.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principal Names of the users to retrieve manager chains. User IDs and Principal Names can be obtained using the List Users command.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get User Manager failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Get User Manager failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Get User Manager Chain
Returns the specified users' manager chains up to the root node.
Reader Note
The parameter IDs Or Principal Names is required to run this command.
Run the List Users command to obtain IDs Or Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
IDs Or Principal Names
Required
The IDs or Principal Names of the users to get manager chains. User IDs and Principal Names can be obtained using the List Users command.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Get User Manager Chain failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: IDs Or Principal Names does not exist or one of its queried reference-property objects are not present.
Error Sample Data
Get User Manager Chain failed.
Status Code: 404.
Message: IDs Or Principal Names does not exist or one of its queried reference-property objects are not present.
List Device Groups
Lists groups and administrative units that the specified device is a direct member of.
Reader Note
ID is a required parameterto run this command.
Run the List Devices command to obtain ID. Device IDs can be found in the returned raw data at the path $.value[*].id.
When you run the List Devices command, please note that the ID in the request is the "id" property of the device, not the "deviceId" property in the returned Raw data. The "deviceId" in Key Fields corresponds to the value of "id", which can be used directly. An error will be returned if you use the wrong "deviceId".
Input
Input Parameter
Required /Optional
Description
Example
ID
Required
The ID of the device to list groups that it is a member of. Device IDs can be obtained using the List Devices command. Note: The "id" in the request is the "id" property of the device, not the "deviceId" property.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
CODE
No Sample Data
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List Device Groups failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: The device is not found.
Error Sample Data
List Device Groups failed.
Status Code: 404.
Message: The device is not found.
List Devices
Retrieves a list of device objects registered in the organization.
Reader Note
It is recommended to define the Top parameter. Otherwise, the command will run successfully with no results returned.
Filter is an optional parameter to run this command.
You should already have your desired search property on hand to run this command. If you do not know what the searchable properties are, you may run this command with only the Top parameter defined. The returned values under the $.[*].value path in the raw data are all valid properties to filter. Note: "Value-to match" cannot be null.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List Devices failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid page size specified: '1000'. Must be between 1 and 999 inclusive.
Error Sample Data
List Devices failed.
Status Code: 400.
Message: Invalid page size specified: '1000'. Must be between 1 and 999 inclusive.
List Group Members
Retrieves a list of the specified group's direct members. A group can have users, organizational contacts, devices, service principals and other groups as members.
Reader Note
Group ID is a required parameterto run this command.
Run the List Groups command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.value[*].id.
Please note that if your input for the Group Member Type parameter is empty in Microsoft Entra ID (e.g., Group Member Type=Device but no device in the input group), D3 SOAR will run the command successfully with no return data. If you leave the Group Member Type parameter empty, all member types will be listed.
Input
Input Parameter
Required /Optional
Description
Example
Group ID
Required
The IDs of the groups to retrieve group members. Group IDs can be obtained using the List Groups command.
****************
Group Member Type
Optional
The group member type to filter returned results. All member types will be returned by default.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
DELETEDDATETIME
CLASSIFICATION
CREATEDDATETIME
CREATIONOPTIONS
DESCRIPTION
DISPLAYNAME
EXPIRATIONDATETIME
GROUPTYPES
ISASSIGNABLETOROLE
MAIL
MAILENABLED
MAILNICKNAME
MEMBERSHIPRULE
MEMBERSHIPRULEPROCESSINGSTATE
ONPREMISESDOMAINNAME
ONPREMISESLASTSYNCDATETIME
ONPREMISESNETBIOSNAME
ONPREMISESSAMACCOUNTNAME
ONPREMISESSECURITYIDENTIFIER
ONPREMISESSYNCENABLED
PREFERREDDATALOCATION
PREFERREDLANGUAGE
PROXYADDRESSES
RENEWEDDATETIME
RESOURCEBEHAVIOROPTIONS
RESOURCEPROVISIONINGOPTIONS
SECURITYENABLED
SECURITYIDENTIFIER
THEME
VISIBILITY
ONPREMISESPROVISIONINGERRORS
***************************************
None
None
2021-06-02T06:46:13Z
[]
None
*****
None
[]
None
None
False
*****
None
None
*****.*****
2021-06-02T06:46:13Z
*****
*****
***************************************
True
None
None
[]
2021-06-02T06:46:13Z
[]
[]
True
***************************************
None
None
[]
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List Group Members failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid Group ID.
Error Sample Data
List Group Members failed.
Status Code: 400.
Message: Invalid Group ID.
List Groups
Retrieves a list of groups in the organization. The group list is sorted by group display name in ascending order.
Reader Note
Select is an optional parameter to run this command.
The available properties you can select are id, deletedDateTime, classification, createdDateTime, creationOptions, description, displayName, expirationDateTime, groupTypes, isAssignableToRole, mail, mailEnabled, mailNickname, membershipRule, membershipRuleProcessingState, onPremisesDomainName, onPremisesLastSyncDateTime, onPremisesNetBiosName, onPremisesSamAccountName, onPremisesSecurityIdentifier, onPremisesSyncEnabled, preferredDataLocation, preferredLanguage, proxyAddresses, renewedDateTime, resourceBehaviorOptions, resourceProvisioningOptions, securityEnabled, securityIdentifier, theme, visibility, onPremisesProvisioningErrors.
If you enter a value in the Select parameter, all other properties except your input will be ignored. Key Fields might return null for "GroupDisplayNames" and "GroupIDs" depending on your input.
Input
Input Parameter
Required /Optional
Description
Example
Select
Optional
The option to filter the returned user properties (columns). If this parameter is not defined, only the default properties will be returned. Non-default properties must be defined to be included in the returned results.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
BUSINESSPHONES
DISPLAYNAME
GIVENNAME
JOBTITLE
MAIL
MOBILEPHONE
OFFICELOCATION
PREFERREDLANGUAGE
SURNAME
USERPRINCIPALNAME
ID
[]
Azure Container
None
None
None
None
None
None
None
*****@*****.com
***************************************
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List Groups failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Access is denied to the requested resource. The user might not have enough permission.
Error Sample Data
List Groups failed.
Status Code: 403.
Message: Access is denied to the requested resource. The user might not have enough permission.
List User Registration Details
Returns a list of users' registration details. The list contains details on the activity of self-service password resets and multi-factor authentication (MFA) for all registered users. Details include user information, status of registration, and the authentication method used. Please note, the credential user registration details API is deprecated and will stop returning data on June 30, 2024. Use List User Registration Details v1 instead.
Reader Note
An API connection built with the Microsoft Entra ID's beta API version is required to use this command. See step 3h 1c and 2f of Configuring D3 SOAR to Work with Microsoft Entra ID for instructions to set up an API connection.
Input
Input Parameter
Required /Optional
Description
Example
Filters
Optional
The argument to filter the list of user registration details. The following properties can be used for filtering: userDisplayName, userPrincipalName, authMethods, isRegistered, isEnabled, isCapable, isMfaRegistered. For userDisplayName and userPrincipalName, the supported filter operators are eq and startswith() (e.g. userDisplayName eq 'Contoso'). For all other properties, eq is the only supported operator. All the properties can be logically joined using the logical operators "and" and "or". See List credentialUserRegistrationDetails from Microsoft's documentation for more information.
authMethods/any(t:t eq microsoft.graph.registrationAuthMethod'email') or userPrincipalName eq 'user@d3soar.com'and isRegistered eq true and isEnabled eq true and isCapable eq true and isMfaRegistered eq true
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List User Registration Details failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Invalid filter clause.
Error Sample Data
List User Registration Details failed.
Status Code: 400.
Message: Invalid filter clause.
List Users
Retrieves a list of user objects. The user list is sorted by user display name in ascending order.
Reader Note
Select is an optional parameter to run this command.
The available properties you can select are businessPhones, displayName, givenName, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName, and id.
If you enter value in the Select parameter, all other properties except your input will be ignored. Key Fields might return null to "userPrincipalName" depending on your input.
Input
Input Parameter
Required /Optional
Description
Example
Select
Optional
Filters user properties (columns) to be returned. If not specified, the default properties will be returned. Specify this parameter to return properties that are not default besides the default properties. For available properties, please refer to https://*****.com/***.
userPrincipalName, displayName, id
User Name
Optional
The whole partial user name to filter results. If this parameter is not defined, all groups in the organization will be returned.
doraemon
Search Condition
Optional
The additional search condition for the users. This parameter will join the given user name with the "OR" operator if the parameter "User Name" has a value. Each field and value pair must be quoted with double quotation marks. If not specified, all users in the organization will be returned.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
BUSINESSPHONES
DISPLAYNAME
GIVENNAME
JOBTITLE
MAIL
MOBILEPHONE
OFFICELOCATION
PREFERREDLANGUAGE
SURNAME
USERPRINCIPALNAME
ID
[]
Azure Container
None
None
None
None
None
None
None
*****@*****.com
***************************************
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
List Users failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Get Token Fail, reason: unauthorized_client.
Error Sample Data
List Users failed.
Status Code: 400.
Message: Get Token Fail, reason: unauthorized_client.
Remove Group Devices
Removes devices from a specified security group.
Reader Note
Group ID and Device IDs are required parametersto run this command.
Run the List Groups command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.value[*].id.
Run the List Group Member or List Devices command to obtain Device IDs. Device IDs can be found in the returned raw data at the path $.value[*].id.
Ensure that the input user is part of your input group. Begin by running the List Groups command to identify your preferred group. Next, enter the chosen group's ID in the List Group Members command and set the "Group Member Type" to "Group". From the listed members, locate the user you need. Finally, use the selected group-user pair to run this command.
Please note that the same device cannot be removed twice from the group. Please make sure your input Devices are not in your input group. Otherwise, an error will be returned.
When you run the List Devices command, please note that the Device IDs in the request are the "id" property of the device, not the "deviceId" property in the returned Raw data. The "deviceId" in Key Fields corresponds to the value of "id", which can be used directly. An error will be returned if you use the wrong "deviceId".
Input
Input Parameter
Required /Optional
Description
Example
Group ID
Required
The ID of the security group to remove device members. Group IDs can be obtained using the List Groups command.
****************
Device IDs
Required
The IDs of the devices to remove from the specified group. Device IDs can be obtained using the List Group Member or List Devices command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 enriches the context data from the original Azure Active Directory API response by adding the deviceid field to indicate your input device ids, and adding actionResult field to indicate whether the device has been successfully removed.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
ID
ACTIONRESULT
***************************************
remove device successfully
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Remove Group Device failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Remove Group Device failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Remove Group Members
Removes users from a specified group.
Reader Note
Group ID and User IDs are required parametersto run this command.
Run the List Groups command to obtain Group ID. Group IDs can be found in the returned raw data at the path $.value[*].id.
Run the List Group Members or List Users command to obtain User IDs. User IDs can be found in the returned raw data at the path $.value[*].id.
Ensure that the input user is part of your input group. Begin by running the List Groups command to identify your preferred group. Next, enter the chosen group's ID in the List Group Members command and set the "Group Member Type" to "User". From the listed members, locate the user you need. Finally, use the selected group-user pair to run this command.
Input
Input Parameter
Required /Optional
Description
Example
Group ID
Required
The ID of the group to remove members. Group IDs can be obtained using the List Groups command.
***************************************
User IDs
Required
The IDs of the users to remove from the specified group. User IDs can be obtained using the List Group Members or List Users command.
[ "***************************************" ]
Output
Raw Data
The primary response data from the API request.
D3 enriches the raw data from the original Azure Active Directory API response by adding the userid field to indicate your input user ids, and adding actionResult field to indicate whether the users have been successfully removed.
SAMPLE DATA
JSON
[
{
"userid": "***************************************",
"actionResult": "remove user successfully"
}
]
Context Data
The data extracted from Raw Data is converted into JSON format. Context Data may be identical to Raw Data in some cases.
D3 enriches the context data from the original Azure Active Directory API response by adding the userid field to indicate your input user ids, and adding actionResult field to indicate whether the users have been successfully removed.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
SAMPLE DATA
CODE
[
{
"userid": "***************************************",
"actionResult": "remove user successfully"
}
]
Key Fields
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
USERID
ACTIONRESULT
***************************************
remove user successfully
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Remove Group Members failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Remove Group Members failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Reset Password
Resets the password of a specified user. This can only be done by an administrator with appropriate permissions and cannot be performed on a user's own account. The admin can either provide a new password or have the system generate one. The user is prompted to change their password on their next sign-in. Please note that the grant type must be authorization_code(delegated).
Note: For delegated scenarios, the calling administrator needs at least the Authentication Administrator or Privileged Authentication Administrator Microsoft Entra role. Admins with User Administrator, Helpdesk Administrator, or Password Administrator roles can also reset passwords for non-admin users and a limited set of admin roles as defined in Privileged roles and permissions in Microsoft Entra ID (preview).
Reader Note
User ID or User Principal Name is a required parameter to run this command.
Run the List Users command to obtain User ID or User Principal Name. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Please note that the email address cannot be the same as input in User ID or User Principal Name(ID or name will correspond to an email address). If those email addresses are the same, errors will be returned.
Input
Input Parameter
Required /Optional
Description
Example
User ID or User Principal Name
Required
The ID or User Principal Name of the user account to reset password. User IDs and Principal Names can be obtained using the List Users command.
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Reset Password failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 400.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Connector Error: Grant Type should be authorization_code.
Error Sample Data
Reset Password failed.
Status Code: 400.
Message: Connector Error: Grant Type should be authorization_code.
Revoke SignIn Sessions
Invalidates all the refresh tokens issued to applications for the specified 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 the device.
Reader Note
The parameter User ID or User Principal Name is required to run this command.
Run the List Users command to obtain User ID or User Principal Name. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
User ID Or User Principal Name
Required
The IDs or Principal Names of the users to revoke sign-in sessions. User IDs and Principal Names can be obtained using the List Users command.
The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.
It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@odata.context
https://graph.microsoft.com/v*.*/***
value
True
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Revoke SignIn Sessions failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 404.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Error Sample Data
Revoke SignIn Sessions failed.
Status Code: 404.
Message: Resource does not exist or one of its queried reference-property objects is not present.
Update User
Updates the properties of a user object. Not all properties can be updated by Member or Guest users with their default permissions without Administrator roles. Compare member and guest default permissions to see the properties they can manage.
Reader Note
The parameter User IDs or User Principal Names is required to run this command.
Run the List Users command to obtain User IDs or User Principal Names. User IDs can be found in the returned raw data at the path $.value[*].id. User Principal Names can be found in the returned raw data at the path $.value[*].userPrincipalName.
Input
Input Parameter
Required /Optional
Description
Example
User IDs Or User Principal Names
Required
The IDs or Principal Names of the users to update. User ID and Principal Names can be obtained using the List Users command.
[ "*****@*****.com"]
Updated Fields
Required
The updated values of the relevant fields. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance, you should not include existing values that have not changed. Please refer to Update user - Microsoft Graph v1.0 for more information on available user fields.
Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields. The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.
Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.
The Partially Successful state only occurs when a command's input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Result
Provides a brief summary of outputs in an HTML formatted table.
SAMPLE DATA
@ODATA.CONTEXT
BUSINESSPHONES
DISPLAYNAME
GIVENNAME
JOBTITLE
MAIL
MOBILEPHONE
OFFICELOCATION
PREFERREDLANGUAGE
SURNAME
USERPRINCIPALNAME
ID
https://graph.microsoft.com/v1*.*/***
['****************']
*****1
Dora
IT specialist
None
****************
MountainView
en-US
Emon
*****@*****.com
***************************************
Error Handling
If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Update User failed.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Access is denied to the requested resource. The user might not have enough permission.
Error Sample Data
Update User failed.
Status Code: 403.
Message: Access is denied to the requested resource. The user might not have enough permission.
Test Connection
Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.
Input
N/A
Output
Return Data
Indicates one of the possible command execution states: Successful or Failed.
The Failed state can be triggered by any of the following errors:
A connection issue with the integration
The API returned an error message
No response from the API
You can view more details about an error in the Error tab.
Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.
SAMPLE DATA
CODE
Successful
Error Handling
If the Return Data is Failed, an Error tab will appear in the Test Result window.
The errortab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.
Parts in Error
Description
Example
Failure Indicator
Indicates the command failure that happened at a specific input and/or API call.
Test Connection failed. Failed to check the connector.
Status Code
The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Microsoft Entra ID portal. Refer to the Microsoft Graph error responses and resource types for details.
Status Code: 403.
Message
The raw data or captured key error message from the integration API server about the API request failure.
Message: Access is denied to the requested resource. The user might not have enough permission.
Error Sample Data
Test Connection failed. Failed to check the connector.
Status Code: 403.
Message: Access is denied to the requested resource. The user might not have enough permission.
FAQ
Question 1: Why do I see the following error message when I click Get Authorization?
Answer: You are logged in to a Microsoft account that has not been configured as a Microsoft Azure user. You can choose to log out of your current account, then sign in to an existing account or add your account to Microsoft Azure users.
If you choose to add an account, you can add a new user on Microsoft Entra ID or use the D3 Create User command.
JavaScript errors detected
Please note, these errors can depend on your browser setup.
If this problem persists, please contact our support.
