Skip navigation
Documentation

Duo Splunk Connector

Duo Splunk Connector allow administrators to easily import their Duo logs into their Splunk environment.

Overview

This document takes you through installing and configuring the Duo Splunk Connector in your Splunk environment. Once configured, the connector automatically pulls in the following Duo logs for the last 30 days:

  • Authentication Logs
  • Administrator Logs
  • Telephony Logs
  • Endpoint Logs - Duo Beyond and Duo Access plans only

The connector comes populated with default dashboards for the above logs. Administrators can create new dashboards or manipulate the existing dashboards.

First Steps

  1. Sign up for a Duo account. Duo Splunk Connector requires a Duo Beyond, Duo Access, or Duo MFA plan.

  2. Contact Duo Support to enable Admin API for your Duo account.

  3. Log in to the Duo Admin Panel and navigate to Applications.

  4. Click Protect an Application and locate Admin API in the applications list. Click Protect this Application.

  5. Under the "Settings" section for this application locate the "Permissions" section and check the boxes next to Grant read information, Grant read log, and Grand read resource. Do not check the boxes next to any other permissions.

  6. You may also rename the Admin API application under the "Settings" section.

  7. Click Save.

  8. You can view your integration key, secret key, and API hostname at the top of the page.

    Admin API Application Page

Deployment Considerations

The Duo Splunk Connector has been tested in multiple deployment scenarios; use the directions below based on your deployment.

Single Instance

In a Splunk single instance environment where there is only one Splunk server present and it is acting as both the Indexer and a Search Head you should install and configure the Duo Splunk Connector app on this server.

Distributed Search

In a scenario where you have multiple Indexers that do not communicate with each other but do communicate with all your Search Heads install and configure Duo Splunk Connector on one Indexer. Install but do not configure Duo Splunk Connector on all Search Heads.

Index Clustering

In a scenario where you have multiple Indexers clustered together install and configure Duo Splunk Connector on one Indexer. Install but do not configure Duo Splunk Connector on all other Indexers and Search Heads. Duo Splunk Connector is automatically configured to replicate its index in a Index Clustering deployment.

Forwarders

In any of the above scenarios if you've configured a Splunk server to act as a forwarder, install and configure Duo Splunk Connector on the Forwarder and only install Duo Splunk Connector on the servers mentioned above.

Configure the Duo Security app context to be forwarded from the Forwarder to one Indexer.

Install Duo Splunk Connector

You can choose to install Duo Splunk Connector from Splunkbase or with our manual steps.

Splunkbase

  1. Log into your Splunk deployment as an Administrative user.

  2. While on the home screen click the + icon located under the "Apps" section omn the left-hand side of the page. You'll be taken to the "Browse More Apps" page.

  3. Type Duo Splunk Connector into the search field. Click Install on the Duo Splunk Connector app.

    Search Splunkbase for Duo Splunk Connector app

  4. You'll be asked to sign in with your Splunk.com account information and accept the Splunk Software License Agreement. Once you've entered the required information click Login and Install.

    Install Duo Splunk Connector app

  5. Duo Splunk Connector will automatically install and prompt you to restart Splunk once it is completed. Click Restart Splunk.

    Restart Splunk

  6. Once Splunk restarts log back into the site and return to your home screen.

Manual Install

  1. Download the Duo Splunk Connector.

  2. Log into your Splunk deployment as an Administrative user.

  3. While on the home screen click the gear icon located next to "Apps".

  4. On the "Apps" page click Install app from file.

  5. On the "Upload an app" page click Choose File and select the duo_splunkapp_1.1.2.spl file you downloaded earlier.

    Upload Duo Logs app

  6. Click Upload. Splunk must restart after installation. Click Restart Splunk when prompted.

    Restart Splunk

  7. Once Splunk restarts log back into the site and return to your home screen.

Configuring Duo Splunk Connector

  1. Click on the new Duo Security app under the "Apps" section on the left hand side of the screen.

  2. Review the directions on the "Duo Overview" page and then click Configure Duo when done.

    Configuration Splash screen

  3. On the "Add Data" page on the right-hand side of the screen you'll be asked to enter in Duo Admin API information. For the Name field type Duo Logs.

  4. Paste the Duo Integration Key for the Admin API application you created earlier from the Duo Admin Panel into the Integration Key field.

  5. Paste the Duo Secret Key for the Admin API application you created earlier from the Duo Admin Panel into the Secret Key field.

  6. Paste the Duo Host for the Admin API application you created earlier from the Duo Admin Panel into the Host field.

    Configure Duo app

  7. By default the Duo Splunk Connector queries Duo for new data every 120 seconds. You can change this time by clicking the checkbox next to More settings and changing the value in the Interval field.

    Do not change any other values under "More settings" or this may cause the connector to not function correctly. Please see Advanced Configuration for more options.

    Configure Duo app additional

  8. When you've entered all required information click the Next > button at the top of the screen.

  9. You'll be taken to a page saying that the data input was configured successfully. It may take some time for Duo Logs data to be pulled down.

  10. Return to the Duo Security application to view the default dashboards.

    Duo default dashboard

For more information on the data included in the logs or the format of the logs please visit the Admin API docs page.

Upgrading Duo Splunk Connector

If you are using our manual install steps you can follow these directions to download the latest spl file and upgrade your Splunk.

  1. Log into your Splunk deployment as an Administrative user.

  2. While on the home screen click the gear icon located next to "Apps".

  3. On the "Apps" page click Install app from file.

  4. On the "Upload an app" page click Choose File and select the duo_splunkapp_1.0.1.spl file you downloaded earlier.

  5. Check the box next to Upgrade app.

    Upgrade Duo Logs app

  6. Click Upload. Splunk must restart after installation. Click Restart Splunk when prompted.

    Restart Splunk

  7. Once Splunk restarts the upgrade is complete.

Advanced Configuration

Changing Duo Splunk Connector Index

Duo Splunk Connector by default uses an index named duo that is automatically created when the connector is configured. You may choose to use a different index when configuring the connector and update the macro to match that index name.

  1. On the "Add Data" page click the checkbox next to More settings and select the drop-down next to Index. Select the index you would like to store your Duo logs.

    Specify custom index

  2. When you've entered all required information click the Next > button at the top of the screen.

  3. Click Settings in the top right-hand corner of the screen. A drop-down will appear. Click Advanced search.

  4. On the "Advanced search" page click Search macros.

  5. On the "Search marcos" page click duo_index.

  6. In the Definition field you will see the default index defined as index=duo. Update this value to use the custom index you chose in step 1.

    Example: If your index was "CUSTOMINDEX" the field should be changed to index=CUSTOMINDEX.

    Change index in macro

  7. Click Save.

  8. Return to the Duo Security application to view the default dashboards.

Known Issues

  • Viewing the Overview dashboard may cause the configuration screen appear for a moment. This may happen if your Splunk server is slow to return query results. The screen will disappear within a few seconds after the queries have completed.

Troubleshooting

Need some help? Take a look at our Splunk Connector Knowledge Base articles or Community discussions. For further assistance, contact Support.

Ready to Get Started?

Sign Up Free