# Duo security

Connecting Duo Security gives SureCloud read access to your Duo account's user inventory, MFA device enrolment status, authentication policy assignments, and authentication log events. SureCloud monitors MFA enrolment coverage to identify users without an enrolled Duo device, verifies that authentication policies enforce the required factor types and are applied to all protected applications, checks device trust posture for endpoints authenticating via Duo Desktop, and collects authentication log events to provide evidence of MFA enforcement activity. This gives continuous evidence that multi-factor authentication is deployed and enforced across your organisation.

{% hint style="info" %}
SureCloud connects to Duo Security using an API integration key and secret key pair generated in the Duo Admin Panel. Duo uses its own API credential system rather than OAuth 2.0. The integration key and secret are scoped to a specific Duo Admin API application and inherit the permissions granted to that application.
{% endhint %}

## Authentication and setup

{% stepper %}
{% step %}

#### Create an Admin API application in Duo

In the [Duo Admin Panel](https://admin.duosecurity.com/), navigate to **Applications → Protect an Application** and search for **Admin API**. Click **Protect**.

On the Admin API application page, configure the following permissions — grant **Read** access only, no write permissions:

| Permission             | Grant | Purpose                                  |
| ---------------------- | ----- | ---------------------------------------- |
| Grant read resource    | Read  | Read users, groups, and device enrolment |
| Grant read log         | Read  | Read authentication log events           |
| Grant read information | Read  | Read account-level settings and policies |

Note the **Integration key**, **Secret key**, and **API hostname** (in the format `api-xxxxxxxx.duosecurity.com`). These three values are all required to authenticate SureCloud.

{% hint style="warning" %}
The secret key is equivalent to a password. Store it securely and treat it as a credential. Rotate it by generating a new Admin API application if the secret is ever compromised, then update the new values in **SureCloud → Integrations → Duo Security → Edit Connection**.
{% endhint %}
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Duo Security → Connect** and provide:

* **Integration key** (`DIXXXXXXXXXXXXXXXXXX`)
* **Secret key**
* **API hostname** (`api-xxxxxxxx.duosecurity.com`)

Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}

## Endpoints

| API Call                                     | Use Case                                                                                |
| -------------------------------------------- | --------------------------------------------------------------------------------------- |
| `GET /admin/v1/users`                        | Enumerate all users with their Duo status and enrolment state                           |
| `GET /admin/v1/users/{user_id}/phones`       | Read enrolled phone devices per user; detect users with no enrolled device              |
| `GET /admin/v1/users/{user_id}/tokens`       | Read enrolled hardware token devices per user                                           |
| `GET /admin/v1/users/{user_id}/bypass_codes` | Detect users with active bypass codes that circumvent MFA                               |
| `GET /admin/v1/groups`                       | Enumerate Duo groups and their policy assignments                                       |
| `GET /admin/v1/policies`                     | Read authentication policies and their factor requirements                              |
| `GET /admin/v1/integrations`                 | List protected applications and their policy assignments                                |
| `GET /admin/v2/logs/authentication`          | Retrieve authentication log events with factor used, result, and device context         |
| `GET /admin/v1/endpoints`                    | Read Duo Desktop endpoint trust records and device health status                        |
| `GET /admin/v1/settings`                     | Read account-level settings including user lockout policy and new user enrolment policy |

## Pagination

The Duo Admin API uses offset-based pagination for most list endpoints, via `offset` and `limit` query parameters. SureCloud increments `offset` by `limit` (up to 300 for user endpoints) until the response `stat` is `OK` and the returned list is shorter than the page size.

```json
{
  "stat": "OK",
  "response": [
    {
      "user_id": "DU3RP9I2WOC59VZX",
      "username": "alice.nguyen",
      "status": "active",
      "is_enrolled": true,
      "phones": [ { "phone_id": "DP5ZN83...", "type": "mobile" } ]
    }
  ],
  "metadata": {
    "next_offset": [300]
  }
}
```

The authentication log endpoint (`/admin/v2/logs/authentication`) uses a `next_offset` cursor returned in the response metadata. SureCloud passes this value as the `next_offset` query parameter until no `next_offset` is returned.

## Required permissions

The Admin API application must have the following permissions granted with **Read** access:

| Permission             | Purpose                                                         |
| ---------------------- | --------------------------------------------------------------- |
| Grant read resource    | Read users, groups, devices, and bypass codes                   |
| Grant read log         | Read authentication and administrator log events                |
| Grant read information | Read account settings, policies, and application configurations |

No write permissions (`Grant write resource`, `Grant administrator`, `Grant applications`, `Grant settings`) should be granted to SureCloud.

## Polling frequency

| Data type                                           | Collection interval |
| --------------------------------------------------- | ------------------- |
| User inventory and enrolment status                 | 24 hours            |
| Device enrolment per user                           | 24 hours            |
| Bypass code status                                  | 24 hours            |
| Authentication policies and application assignments | 24 hours            |
| Authentication log events                           | 1 hour              |
| Endpoint trust records                              | 24 hours            |

## Troubleshooting

<details>

<summary>Test Connection fails with "Invalid signature" or "Authentication error"</summary>

The Integration key, Secret key, or API hostname is incorrect. Duo API authentication uses HMAC-SHA1 request signing — any mismatch in these three values will cause all requests to fail.

1. In **Duo Admin Panel → Applications → \[Admin API application]**, confirm the Integration key matches exactly what was entered in SureCloud (it begins with `DI`).
2. Confirm the API hostname is in the format `api-xxxxxxxx.duosecurity.com` with no trailing slash or `https://` prefix — SureCloud adds the scheme automatically.
3. If the secret key is unknown, it cannot be retrieved — generate a new Admin API application and update all three values in **SureCloud → Integrations → Duo Security → Edit Connection**.

</details>

<details>

<summary>Users show as enrolled but no device records are appearing</summary>

Device records per user are collected via separate per-user calls to `/admin/v1/users/{user_id}/phones`. If device data is missing, the Admin API application may not have the **Grant read resource** permission, which is required for per-user device lookups.

In **Duo Admin Panel → Applications → \[Admin API] → Permissions**, confirm **Grant read resource** shows **Read**.

</details>

<details>

<summary>Authentication log events are returning for only the past 180 days</summary>

Duo retains authentication log data for **180 days** via the Admin API. Events older than 180 days cannot be retrieved. SureCloud collects authentication log events within a rolling window on each polling cycle — historical events prior to the integration connection date and beyond the 180-day window are not available.

For longer retention, Duo supports log export to a SIEM via the Duo Log Sync utility or the Duo Admin API log streaming feature. Contact SureCloud support if extended log history is required for evidence purposes.

</details>

<details>

<summary>Authentication policies are not appearing for some applications</summary>

Policy data is returned from `/admin/v1/policies` (global policies) and from `/admin/v1/integrations` (per-application policy overrides). If an application uses the global policy rather than a custom policy, it will appear in the integrations list without a specific policy reference. SureCloud represents these applications as using the global policy.

If specific applications are not appearing in the integrations list at all, confirm the Admin API application has **Grant read information** permission, which is required to enumerate protected applications.

</details>

<a href="https://duo.com/docs/adminapi" class="button secondary">Duo Admin API reference</a> <a href="https://duo.com/docs/adminapi#authentication" class="button secondary">Duo API authentication guide</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/duo-security.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.