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:
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
Log into your Duo Admin Panel.
Navigate to Applications on the left-hand tab and click on the Protect an Application option.
Locate the Admin API entry using the search bar and click on the Protect button.
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
Log in to D3 SOAR.
Find the Duo Admin integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Duo Admin in the search box to find the integration, then click it to select it.
Click on the + Connection button on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Duo Admin.
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.
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.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the checkbox 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.
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).
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.
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.
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 check mark appear beside the Test Connection button. If the test connection fails, check your connection parameters and try again.
Click OK to close the alert window.
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:
Navigate to Configuration Application Settings. Select Date/Time Format.
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
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".
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 |
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
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
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
|
Output
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
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
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
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. |