---
title: "Cisco Duo"
slug: "cisco-duo"
description: "Customer-facing setup instructions: what a Duo administrator must configure in the Duo Admin Panel, and which values to enter into Clarity."
updated: 2026-10-21T19:12:18Z
published: 2026-10-21T19:12:18Z
canonical: "help.claritysecurity.com/cisco-duo"
---

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

# Cisco Duo

Clarity ships **two** Duo connectors. Both use the same **Admin API** application in Duo and the same three credentials, but they cover different populations and need different API permissions:

| Clarity integration | Population it syncs | Entitlements | Duo permission needed |
| --- | --- | --- | --- |
| **Cisco Duo User** | Duo **end users** (the people who authenticate with Duo) | Duo **groups** | Grant resource – Read (+ Write for provisioning) |
| **Cisco Duo Admin** | Duo **administrators** (people who log in to the Admin Panel) | Admin **roles** and **administrative units** | Grant administrators – Read (+ Write for provisioning) |

You can configure one Admin API application in Duo with both permission sets and reuse its keys for both Clarity integrations, or create one application per integration if you want the permissions separated.

## Overview

### Cisco Duo User

| What Clarity syncs / writes | Duo source | Direction |
| --- | --- | --- |
| Users | GET /admin/v1/users | read |
| Groups | GET /admin/v1/groups | read |
| Per-user group memberships | inline groups[] on each user | read |
| Add / remove a user’s group | POST /admin/v1/users/{id}/groups · DELETE …/groups/{group_id} | write |
| Create a user | POST /admin/v1/users | write |
| Disable / re-enable a user | POST /admin/v1/users/{id} with status | write |
| Delete a user | DELETE /admin/v1/users/{id} | write |

A user is treated as **active** in Clarity when its Duo status is active or bypass. Users with status disabled, locked out, or pending deletion are imported as **inactive**.

### Cisco Duo Admin

| What Clarity syncs / writes | Duo source | Direction |
| --- | --- | --- |
| Administrators | GET /admin/v1/admins | read |
| Admin roles (Owner, Administrator, Application Manager, User Manager, Security Analyst, Help Desk, Billing, Read-only) | static list, mirrors Duo’s built-in roles | read |
| Administrative units | GET /admin/v1/administrative_units | read |
| Per-admin role and unit assignments | inline role and admin_units[] on each admin | read |
| Change an admin’s role | POST /admin/v1/admins/{id} with role | write |
| Add / remove an admin from an administrative unit | POST / DELETE /admin/v1/administrative_units/{unit}/admin/{admin} | write |
| Create an admin | POST /admin/v1/admins (activation email sent by Duo, link valid 14 days) | write |
| Disable / re-enable an admin | POST /admin/v1/admins/{id} with status | write |
| Delete an admin | DELETE /admin/v1/admins/{id} | write |

An administrator is treated as **active** in Clarity when its Duo status is Active or Pending Activation. Disabled and Expired admins are imported as **inactive**.

### Authentication

Both connectors authenticate with Duo’s **HMAC request signing** (Duo “v2 signing”): every request is signed with your application’s **secret key** and sent with the **integration key** as the HTTP Basic username. There is no OAuth flow, no browser consent step, and no token to refresh. Nothing is ever sent to Duo except signed API requests from Clarity.

## Prerequisites

- A Duo plan that includes the Admin API. Per Duo, the Admin API is available to **Duo Essentials, Advantage, and Premier** customers and to Advantage or Premier trials. It is **not** available on Duo Free.
- A Duo administrator with the **Owner** role. Duo only lets Owners create or modify an Admin API application.
- **Administrative units** (Cisco Duo Admin connector) are a Duo Advantage / Premier feature. On lower editions the unit sync simply returns nothing.
- Clarity must be able to reach your API hostname on **TCP 443**.

## Step 1 — Create an Admin API application in Duo

1. Log in to the **Duo Admin Panel** as an **Owner**.
2. Go to **Applications → Application Catalog**.
3. Find **Admin API** in the catalog and click **+ Add**.
4. Duo shows the application’s details page with three values you will need:
  - **Integration key** (sometimes called ikey)
  - **Secret key** (skey) — click to reveal it
  - **API hostname** — looks like api-XXXXXXXX.duosecurity.com (Duo Federal tenants use a duofederal.com hostname)
5. Give the application a recognisable name such as *Clarity Security*.

⚠️ Duo’s own guidance: **treat your secret key like a password.** Do not email it or share it outside the people configuring Clarity. If it is ever exposed, reset it in Duo and update the Clarity integration.

## Step 2 — Grant the API permissions

Still on the Admin API application page, tick the permissions the integration needs. Clarity uses nothing outside the rows below.

| Permission | Cisco Duo User | Cisco Duo Admin | Why |
| --- | --- | --- | --- |
| **Grant resource – Read** | Required | — | Reads users and groups. Without it, the credential test fails with HTTP 403 and nothing syncs. |
| **Grant resource – Write** | Required for provisioning | — | Create / disable / delete users and add or remove group membership. Without it, sync works but every provisioning action fails with HTTP 403. |
| **Grant administrators – Read** | — | Required | Reads administrators and administrative units. Without it, the credential test fails with HTTP 403. |
| **Grant administrators – Write** | — | Required for provisioning | Change roles, add / remove unit assignments, create / disable / delete admins. Without it, sync works but provisioning fails with HTTP 403. |

Leave every other permission (Grant applications, Grant settings, Grant read log, Grant read information, identity verification, set Admin API permissions) **unticked**. Clarity does not call those endpoints.

Duo’s Write permissions include Read, so ticking only “Write” is sufficient if you intend to provision.

## Step 3 — Enter the credentials in Clarity

In Clarity, add a **Cisco Duo User** and/or **Cisco Duo Admin** integration and fill in:

| Clarity field | Value from Duo |
| --- | --- |
| **hostname** | The **API hostname** from the Admin API application page, e.g. api-a1b2c3d4.duosecurity.com. Enter the host only — **no https://**, no trailing slash, and keep it lowercase exactly as Duo displays it. |
| **integration_key** | The **Integration key** from the same page (stored encrypted). |
| **secret_key** | The **Secret key** from the same page (stored encrypted). |

All three fields are required. Save, then use Clarity’s **Test credentials** action. The test performs a one-record list call (/admin/v1/users for the User connector, /admin/v1/admins for the Admin connector), so it also confirms the Read permission was granted.

If you are configuring both integrations from one Admin API application, enter the same three values in each.

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| HTTP **401** on the credential test | Wrong secret key, wrong integration key, or the hostname does not match the API hostname shown in Duo (a typo, a https:// prefix, or the hostname of a different Duo account). The signature is computed over the hostname, so any mismatch fails authentication. |
| HTTP **403** on the credential test | The application lacks the Read permission the connector needs (resource – Read for the User connector, administrators – Read for the Admin connector), or the request came from an IP outside **Networks for API Access**. |
| Sync succeeds but provisioning (add / remove group, change role, create / disable / delete) fails with **403** | The matching **Write** permission is not granted. |
| **429** during a large sync | Duo rate-limits Admin API calls per account and returns a bare 429 with no reset header. Clarity backs off with jitter and retries automatically; a sync of a large tenant will simply take longer. |
| Admin connector: adding an admin to an administrative unit fails | Duo requires restricted_by_admin_units = true on the admin first. Clarity sets it automatically, but Duo refuses to restrict an **Owner**, so unit assignments cannot be provisioned to Owners. |
| Admin connector: disable, role change, or delete fails for some admins | Admins managed by Duo **directory sync** cannot be disabled or deleted via the API, and their role can only be changed to Owner. **Owners** cannot be disabled via the API at all. Manage those admins in the Duo Admin Panel. |
| User connector: disable fails for some users | Users synced from **Active Directory or Entra ID** cannot be set to disabled via the API. Disable them in the source directory instead. |
| A user’s group membership looks wrong after sync | Group **status** can override a member’s individual status in Duo. Clarity imports the user’s own status; group-level bypass/disable is not reflected. |

## What Clarity does NOT do

- **User deletion is permanent.** Duo does not move API-deleted users into the seven-day “Pending Deletion” trash; they are removed immediately and cannot be restored. Prefer *deactivate* (which sets disabled) unless permanent removal is intended.
- **No phones, tokens, or devices.** Clarity does not read or manage authentication devices, bypass codes, or enrollment.
- **No custom admin roles.** Clarity models Duo’s eight built-in roles. An administrator holding a **custom role** is imported without a role entitlement, and Clarity cannot assign custom roles.
- **No group creation or deletion.** Groups are read from Duo; Clarity only adds and removes members.
- **No administrative-unit creation or deletion**, and no management of the groups or applications inside a unit — only which admins belong to it.
- **No attribute write-back.** Beyond the fields sent on create (name, email, username), Clarity does not push identity attributes into Duo.
- **No logs, policies, settings, or applications.** The connector never uses the Grant read log, Grant settings, or Grant applications permissions.

## Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support [via email](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.