Cisco Duo Setup

Connect Cisco Duo to let Junto investigate a customer's MFA problems during ticket work. The AI agent can find Duo users, inspect their status, enrollment, groups, and authenticators, read authentication and administrative activity logs, and review groups and policies. With approval, the agent can also perform one recovery step at a time, such as issuing a single-use bypass code, sending a phone activation link, or removing a lost authenticator.

Junto supports one Duo configuration per organization. Connect your MSP parent account once, then map Duo subaccounts to Junto companies. Every read and recovery action runs inside one mapped subaccount; the agent never enumerates your Duo accounts or works across customers.

Prerequisites

• A Junto Administrator or Owner account
• A Cisco Duo MSP (parent) account with the customer subaccounts you want to connect
• Administrator access to the Duo Admin Panel for the parent account, with permission to create API applications
• If your Duo API application restricts access by network, the ability to add Junto's IP address (shown in the Junto configuration form) to its allowlist
• Customer companies in Junto, imported from your PSA, to map to Duo subaccounts

Step 1: Create a Duo Admin API Application

1. Sign in to the Duo Admin Panel for your parent account. Create the application in the parent account, not in an individual customer subaccount. Junto uses the parent credentials to discover your subaccounts and then acts within one mapped subaccount at a time.
2. Go to Applications, click Protect an Application, and search for Admin API.
3. Click Protect to create the application.
4. On the application page, copy the Integration key, Secret key, and API hostname (for example, api-XXXXXXXX.duosecurity.com). Store the secret key securely.
5. Under permissions, grant what your workflows require. Reading users, phones, tokens, groups, policies, and logs covers investigation; writing to users and phones is needed for recovery actions. See Duo's Admin API documentation for the current permission names.
6. If the application has a Networks for API Access allowlist, add the Junto IP address shown in the configuration form in Step 2. Without it, Duo rejects every request from Junto, including the connection test.

Step 2: Configure in Junto

1. Go to Settings > Integrations > Cisco Duo.

2. Click Add configuration.

3. Complete the form:

   Field	What to enter
   Parent API hostname	The API hostname from Step 1, such as api-example.duosecurity.com. Enter the hostname only, without https://
   Integration key	The integration key from Step 1
   Secret key	The secret key from Step 1
   Active	Leave enabled to make the integration available to the agent

   The form also shows the IP address Junto connects from. If your Duo application uses a Networks for API Access allowlist, add that address in Duo before testing the connection.

4. Click Create configuration. Junto encrypts both keys when stored and shows only the last four characters of the integration key on the connection card.

5. Click Test connection on the Duo API connection card and confirm Connection successful appears. A successful test reports how many Duo subaccounts the credentials can see.

The connection test is read-only: it lists the subaccounts available to your parent credentials and does not change anything in Duo. A passing test confirms the keys and hostname work; individual features still depend on the permissions granted to the API application.

Step 3: Map Companies

1. Click Map companies on the active configuration. This button is available only while the configuration is Active.
2. For each Junto company, select its Duo subaccount.
3. Click Save mappings.

You can also click Run auto-map. Exact name matches are applied automatically; similar names are presented for review so you can confirm or dismiss them. The dialog shows how many companies are mapped out of the total.

Each Junto company can map to one Duo subaccount, and each subaccount can belong to only one company. To remove a mapping, select Not mapped and save. An unmapped company cannot use any Duo tool, because every Duo request requires a mapped subaccount.

If a saved selection shows (unavailable subaccount), the parent credentials can no longer see that subaccount. Select a current subaccount and save again. If no subaccounts are listed, confirm the integration credentials and the IP allowlist.

Credential changes clear mappings

Changing the Parent API hostname or either key clears all company mappings, because a different Duo account may contain unrelated subaccounts with overlapping identifiers. Map companies again after saving new credentials.

What the Agent Can Do

Capability	What Junto can do	Risk level
Find users	Search one mapped subaccount by username, email, display name, alias, or ID	Low
User details	Read a user's current status, enrollment, last login, lockout reason, groups, and authenticators (phones, hardware tokens, security keys, and desktop authenticators)	Low
MFA coverage roster	Page through every user in a subaccount with status, enrollment, bypass state, and authenticator count for coverage reporting	Low
Authentication and activity logs	Read the newest authentication attempts or administrative activity for the subaccount, or for one user, over a window of 1 to 168 hours	Low
Groups and policies	Read groups and the authentication-method, authentication-policy, new-user, and remembered-devices sections of policies	Low
MFA recovery	Perform one approved recovery step for a user: enable or remove bypass status, create a single-use bypass code, unlink or delete a phone, unlink a hardware token, delete a security key, send a phone activation link or activation SMS, or send an enrollment email	High

All write actions require technician approval before execution. Each recovery step is approved individually, and recovery is never eligible for risk-based auto-approval. MFA recovery requires the Manager role or higher; a request from a lower-level member is routed to a member with that role for approval instead.

Scope and Reporting

• Customer context: Every Duo tool operates on one mapped company at a time. In a ticket or run bound to a company, the agent uses that company's subaccount automatically. In an organization-wide Explore chat, the agent must first resolve which company you mean.
• Where tools are available: Reads are available in Explore chat, ticket work, runbooks, and automated ticket processing. MFA recovery is available only in Explore chat and supervised ticket work, never in runbooks or unattended processing. The MFA coverage roster is available only through Explore chat and connected AI clients; runbooks use user search and user details instead.
• Status is not enforcement: An Active user status alone does not prove MFA is enforced. Group and application policies can bypass MFA separately, so ask the agent to review policy context alongside user details.
• Logs: Duo logs lag by about two minutes, and the agent waits at least a minute between refreshes. An empty result covers only the requested window. Activity logs filtered to one user are matched locally, and sensitive change details are excluded.
• Result limits: User searches scan the complete subaccount inventory; if Duo cannot return it completely, the search fails rather than reporting a misleading empty result. Log requests return up to 100 of the newest events.
• Read-only areas: Groups and policies are inspected, never modified. The agent does not create users, change group membership, or edit policies.
• MFA coverage audits: Once a company is mapped, Duo also feeds the MFA coverage check in Junto-built workspaces. Users who are not enrolled in Duo are flagged, and users whose Duo status is Bypass are flagged separately. Duo results are combined with Microsoft 365, Google Workspace, and CIPP findings rather than replacing them.

MFA Recovery

The agent performs one recovery step per approval and submits each change to Duo exactly once. Before the approval card is created, the agent reads the user's current state; after approval, it checks that the user, company mapping, credentials, and security state are unchanged. An approval expires after 15 minutes. If anything changed or the approval expired, the agent asks for a fresh approval instead of proceeding.

• Prefer a single-use bypass code. A bypass code expires after a short lifetime (1 to 60 minutes, 10 minutes by default). Bypass status, by contrast, disables MFA for the user indefinitely and never expires on its own.
• Bypass status requires a ticket. Enabling bypass or restoring active status must happen in ticket context. Junto records an internal note on the ticket before the change and keeps reminding the technician to restore normal enforcement. Only a fresh Duo read confirming active status clears the reminder; a successful login or elapsed time does not. If you restore the user in the Duo Admin Panel instead, ask the agent to recheck the user from the ticket so the reminder is cleared.
• Secrets go through Secure Send. Generated bypass codes and activation links are never shown in chat or ticket notes. The agent requires a named recipient and delivers the secret through a single-view Secure Send link that expires after one hour.
• State checks. Bypass can be enabled only for an active user, and restoring active status only removes bypass; it never re-enables a disabled or locked-out user. Enrollment email is only for users who are not yet enrolled and have an email address.
• Shared phones. A phone shared by more than one user can only be unlinked from the selected user. Deleting or activating a shared phone is blocked.
• Delivery is not confirmed. Activation SMS and enrollment email are handed to Duo for delivery; Duo does not confirm receipt.
• Uncertain outcomes. If a change times out, the agent does not retry. Ask it to reread the user and authenticators, or check the Duo Admin Panel, before requesting another approval.

Example requests:

• "Find alice@acme.com in Acme's Duo and show her status and authenticators."
• "Why is Bob at Acme failing Duo pushes? Check his authentication logs for the last 24 hours."
• "Review Acme's Duo groups and policies to see whether MFA is enforced for the Sales group."
• "Create a 10-minute single-use Duo bypass code for Alice and send it to her with Secure Send."
• "Send a Duo activation link for Alice's new phone."
• "Remove Alice's Duo bypass now that her phone is activated, then confirm she is active."

Managing the Connection

• Update credentials: Click Edit, enter the replacement values, and click Update configuration. Leave Integration key and Secret key blank to keep the stored values. Changing the hostname or either key clears company mappings; map companies again afterward and test the connection.
• Pause the integration: Click Edit, turn off Active, and click Update configuration. The agent loses access to Duo while the credentials and mappings stay saved. Mapping cannot be edited while the configuration is inactive.
• Remove the integration: Click Disconnect, then Disconnect configuration. This removes Junto's saved credentials and all Duo company mappings. Existing Duo users and devices are unchanged.

Troubleshooting

• Connection test fails: Recheck the Parent API hostname (the api-....duosecurity.com value, with no https://), the integration key, and the secret key. If the Duo application restricts access by network, confirm the Junto IP address shown in the configuration form is allowed. An authentication or permission error indicates a key, permission, or allowlist problem; a rate-limiting error means Duo is throttling requests and you should wait before retrying.
• Connection passes, but a feature fails: Grant the missing permission on the Admin API application in Duo. Read failures usually indicate missing read permissions; recovery failures usually indicate missing write permissions.
• The agent says the company is not mapped: Open Map companies, select the company's Duo subaccount, and click Save mappings. The configuration must be Active to save mappings.
• Duo tools do not appear: Duo tools become available once the configuration is active and at least one company is mapped.
• No subaccounts listed when mapping: Confirm the credentials belong to the parent account and that the connection test passes. An individual subaccount's Admin API application cannot list subaccounts.
• User search returns nothing: Confirm the spelling, alias, and company with the technician. An empty result means no match in the selected subaccount; the agent will not switch tenants or create a user to work around it. A discovery or permission error is incomplete evidence, not a confirmed absence.
• Recovery asks for a fresh approval: The user's state, the company mapping, or the credentials changed after approval, or more than 15 minutes passed. Ask the agent to reread the user and request approval again.
• Recovery asks for a ticket: Enabling or removing bypass status must run from a ticket so the internal reminder can be recorded. Open the request from the customer's ticket.
• Bypass reminder will not clear: The reminder clears only when a fresh Duo read shows the user active after bypass was observed. Ask the agent to check the user from the ticket. If the original bypass attempt was uncertain and bypass was never observed, review the user in the Duo Admin Panel and record the outcome in the ticket.