Skip to main content
Skip table of contents

Duo Admin

LAST UPDATED: OCT 24, 2024

Overview

The DUO Admin integration enables organizations to read their Duo account's authentication logs and administrator logs as well as read or update account settings. To use this integration, access to the Duo Admin API is required.

D3 SOAR is providing REST operations to function with Duo Admin.

Duo Admin is available for use in:

D3 SOAR

V16.8+

Category

Identity & Access Management

Deployment Options

Option II, Option IV

Known Limitations

For each API call, a maximum of 50 JSON objects can be included in a JSON array per minute. For instance, 2 API calls are required to lock or unlock 100 userIDs, with each JSON array containing 50 user IDs (in JSON format).

Refer to Duo Admin | Bulk Operations for detailed information.

Connection

To connect to Duo Admin from D3 SOAR, follow this part to collect the required information below:

Parameter

Description

Example

API Hostname

Your DUO API hostname in the format: "api-*****.duosecurity.com." Your API hostname can be obtained on the DUO Admin portal by clicking on Protect an Application and locating the entry for Admin API in the applications list. Click on Protect in the far-right to configure the application and retrieve your API Hostname.

api-*****.duosecurity.com

Integration Key

The Integration Key for DUO Admin API authentication.

*****

Secret Key

The Secret Key for DUO Admin API authentication.

*****

READER NOTE

The prerequisite for using this guide is access to the Duo Admin API, which is automatically available to paying Duo Premier, Duo Advantage, and Duo Essentials customers and new customers with an Advantage or Premier trial.

Permission Requirements

Each endpoint in the Duo Admin API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command

Required Permissions

Fetch Event

Grant read log

Get Activity Logs

Grant read log

Get Telephony Logs

Grant read log

Get Users

Grant resource - Read

Lock Users

Grant resource - Write

Unlock Users

Grant resource - Write

Test Connection

Grant resource - Read

Duo Admin's role-based access control (RBAC) model enables authorization of users based on roles with different sets of permissions. Duo Admin distinguishes between authentication, which establishes the identity of the user, and authorization, which decides what actions an authenticated user may perform. For more information, see Duo Admin API | First Steps.

READER NOTE

Only administrators with the Owner role can create or modify an Admin API application from the Duo Admin Panel.

Configuring Duo Admin to Work with D3 SOAR

  1. Log into your Duo Admin Panel.

  2. Navigate to Applications on the left-hand tab and click on the Protect an Application option.

    Group 8.png
  3. Locate the Admin API entry using the search bar and click on the Protect button.

    Group 9.png
  4. Save your integration key, secret key, and API hostname in a secure place using the Copy buttons ( refer to step 3i of Configuring D3 SOAR to Work with Duo Admin). See Protecting Applications for more information about protecting applications in Duo and additional application options.

Configuring D3 SOAR to Work with Duo Admin

  1. Log in to D3 SOAR.

  2. Find the Duo Admin integration.

    screenshot_1 (4).png
    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type Duo Admin in the search box to find the integration, then click it to select it.

    4. Click on the + Connection button on the right side of the Connections section. A new connection window will appear.

  3. Configure the following fields to create a connection to Duo Admin.

    screenshot_2 (4).png
    1. Connection Name: The desired name for the connection.

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

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

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

    5. Description (Optional): Add your desired description for the connection.

    6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.

      att_1_for_211845286 (1).png
    7. Configure User Permissions: Defines which users have access to the connection.

    8. Active: Check the checkbox to ensure the connection is available for use.

    9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.

      screenshot_3 (8).png

      1. Input the API Hostname from the Duo Admin platform (refer to step 4 of Configuring Duo Admin to Work with D3 SOAR).

      2. Copy the Integration Key from the Duo Admin platform (refer to step 4 of Configuring Duo Admin to Work with D3 SOAR).

      3. Input the Secret Key from the Duo Admin platform (refer to step 4 of Configuring Duo Admin to Work with D3 SOAR).

    10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.

    11. 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 tick box. 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.

  4. Test the connection.

    1. 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 check mark appear beside the Test Connection button. If the test connection fails, check your connection parameters and try again.

    2. Click OK to close the alert window.

    3. Click +Add to create and add the configured connection.

Commands

Duo Admin 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.

Integration API Note

For more information about the Duo Admin API, refer to the Duo Admin API reference.

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Duo Admin to Work with D3 SOAR sections for details.

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:

  1. Navigate to Configuration Application Settings. Select Date/Time Format.

  2. Choose your desired date and time format, then click on the Save button.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Fetch Events

Ingests DUO Authentication Logs into VSOC as events. There is an intentional two-minute delay in the availability of new authentication logs in the API response. Duo operates a large-scale distributed system, and this two minute buffer period ensures that calls will return consistent results. As performing a query before the buffer period will return empty results, it is suggested to include a tolerance scope of at least 2 minutes in the Fetch Event schedule.

READER NOTE

User IDs is a optional parameter to run this command.

  • Run the Get Users command to obtain the User IDs. User IDs can be found in the raw data at the path $.response[*].user_id.

Input

Input Parameter

Required/Optional

Description

Example

Start Time

Optional

The start time of the time range to fetch authentication logs (in UTC). By default, the value is 4 hours before End Time. Start Time cannot be earlier than 180 days from now.

2024-06-15 00:00:00

End Time

Optional

The end time of the time range to fetch authentication logs (in UTC). By default, the value is the current time. End Time cannot be earlier than Start Time.

2024-06-15 01:00:00

User IDs

Optional

The ID(s) of the user(s) to unlock. User IDs can be obtained using the Get Users command.

JSON
[ "*****" ]

Event Type

Optional

Filters authentication logs by event type, with the options: Authentication | Enrollment. By default, both Authentication and Enrollment events will be returned.

Enrollment

Number of Event(s) Fetched

Optional

The maximum number of authentication logs to return, from 1 to 1000. By default, all logs matching the filter criteria will be returned.

10

Output

Return Data

Indicates one of the possible command execution states: Successful, Successful with No Event Data, 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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "response": [
        {
            "http_status": 200,
            "response": {
                "alias1": null,
                "alias2": null,
                "alias3": null,
                "alias4": null,
                "aliases": {},
                "created": 1729121198,
                "desktoptokens": [],
                "email": "",
                "enable_auto_prompt": true,
                "firstname": "",
                "groups": [],
                "is_enrolled": false,
                "last_directory_sync": null,
                "last_login": null,
                "lastname": "",
                "lockout_reason": null,
                "notes": "",
                "phones": [],
                "realname": "",
                "status": "active",
                "tokens": [],
                "u2ftokens": [],
                "user_id": "*****",
                "username": "*****",
                "webauthncredentials": []
            },
            "stat": "OK"
        }
    ],
    "stat": "OK"
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "AuthenticationEventIDs": [
        "*****"
    ],
    "UserIDs": [
        "*****"
    ],
    "Statuses": [
        "active"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Start Time (UTC)

2024-06-15 00:00:00

End Time (UTC)

2024-06-15 01:00:00

Events Count

1

Fetch Event Field Mapping

Fetch Event commands require event field mapping. Field mapping plays a key role for data normalization within the event pipeline. Field mapping converts the original data fields from the different providers to standardized D3 fields as defined by the D3 Model. Refer to Event and Incident Intake Field Mapping for details.

To customize field mapping, click + Add Field and add the custom field of your choice. You can also remove built-in field mappings by clicking x. Note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Duo Admin integration has some pre-configured field mappings for default field mapping.

  • Default Event Source

    The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events (e.g., LocalTime and EventType). The default event source has a "Main Event JSON Path" (i.e. $.authlogs) that is used to extract a batch of events from the response raw data. Click Edit Main JSON Path to view the "Main Event JSON Path".

    Group 10 (1).png
    • Main Event JSON Path: $.authlogs

      The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...’]) should be used to separate child elements in JSON arrays.

      For example, the root node of a JSON Path is authlogs. The child node denoting the Unique Event Key field would be txid. Putting it together, the JSON Path expression to extract the Unique Event Key is $.authlogs.txid.

Field Name

Source Field

Unique Event Key

.txid

Start Time

.timestamp

hostname

.access_device.hostname

Action result

.result

Reason

.reason

Username

.user.name

User ID

.user.key

User Group

.user.group

Event Type

.event_type

Factor

.factor

Email

.email

Trusted Endpoint Status

.trusted_endpoint_status

App

.application.name

Application ID

.application.key

Device IP address

.access_device.ip

Browser

.access_device.browser

Access State

.access_device.location.state

Access Country

.access_device.location.country

Operating System

.access_device.os

OS Version

.access_device.os_version

User Alias

.alias

Auth Device Name

.auth_device.name

Auth Device IP

.auth_device.ip

Auth Device City

.auth_device.location.city

Auth Device State

.auth_device.location.state

Auth Device Country

.auth_device.location.country

Auth Device ID

.auth_device.key

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

Fetch Event 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 Proofpoint Protection Server portal. Refer to the HTTP Status Code Registry 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: Bad request.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Bad request.

Get Activity Logs

Returns a list of administrator activity log events ranging from the last 180 days up to two minutes before the current time. There is an intentional two-minute delay in the availability of new authentication logs in the API response. Duo operates a large-scale distributed system, and this two minute buffer period ensures that calls will return consistent results.

Input

Input Parameter

Required/Optional

Description

Example

Start Time

Optional

The start time of the time range to search activity logs (in UTC). By default, the value is 4 hours before End Time. Start Time cannot be earlier than 180 days from now.

2024-06-15 00:00:00

End Time

Optional

The end time of the time range to search activity logs (in UTC). By default, the value is the current time. End Time cannot be earlier than Start Time.

2024-06-15 01:00:00

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "items": [
        {
            "access_device": null,
            "action": {
                "details": null,
                "name": "user_update"
            },
            "activity_id": "*****",
            "actor": {
                "details": "{\"created\": null, \"last_login\": null, \"email\": null, \"status\": null, \"groups\": null}",
                "key": null,
                "name": "API (Admin API)",
                "type": "adminapi"
            },
            "akey": "*****",
            "application": null,
            "old_target": {
                "details": "{\"uname\": \"*****\", \"realname\": \"\", \"status\": \"Active\", \"notes\": \"\", \"email\": \"\", \"display_id\": null, \"revoked_for\": null, \"firstname\": null, \"lastname\": null, \"custom_attributes\": {}}",
                "key": "*****",
                "name": "*****",
                "type": "user"
            },
            "outcome": null,
            "target": {
                "details": "{\"uname\": \"*****\", \"realname\": \"\", \"status\": \"Active\", \"notes\": \"\", \"email\": \"\", \"display_id\": null, \"revoked_for\": null, \"firstname\": null, \"lastname\": null, \"custom_attributes\": {}}",
                "key": "*****",
                "name": "*****",
                "type": "user"
            },
            "ts": "2024-10-21T18:28:36.188833+00:00"
        }
    ],
    "metadata": {
        "next_offset": "1729025971157,*****",
        "total_objects": 1
    }
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "ActivityIDs": [
        "*****"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Activities Count

1

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Bad Request

Error Sample Data

Get Activity Logs failed.

Status Code: 400.

Message: Bad Request

Get Telephony Logs

Returns a list of telephony log events ranging from the last 180 days up to two minutes before the current time. There is an intentional two-minute delay in the availability of new authentication logs in the API response. Duo operates a large-scale distributed system, and this two minute buffer period ensures that calls will return consistent results.

Input

Input Parameter

Required/Optional

Description

Example

Start Time

Optional

The start time of the time range to search telephony logs (in UTC). By default, the value is 4 hours before End Time. Start Time cannot be earlier than 180 days from now.

2024-06-15 00:00:00

End Time

Optional

The end time of the time range to search telephony logs (in UTC). By default, the value is the current time. End Time cannot be earlier than Start Time.

2024-06-15 01:00:00

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "items": [
        {
            "context": "enrollment",
            "credits": 1,
            "phone": "*****",
            "telephony_id": "*****",
            "ts": "2024-10-17T20:57:19.348164+00:00",
            "txid": "*****",
            "type": "sms",
            "eventtype": "telephony",
            "host": "*****"
        }
    ],
    "metadata": {
        "next_offset": "1729198639348,*****",
        "total_objects": 3
    }
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "TelephonyEventIDs": [
        "*****"
    ],
    "AuthenticationEventIDs": [
        "*****"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Telephony Events Count

1

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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 Telephony 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Bad Request

Error Sample Data

Get Telephony Logs failed.

Status Code: 400.

Message: Bad Request

Get Users

Searches for users in your DUO instance.

Input

Input Parameter

Required/Optional

Description

Example

User Names

Optional

The name(s) of the user(s) for whom to retrieve user details. Up to 100 user names can be provided. By default, all users will be returned.

JSON
[ "user1" ]

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "metadata": {
        "prev_offset": 0,
        "total_objects": 2
    },
    "response": [
        {
            "alias1": null,
            "alias2": null,
            "alias3": null,
            "alias4": null,
            "aliases": {},
            "created": 1729121198,
            "desktoptokens": [],
            "email": "",
            "enable_auto_prompt": true,
            "firstname": "",
            "groups": [],
            "is_enrolled": false,
            "last_directory_sync": null,
            "last_login": null,
            "lastname": "",
            "lockout_reason": null,
            "notes": "",
            "phones": [],
            "realname": "",
            "status": "active",
            "tokens": [],
            "u2ftokens": [],
            "user_id": "*****",
            "username": "*****",
            "webauthncredentials": []
        }
    ],
    "stat": "OK"
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "UserNames": [
        "user1"
    ],
    "UserIDs": [
        "*****"
    ],
    "Statuses": [
        "active"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Users Count

1

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Bad Request

Error Sample Data

Get Users failed.

Status Code: 400.

Message: Bad Request

Lock Users

Locks out the specified users.

READER NOTE

User IDs is a required parameter to run this command.

  • Run the Get Users command to obtain the User IDs. User IDs can be found in the raw data at the path $.response[*].user_id.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Required

The ID(s) of the user(s) to lock out. User IDs can be obtained using the Get Users command.

JSON
[ "*****" ]

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "response": [
        {
            "http_status": 200,
            "response": {
                "alias1": null,
                "alias2": null,
                "alias3": null,
                "alias4": null,
                "aliases": {},
                "created": 1729121198,
                "desktoptokens": [],
                "email": "",
                "enable_auto_prompt": true,
                "firstname": "",
                "groups": [],
                "is_enrolled": false,
                "last_directory_sync": null,
                "last_login": null,
                "lastname": "",
                "lockout_reason": "Admin API disabled",
                "notes": "",
                "phones": [],
                "realname": "",
                "status": "locked out",
                "tokens": [],
                "u2ftokens": [],
                "user_id": "*****",
                "username": "*****",
                "webauthncredentials": []
            },
            "stat": "OK"
        }
    ],
    "stat": "OK"
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "UserNames": [
        "user1"
    ],
    "UserIDs": [
        "*****"
    ],
    "Statuses": [
        "locked out"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Successful Lock Outs Count

1

Failed Lock Outs Count

0

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

Lock 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Bad Request

Error Sample Data

Lock Users failed.

Status Code: 400.

Message: Bad Request

Unlock Users

Unlocks users who were previously locked out. This command cannot set the "active" status for users who are disabled by directory sync.

READER NOTE

User IDs is a optional parameter to run this command.

  • Run the Get Users command to obtain the User IDs. User IDs can be found in the raw data at the path $.response[*].user_id.

Input

Input Parameter

Required/Optional

Description

Example

User IDs

Optional

The ID(s) of the user(s) to unlock. User IDs can be obtained using the Get Users command.

JSON
[ "*****" ]

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
Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON
{
    "response": [
        {
            "http_status": 200,
            "response": {
                "alias1": null,
                "alias2": null,
                "alias3": null,
                "alias4": null,
                "aliases": {},
                "created": 1729121198,
                "desktoptokens": [],
                "email": "",
                "enable_auto_prompt": true,
                "firstname": "",
                "groups": [],
                "is_enrolled": false,
                "last_directory_sync": null,
                "last_login": null,
                "lastname": "",
                "lockout_reason": null,
                "notes": "",
                "phones": [],
                "realname": "",
                "status": "active",
                "tokens": [],
                "u2ftokens": [],
                "user_id": "*****",
                "username": "*****",
                "webauthncredentials": []
            },
            "stat": "OK"
        }
    ],
    "stat": "OK"
}
Key Fields

Common cyber security indicators such as risk levels, risk level names, unique IDs, file hash values, CVE numbers and IP addresses 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

JSON
{
    "UserNames": [
        "user1"
    ],
    "UserIDs": [
        "*****"
    ],
    "Statuses": [
        "active"
    ]
}
Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

Successful Unlocks Count

1

Failed Unlocks Count

0

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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.

Unlock 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Bad Request

Error Sample Data

Unlock Users failed.

Status Code: 400.

Message: Bad Request

Test Connection

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

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab 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 Duo Admin portal. Refer to the HTTP Status Code Registry 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: Server URL is not valid in format.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Server URL is not valid in format.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.