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
Log in to the Duo Admin Panel as an Owner.
Go to Applications → Application Catalog.
Find Admin API in the catalog and click + Add.
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)
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 — Restrict network access (optional but recommended)
On the same page, Networks for API Access lets you allowlist the IP addresses or ranges that may use this application. If you leave it empty the application “may be accessed from any network”.
If you use it, add Clarity’s egress IP addresses (ask Clarity Support for the current list for your tenant). Duo checks the IP after validating the signature, so a blocked request from an unknown IP is logged in Duo as a possible key compromise. Requests from an unlisted IP fail even when the keys are correct.
Step 4 — 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, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.