Infrastructure

Duo Security

Connect Duo Security to Ploy to see every Duo user, their status, whether they have enrolled a second factor, when they last signed in, and which Duo groups they belong to. You can also choose to see the administrators of your Duo account and their administrator roles. Ploy can create users, disable and re-enable users and administrators, remove them, change an administrator's role, and add or remove users from groups.

This integration is in beta

The Duo Security integration is in beta. It was built from Duo's Admin API documentation and has not yet been checked against a live Duo account, so some details may need adjusting once customers connect it. Beta does not limit what the integration can do.

The first step of setup is a consent checkbox. Ticking it lets Ploy capture redacted error data when a request to Duo fails: the error response Duo sends back, with personal details, keys and other secrets removed. Ploy uses it only to fix problems with this integration. You must tick the box to continue.

What Ploy reads

  • Every Duo user, with their username, email address and status (active, bypass, locked out, disabled, or waiting to be deleted)

  • Whether each user has enrolled a second factor, and whether it is a phone, a hardware token or a security key

  • When each user last signed in through Duo

  • Every Duo group and the users in it

  • If you turn it on, every administrator of your Duo account with their administrator role and status

Ploy does not read your Duo authentication logs or the applications Duo protects.

Before you start

You need:

  • An administrator with the Owner role in the Duo Admin Panel, because only an Owner can create an Admin API application

  • A Duo plan that includes the Admin API (Duo Essentials, Advantage or Premier, or an Advantage or Premier trial)

Create an Admin API application in Duo

  1. Sign in to the Duo Admin Panel as an Owner.

  2. Go to Applications, then Protect an Application, and find Admin API. Click Protect.

  3. On the new application's page, note the Integration key, the Secret key and the API hostname. Treat the secret key like a password.

  4. Under Permissions, tick Grant resource - Read so Ploy can read users and groups.

  5. Tick Grant resource - Write if Ploy should create, disable, re-enable and remove users and change their groups.

  6. If you want Ploy to see administrators, tick Grant administrators - Read. Tick Grant administrators - Write as well if Ploy should disable, remove or change the role of an administrator.

  7. If you restrict the application to certain networks, allow the addresses Ploy connects from.

  8. Click Save Changes.

Connect Duo Security in Ploy

  1. In Ploy, open Integrations and choose Duo Security.

  2. Tick the beta consent checkbox.

  3. Enter the API hostname, for example api-1a2b3c4d.duosecurity.com.

  4. Enter the Integration key and paste the Secret key.

  5. Choose whether to scan Duo administrators. Choose Yes only if you gave the application Grant administrators - Read.

  6. Click Test. Ploy reads one Duo user to check the details work.

  7. Finish the setup. The first scan starts straight away.

Things to know

  • Users and administrators are separate in Duo. Someone who is both appears twice in Ploy, once as a Duo user and once as a Duo administrator, linked to the same person by their email address.

  • Disabled users and users waiting in Duo's trash show as having lost access straight away.

  • Removing a user or administrator from Ploy deletes them from Duo permanently. It does not go through Duo's 7-day trash. To keep the account recoverable, disable it instead.

  • New users get your chosen username, or their email address if you do not set one. They enrol their own second factor.

  • Duo does not let the Admin API disable users or administrators that are synced from Active Directory or Entra ID, or disable an administrator with the Owner role. Make those changes in your directory or the Duo Admin Panel.

  • Ploy only assigns the eight standard Duo administrator roles. Custom roles are shown but cannot be assigned from Ploy.

  • Duo does not record when someone joined a group, so group access has no start date.

Troubleshooting

  • Duo rejected those keys: check the integration key and secret key were copied in full from the Admin API application.

  • Those keys cannot read users: give the Admin API application Grant resource - Read, then test again.

  • Administrators do not appear: check you chose Yes for scanning administrators and gave the application Grant administrators - Read. Some Duo accounts set up through Cisco Security Cloud Control have no administrators API, and then administrators cannot be scanned.

Was this helpful?
Was this helpful?