> ## Documentation Index
> Fetch the complete documentation index at: https://help.dsalta.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Duo

> MFA / identity security — users, admins & incidents

<Tabs>
  <Tab title="Overview">
    Connect Duo with an Admin API application to sync end users, Duo Admin Panel administrators, and MFA status, and run access reviews. Read-only; the credential is held by Nango, and DSALTA keeps only a connection reference.

    <Info>
      **Read-only access.** DSALTA only reads data from this integration. It never creates, modifies, or deletes anything in your environment, and every remediation step is performed by your team directly in the third-party product.
    </Info>

    <Note>
      DSALTA collects this integration's data when you connect it — you can refresh it at any time with **Sync from integrations** on the **Integrations** page. The compliance checks below re-run once a day at 02:00 America/New\_York.
    </Note>

    ## What DSALTA reads

    DSALTA reads two Duo rosters and merges them onto your **Access** page: the end users Duo protects with 2FA — username, email, name, status, MFA enrolment and creation date — and your Duo Admin Panel administrators, with their name, email, role and status. Anyone who appears in both lists is deduplicated by email into a single row. Denied and self-reported-fraud authentication events from the last 30 days appear on your **Incidents** page. The administrator roster requires the **Grant administrators - Read** permission on your Admin API application, and the authentication log requires **Grant read log**.

    It calls these Duo endpoints:

    * `/admin/v1/users`
    * `/admin/v1/admins`
    * `/admin/v2/logs/authentication`

    Every request is a read. DSALTA has no code path that creates, modifies, or deletes anything in your Duo environment.

    ## Troubleshooting

    <AccordionGroup>
      <Accordion title="The connection fails to validate">
        Wrong Integration Key, Secret Key or API hostname, or an Admin API application that is missing **Grant resource - Read**. Grant that permission and save the application in the Duo Admin Panel before you connect.
      </Accordion>

      <Accordion title="An administrator shows MFA Unknown">
        Duo reports an enrolment flag for end users but not for administrators, so DSALTA reads the factors registered on the admin record instead — a WebAuthn credential, an activated phone or a hardware token shows **Yes**. With none of the three on the record the column shows **Unknown**. A phone listed as not activated is a number on file rather than an enrolled device.
      </Accordion>
    </AccordionGroup>

    <AccordionGroup>
      <Accordion title="How do I check whether the connection is healthy?">
        Open **Integrations** in the DSALTA sidebar, stay on the **Connected** tab, and click **Manage** on the integration's card. Open the **Status** tab: it shows either **Connected and working properly** or **Connection issues detected**.

        Use the **Status** tab, not **Overview** — Overview always reports **Connected** regardless of the real state.
      </Accordion>

      <Accordion title="A check shows Failed and nothing changed on my side">
        On an integration-powered check, **Failed** normally means DSALTA was blocked rather than that you are non-compliant. Open the test, go to **Source Data**, and read the result code: **403** is a missing permission, **428** is a setting DSALTA still needs, **500** is a failure on DSALTA's side.

        A real compliance gap shows **207** and leaves the test looking **Completed**. See [Understanding Test Results](/guides/data-library/test-results).
      </Accordion>

      <Accordion title="Data looks out of date">
        Compliance checks re-run once a day at 02:00 America/New\_York. To refresh sooner, open **Integrations → Connected** and click **Sync from integrations** at the top right — it refreshes every connected integration at once.
      </Accordion>

      <Accordion title="How do I repair a broken connection?">
        There is no Reconnect, Repair or Refresh Token button. The only repair available is to disconnect and connect again.

        <Warning>
          **Disconnecting is destructive and cannot be undone.** DSALTA removes the access records, inventory, vulnerabilities, code changes, incidents and device records collected from this integration, and deletes the test results tied to the connection. Export anything you still need as audit evidence first — see [Integration errors](/troubleshooting/integration-errors).
        </Warning>
      </Accordion>

      <Accordion title="Configure scope will not let me change anything">
        That is expected. **Configure scope** is read-only — it shows what DSALTA is permitted to read, and has no Save action. To change what DSALTA can see, change the permissions on the credential in the third-party product, then disconnect and connect again.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="How to connect">
    A Duo Admin API application's Integration Key, Secret Key and API hostname. Read-only.

    **Before you begin**

    * A Duo Advantage, Premier or Essentials plan, or an Advantage/Premier trial — the Admin API is not on the base free tier
    * An Owner-role Duo administrator account, which is required to add an Admin API application
    * The three permissions below granted on that application before you connect

    You will need:

    | Field               | Where to find it    | Example                                           |
    | ------------------- | ------------------- | ------------------------------------------------- |
    | **Integration Key** | See the steps below | Shown on the Admin API application's details page |
    | **Secret Key**      | See the steps below | Shown on the same page — treat it as a password   |
    | **API Hostname**    | See the steps below | `api-xxxxxxxx.duosecurity.com`                    |

    <Steps>
      <Step title="Start in DSALTA">
        Open **Integrations** in the DSALTA sidebar, find **Duo**, and click **Connect** to open the connect panel. Leave it open — it lists every value you need, and you create those in the steps below.
      </Step>

      <Step title="Check your Duo plan">
        The Admin API is available on Duo Advantage, Premier, or Essentials plans, and on Advantage/Premier trials. If you don't have a Duo account, sign up for a trial at duo.com first.
      </Step>

      <Step title="Create an Admin API application">
        In the Duo Admin Panel, go to **Applications → Application Catalog**, find **Admin API**, and click **+ Add**. You must be logged in as an Owner-role administrator.

        <Tip>
          If **Admin API** is not in the catalog, you are either on the base free tier or signed in as an administrator below Owner role — ask an Owner to create the application for you.
        </Tip>

        <img src="https://mintcdn.com/dsalta/50UUP7lNdp3gnRd3/images/integrations/duo/01-application-catalog.png?fit=max&auto=format&n=50UUP7lNdp3gnRd3&q=85&s=eca79211a64448bc4087e416ac423d37" alt="Duo's Admin Panel with Applications open in the sidebar and Application Catalog selected in the Manage list" style={{maxWidth:"720px",width:"100%",borderRadius:"8px"}} width="1100" height="504" data-path="images/integrations/duo/01-application-catalog.png" />
      </Step>

      <Step title="Grant exactly these 3 permissions">
        Check **Grant resource - Read** (users, phones, tokens), **Grant administrators - Read** (admin roster), and **Grant read log** (authentication log). Leave everything else unchecked — DSALTA only reads data, never writes.

        <Info>
          Each permission maps to one part of the sync: **Grant resource - Read** is required for the connection to validate, **Grant administrators - Read** adds your Duo Admin Panel administrators to the **Access** page, and **Grant read log** populates the **Incidents** page.
        </Info>

        <img src="https://mintcdn.com/dsalta/50UUP7lNdp3gnRd3/images/integrations/duo/02-admin-api-permissions.png?fit=max&auto=format&n=50UUP7lNdp3gnRd3&q=85&s=97a8efd3bb88f4a010d5d1f0a77c4649" alt="A Duo Admin API application showing the Integration key, Secret key and API hostname fields above the Settings Permissions checkboxes, including Grant administrators with its Read and Write options" style={{maxWidth:"720px",width:"100%",borderRadius:"8px"}} width="1100" height="504" data-path="images/integrations/duo/02-admin-api-permissions.png" />
      </Step>

      <Step title="Copy the 3 credentials and click Save">
        Copy the Integration Key, Secret Key, and API Hostname (looks like `api-xxxxxxxx.duosecurity.com`) shown after saving. Make sure you actually click **Save** — the permissions and credentials aren't applied until you do. You'll enter all 3 in the next step.

        <Warning>
          **The Secret Key is a credential for your whole Duo tenant.** Anyone holding all three values can read your users, administrators and authentication log. Paste it only into the connect window in the next step, and never into a ticket, chat message or shared document.
        </Warning>
      </Step>

      <Step title="Connect Duo">
        Return to the connect panel you opened in step 1 and start the connection. A secure Nango window opens — enter the Integration Key, Secret Key, and API hostname there. The credential is stored by Nango; DSALTA keeps only a connection reference and never stores the keys directly.

        <img src="https://mintcdn.com/dsalta/50UUP7lNdp3gnRd3/images/integrations/duo/03-connect-window.png?fit=max&auto=format&n=50UUP7lNdp3gnRd3&q=85&s=ef51c3c491777b03a9b5af6f97be179c" alt="The Link Cisco Duo Admin API Account window with fields for API Hostname, Integration Key and Secret Key" style={{maxWidth:"720px",width:"100%",borderRadius:"8px"}} width="1002" height="1288" data-path="images/integrations/duo/03-connect-window.png" />
      </Step>
    </Steps>

    <Check>
      DSALTA validates the credential when you connect, by requesting a single record from `/admin/v1/users`. On success the integration moves to the **Connected** tab, and **Manage → Status** reads **Connected and working properly**. Checks begin reporting after the first sync.
    </Check>

    <Warning>
      **If the connection is rejected.** Wrong Integration Key, Secret Key or API hostname, an Admin API application saved without "Grant resource - Read", or a Duo plan that does not include the Admin API.

      The on-screen message is generic — see [Connection error messages](/troubleshooting/connection-error-messages).
    </Warning>
  </Tab>

  <Tab title="Automated checks">
    Each check below re-runs once a day, at 02:00 America/New\_York, while this integration is connected. Click any check for step-by-step remediation guidance.

    | Check                                                                                                              | Severity | What it verifies                                                               |
    | ------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------ |
    | [User access to Critical System should be valid](/integrations/duo/user-access-to-critical-system-should-be-valid) | Info     | Checks that everyone with Duo access is an active employee on the People page. |
    | [Offboarded users should not have active access](/integrations/duo/offboarded-users-should-not-have-active-access) | High     | Checks that offboarded employees no longer have active Duo access.             |
    | [MFA should be enabled for all users](/integrations/duo/mfa-enabled-for-all-users)                                 | High     | Checks that every active Duo user has multi-factor authentication enrolled.    |
  </Tab>

  <Tab title="Useful links">
    | Topic   | Link                                                                    |
    | ------- | ----------------------------------------------------------------------- |
    | Setup   | [Duo plans and trial sign-up](https://duo.com)                          |
    | General | [Duo website](https://duo.com)                                          |
    | DSALTA  | [Connection error messages](/troubleshooting/connection-error-messages) |
  </Tab>
</Tabs>