Skip to main content

After this article

Lumos has two Duo cards. The Duo card syncs only. The Duo (Multi-Auth) card, tagged Early Access, also provisions, and it’s the one this article’s provisioning steps describe. To tell which one you have, check the card name in your Lumos integrations. You will be able to connect Duo (Cisco Duo) to Lumos to sync users, admins, groups, roles, and last login timestamps for Access Reviews and license management. With the Duo (Multi-Auth) card, you can also create, activate, deactivate, and delete accounts and manage group and role assignments from Lumos.

Capabilities

Activity tracking is supported: the integration syncs each user’s last login timestamp. Provisioning behavior:
  • Create: requires a username, an email, and an account type (user or admin). For users, Lumos checks the username first and links an existing user instead of creating a duplicate. For admins, Duo has no lookup by name or email, so Lumos relies on Duo’s duplicate-email error to link an existing admin. Passwords aren’t supported: Duo’s user creation endpoint has no password field, and its admin creation endpoint ignores the deprecated password field.
  • Assign or remove a group: regular users only. Assigning a group the user already has, or removing one they don’t, is a safe no-op.
  • Assign a role: administrator accounts only. An admin has exactly one role, so assigning a new role replaces the current one. Assigning the role the admin already has is a safe no-op.
  • Remove a role: not supported. Duo requires every admin to hold a role. Assign a different role instead.
  • Activate and deactivate: Lumos sets the account’s status in Duo (works for users and admins), and skips the call if the account is already in the target state. Admins with the Owner role can’t be deactivated. Assign a different role first. Admins in a pending state (for example, awaiting email verification) can’t be activated through the API.
  • Delete: Lumos resolves whether the ID is a user or an admin first, then deletes the account in Duo itself. Users and administrators deleted through the API are removed permanently and can’t be restored. Administrators managed by directory sync can’t be deleted through the API (Duo Admin API). If the account is already gone, the delete is a safe no-op.

Required plan and roles

  • Duo role: you need access to the Duo Admin Panel to create an Admin API application (this is done under Applications → Protect an Application).
  • Lumos role: an Admin in Lumos. Only Admins can connect integrations (see Lumos roles).
  • Permission scoping: Duo Admin API applications carry permission grants. Syncing needs the Grant resource - Read and Grant administrators - Read permissions. Provisioning also needs Grant resource - Write (users and groups) and Grant administrators - Write (admins and roles). To connect read-only, leave the write permission grants off. On the Duo (Multi-Auth) card, Lumos still connects without the write grants, but provisioning actions then fail.
  • Sync vs provisioning: both run over the same Duo Admin API with the same Integration Key and Secret Key.

Instructions

Phase 1: Create an Admin API application in Duo
  1. Log in to the Duo Admin Panel.
  2. Go to Applications → Protect an Application.
  3. Locate Admin API in the applications list and click Protect on the far right.
  4. Under Permissions, select Grant resource - Read and Grant administrators - Read. To let Lumos provision, also select Grant resource - Write (users and groups) and Grant administrators - Write (admins and roles). Save the application.
  5. From the application configuration page, copy the Integration Key and Secret Key.
  6. Note the API hostname. The Subdomain is its first segment (for https://api-333bbc60.duosecurity.com, the subdomain is api-333bbc60).
Phase 2: Connect in Lumos
  1. Find the Duo (Multi-Auth) card in your Lumos integrations for provisioning, or the Duo card for sync only (reconnect an existing card or add a new one).
  2. Enter the Secret Key, Integration Key, and Subdomain.
  3. Click Connect. On the Duo (Multi-Auth) card, Lumos checks the keys by listing a Duo user and an administrator, and the connection fails if either read permission is missing.
Lumos syncs Duo on its regular integration sync schedule, and connecting or reconnecting the integration starts a sync right away. To refresh sooner, see Triggering Syncs Deep Dive.

API Endpoints Used

Troubleshooting

Connection fails with valid keys. Check the Subdomain value: it must be only the first segment of the API hostname (e.g., api-333bbc60), not the full URL. Confirm the keys came from an Admin API application, not another Duo application type. Provisioning actions are unavailable or fail. Check the Admin API application’s permission grants in Duo: user and group changes need Grant resource - Write, and admin and role changes need Grant administrators - Write. The Duo card is sync-only, so to provision, connect the Duo (Multi-Auth) card instead. Deactivating an admin fails. Admins holding the Owner role can’t be deactivated through the API. Assign a different role first, then deactivate.