How to export users and devices from Cisco Duo

How to export users and devices from Cisco Duo before the contract ends

If your Duo renewal is approaching, or a sovereignty requirement is pushing you toward privacyIDEA or Keycloak, you need user and device data out of Duo before access ends. Duo data is exported through documented Admin API calls and reports, and the exact scope of each export depends on your Duo edition and API permissions, so confirm it against Duo's current documentation for your plan before you plan the work. Treat that check as the first task in the migration, not an afterthought.

The intake side is documented. privacyIDEA reads users from existing stores through its user ID resolvers, including LDAP and Active Directory, SQL, SCIM and HTTP resolvers, and imports hardware token seeds in formats such as OATH CSV, Yubikey CSV, SafeNet XML and PSKC. Keycloak supports user federation with LDAP and Active Directory and imports realms from JSON. The Duo side is different: your migration team must confirm which objects the Admin API returns for your edition (users, phones, hardware tokens, integrations and authentication logs), which fields are included, and what rate limits apply to a full pull. Ask Duo for the current endpoint list and limits in writing rather than relying on secondhand examples.

Build the inventory as a reconciled set of files before the contract ends. Export users and their identifiers, map each Duo user to a directory record in your AD or LDAP store, and list every enrolled device and hardware token with its serial number so seeds can be requested or re-imported from the vendor where the format allows. Keep a copy of the authentication logs you need for audit, since logs may be retained for a limited period and cannot be recreated later. Record which users are on push, which use hardware tokens and which only use phone-based codes, because each group needs a different re-enrollment path. Have a named owner for the export, a dated checklist and a rehearsal import into a test privacyIDEA or Keycloak instance. For a full migration sequence, see the Duo to privacyIDEA migration guide.

Which Duo data types map to which migration intake format

This table matches each category in a Duo inventory to the privacyIDEA or Keycloak intake it feeds and names who uses the output. Read each row as a planning step, and confirm the export method, file format and limits in Duo's Admin API documentation before you script anything. The main takeaway is that hardware tokens need the most careful handling, because their seeds can only move into privacyIDEA in a supported import format.

Duo data type	Target intake	Who needs the output	Confirm in Duo's Admin API docs
Users	privacyIDEA user ID resolvers (LDAP, SQL, SCIM or flat file) or Keycloak user federation	Identity team, help desk	Which user attributes, status fields and paging behavior the endpoints return
Phones and devices	Re-enrollment worklist for privacyIDEA or Keycloak factors	Help desk, end users	Whether phone records include model, platform and enrollment state, and whether any secrets are returned
Hardware tokens	privacyIDEA token import in OATH CSV, Yubikey CSV, PSKC or SafeNet XML formats	Identity team, security operations, auditors	Whether Duo returns token seeds at all, and if not, how to obtain them from the vendor or inventory
Integrations	Keycloak clients and realm settings, plus privacyIDEA RADIUS and PAM configuration	Identity team, network and platform owners	Which application, RADIUS and LDAP integration records appear in the export, and how their secrets are handled
Authentication logs	Archive in your SIEM or log store, kept separate from both MFA platforms	Security operations, auditors	Retention window, pagination, time range limits and the fields recorded per event

What usually cannot leave Duo and how teams work around it

The Admin API gives you readable records, but credentials and secrets are generally not released as plain data. Each card below names one category that usually stops at the Duo boundary, the workaround teams use, and the limit to confirm with Duo before you set a cutover date.

Enrolled credentials and device secrets

Duo stores the secret material behind enrolled phones and tokens on its side, and that material is not something you should expect to export as a flat file. Treat each user's enrolled factors as a list of what they used, not as portable credentials. Plan for every migrated user to enroll again in the new system. Ask Duo, in writing, which fields the Admin API returns for each device and confirm that no secret value is included in any export you generate.

Push-enrolled app activations

Duo Mobile activations bind a device to a Duo account, and they do not move to another MFA server. Push notifications in privacyIDEA depend on the privacyIDEA Authenticator app, so users enroll that app and do not carry their Duo Mobile setup over. Set a re-enrollment window, announce it, and keep the Duo tenant reachable until the last user has enrolled. Confirm with Duo how long existing activations remain valid once you stop using them.

Hardware token seeds Duo will not release

Some hardware tokens can be moved only if the vendor releases their seed files. Where Duo provides seeds in a supported format, you can import them into privacyIDEA through its supported formats, including OATH CSV, PSKC, SafeNet XML and Yubikey CSV. Where Duo does not release seeds, the token must be reissued, and you should budget a replacement for each affected user. Confirm the export format and whether seed release is offered for your token model before you buy replacements.

Authentication history for audit

Authentication logs are useful for audit and incident review, but they are records of past events, not an active configuration. Export them on a schedule and store them in an archive your security team controls, with the retention period your policy requires. Do not expect the new MFA system to replay old decisions. Ask Duo for the maximum date range and record count one request can return, and for any retention limit on its side.

Integration and application configuration

Each Duo integration holds the keys and settings for a protected application, such as a VPN, a Windows logon or an SSO client. The Admin API can list integrations, but the configuration on the application side must be rebuilt for the new MFA service. Map each integration to the application that uses it, and plan the switch one application at a time. Confirm with Duo which integration fields are readable, so your inventory records the mapping rather than assuming it.

The sequence for a complete export from Duo

This sequence turns Duo's live user, device, token, integration and log data into a verified, encrypted inventory that a privacyIDEA or Keycloak migration can plan against before the Duo contract ends. Each step closes with a check, so gaps are found while Duo is still available to re-query.

Confirm the Duo edition and API access
Ask the account owner which Duo edition and plan the organization holds, and whether the Admin API is enabled for it. Confirm the exact API endpoints and read scopes that the admin application can use, and ask for written confirmation of any rate limits that apply to the account. Create a dedicated read-only Admin API application for the export so the work is traceable and can be revoked afterward. Done when the account owner has confirmed the edition, the scopes and the limits in writing, and a single test request returns a valid response.
Record the admin roles that can read data
List every Duo administrator role that can view users, phones, hardware tokens, integrations and authentication logs, and name the people who hold them. Assign the migration team the least role that still allows each read, and remove any shared or long-lived credentials that are not needed. Keep a dated record of who was granted access and when it was removed. Done when the role list is signed off by the account owner and matches what the test application can actually read.
Pull users and devices into a versioned staging store
Script read-only calls to the Admin API to pull the users and their enrolled devices into a staging store under version control or a dated snapshot folder. Keep the raw JSON responses unchanged, and write a separate normalized file that the migration team can review. Record the total counts for users, phones and other devices at the time of the pull. Done when the counts in the staging files match the totals shown in the Duo Admin Panel for the same moment, and a sample of about twenty records checked by hand matches the console.
Pull hardware token records and map them to target formats
Retrieve the hardware token records from the Admin API and map each serial number, token type and user assignment to the input format the target system needs. For privacyIDEA, check which of its supported seed formats (SafeNet XML, OATH CSV, Yubikey CSV or PSKC) each token can be expressed in, and flag any token whose seed cannot be exported from Duo. Note that seed material may not be retrievable from Duo at all, so confirm this with Duo before planning around it. Done when every token has a status of mappable, needs re-enrollment or unresolved, and the counts add up to the hardware token total in the Duo console.
Export integrations and authentication logs for audit
Export the list of protected applications and integrations, including their names, types and enrollment policies, so the target design can cover each one. Pull authentication logs for the retention window that the organization's audit policy requires, and confirm with the compliance owner which fields they need to keep. Do not treat logs as a substitute for the user inventory. Done when the integration list matches the Duo applications page one for one, and a sample of log entries spot-checked against the console shows the same events, users and outcomes.
Encrypt the export and limit access to the migration team
Encrypt all exported files at rest with keys held by the organization, not stored beside the data. Restrict read and write access to named members of the migration team, and log every access. Keep hardware token seed files in a separate, more tightly controlled location, and delete any intermediate copies once the final inventory is verified. Done when access reviews show only the named accounts, encryption is confirmed on every storage location, and the team lead has signed off the handling record.
Reconcile the inventory before the contract ends
Compare the full staging set with a fresh pull from Duo and resolve every difference, such as users added, disabled or re-enrolled since the first export. Repeat the hand-sampling check on the final version and record the reconciliation result alongside the snapshot. Keep the final inventory as the baseline for the privacyIDEA or Keycloak import plan. Done when the final pull and the staging set agree or each difference has a documented reason, and the account owner accepts the baseline.

How to verify the inventory is complete before cutover

Treat the inventory as unproven until its counts match Duo at a stated moment. Record the time of each export, then compare the number of users, phones and hardware tokens in your files against the figures shown in the Duo Admin Panel for the same date. Accounts change daily, so a small gap is often timing, but every gap should be explained by listing the records rather than by adjusting totals. Check that each hardware token serial appears exactly once and maps to exactly one user. Duplicate serials and unassigned tokens are the usual reason a token imports cleanly but never authenticates. Finally, confirm group membership and integration assignments, because those decide which factor each application or VPN requires. Confirm with Duo's Admin API documentation which objects your plan returns before you rely on any file as complete.

Rehearse the import in a test instance of privacyIDEA or Keycloak, never in production. For privacyIDEA, load the token seed file through the Token and Import tools using the format it was produced in, whether OATH CSV, Yubikey CSV, PSKC or SafeNet XML, and check that each serial appears with the expected token type and state. Connect a user ID resolver to a copy of the directory so that user identifiers resolve to the same accounts Duo used. For Keycloak, rehearse with kc.sh import on a non-production node. The Keycloak import and export guide describes limits on export as a backup mechanism, so treat the rehearsal as a test of the process, not as a restore plan. Keep the logs from each run so that you can compare the results with the production export later.

Run login tests for every factor type in use, with test accounts drawn from each Duo group. For each account, sign in to each relevant application: a VPN through RADIUS, Windows logon or RDP, SSH, and the web SSO applications. Record the result in a matrix of user, factor and application. Include the failure paths, such as a wrong code, a locked token and a lapsed session, because they reveal policy gaps that successful logins hide. Push users need the privacyIDEA Authenticator app, so flag them for re-enrollment, and confirm which seed-based tokens you can carry over and which need re-issuing. Sign off on the matrix before cutover and keep it with the migration record. Confirm with the vendor, rather than assume, whether Duo will release hardware token seeds for your tokens.

How the export differs for privacyIDEA and for Keycloak

privacyIDEA separates two jobs: finding users and attaching tokens. It does not need a full copy of Duo's user directory to start. It reads accounts from the store you already trust, then imports hardware token seeds from files you export from the token vendor or your key management process. That makes the inventory mostly a mapping exercise between Duo user IDs and the identifiers in your directory.

User sources: privacyIDEA reads users through user ID resolvers, including flat file, LDAP (any LDAP service such as Active Directory), SQL, SCIM and HTTP. Match the Duo username to the attribute your directory uses, and record any users who exist in Duo but not in the directory.
Seed formats: Token import accepts SafeNet XML, OATH CSV, Yubikey CSV and PSKC files. The OATH CSV format covers HOTP, TOTP, OCRA and TAN tokens, with serial, seed, OTP length and time step columns, so confirm each hardware token's type before choosing a format.
GPG-encrypted seeds: Seed files can be encrypted with the project's GPG key on import. Treat the decrypted files as secrets, restrict who can read them, and delete working copies after the import is verified.
Phone-based factors: Push and Duo Mobile enrollments do not transfer as seeds. Plan re-enrollment with the privacyIDEA Authenticator app, and note that standard TOTP and HOTP users can keep apps such as Google Authenticator.
Network flows: privacyIDEA covers RADIUS for VPNs, PAM for Linux and the Windows credential provider, so list every RADIUS client and logon type in the Duo inventory against it.

Before the contract ends, confirm with your own token records which hardware serials are still in use and whether your seed files are complete.

Keycloak is an SSO server, so its migration starts with users and realms rather than token files. Its built-in user federation connects to existing LDAP and Active Directory servers, which lets you keep one source of truth for accounts. Duo's second factors then need to be re-enrolled in Keycloak's OTP or WebAuthn flows, since Keycloak does not import Duo's push or device trust state.

Federation: Keycloak has built-in user federation with existing LDAP and Active Directory servers. Map Duo usernames to directory attributes before enabling federation so that accounts do not duplicate.
Realm export: The kc.sh export and kc.sh import commands write and read realms as JSON files. The Keycloak documentation warns that this is limited as a backup and restore mechanism, and that all nodes must be stopped while it runs. Plan a maintenance window and keep your own backups of the database.
Scope limits: Keycloak does not cover RADIUS for VPNs or Windows logon. Those flows must be listed separately in the inventory and assigned to another component, such as privacyIDEA.
Enrollment: Keycloak's OTP and WebAuthn enrollment happens at login, so build a re-enrollment schedule and a help desk path so that users are not locked out.
Data handling: Exported realm files can contain client secrets and credential data, so store them in restricted, encrypted locations and remove them once the import is confirmed.

Before the contract ends, confirm which Duo second factors protect web SSO and which protect network or endpoint logons.

What to plan before the Duo renewal or termination date

A Duo export is the first step of a migration, and its timing depends on contract terms that only your organization can read. The items below connect the calendar, the approvals, the records you must keep and the written requests you send to the Duo account owner before any data leaves Duo.

Work back from the end date

Set the date the export must finish by counting back from your Duo renewal or termination date. Leave room for a dry run against a test instance, a review of the inventory, and at least one correction cycle before the production cutover. Confirm the notice period for non-renewal and any data return or deletion terms in your own contract, rather than assuming they match the standard terms Duo publishes. Record the dates in one shared plan so procurement, security and the help desk work from the same calendar.

Agree who approves data handling

A user and device inventory contains names, email addresses, phone numbers and token serials, so it is personal data that needs an owner. Ask procurement to confirm which contract clauses govern export and deletion, and ask security to approve where the exported files may be stored, who may open them and how long they may stay on a workstation. Document these approvals before the first API call, because the export script will run under an administrator account with broad read access.

Decide what logs you must keep

Duo's authentication logs answer questions that auditors and incident responders ask after a migration, such as who approved a login from an unusual location. Ask your compliance lead which log periods, fields and formats must be retained, and confirm with Duo how far back the Admin API returns authentication records. Plan to copy those records into your own archive, since they will not be readable from a self-hosted MFA server, and label the archive with the date it was taken.

Plan how long enrollments stay valid

During the move, some users will still rely on Duo Mobile or Duo hardware tokens while the replacement is being set up. Decide how long those enrollments remain usable after the cutover, and whether Duo stays active in read-only or fallback mode for a defined period. Make sure the help desk can verify identities without Duo, because a user locked out on the cutover day creates a support load that a written fallback process should prevent.

Request written confirmations from Duo

Ask the Duo account owner to confirm in writing the export scope available under your plan, any API rate limits or access restrictions that apply to your integration key, and how the account will be handled at termination. Request the date after which Duo stops serving the Admin API and the process for certified deletion of your data. Verbal answers from a sales contact do not bind the vendor, so keep the written responses with the contract file.

Name a single owner for the inventory

The user, phone and hardware token inventory is only useful if one person signs off on its completeness before it feeds a privacyIDEA or Keycloak import. Assign an owner who reconciles the export against the directory, checks that every hardware token has a serial and a seed source, and records users who have no current factor. Hand the signed inventory to the migration team as the baseline for the dry run, so every later difference can be traced to a known change.

Questions buyers ask before exporting Duo data

Can we export our Duo users and devices without outside help?

Yes, a team with Duo administrator access and someone who understands the directory can run the export, because the Admin API is documented and the output is plain data. The harder part is judging what the data means. Your team needs to decide which users are active, which phones are still in use, which hardware tokens are assigned to a person, and which integrations still depend on Duo. Teams that have done this before tend to keep an internal owner for the inventory and bring in outside help for the parts they have not done before, such as mapping hardware token seeds into privacyIDEA or designing the cutover. Ask any provider to state in writing which of these tasks they will do and which stay with your staff.

What makes a Duo export take longer or cost more?

The effort follows four drivers: the number of users, the number of token types, the number of integrations and the condition of the directory behind Duo. A small group with only Duo Mobile push and no hardware tokens is a short exercise. A large population with OATH hardware tokens, RADIUS proxies for VPNs, Windows logon and Linux SSH needs more mapping and more testing. Duplicate accounts, stale users in Active Directory or LDAP, and inconsistent usernames across Duo and the directory add reconciliation work that scales with every mismatch. Ask a quote to list each integration by name and each token type by count, because those two lists drive most of the price.

How long does a Duo export and inventory project take?

No single duration applies, and any figure quoted without a scope should be treated with caution. The timeline depends on the user count, how many integrations must be traced, how many hardware tokens need seed files, and how fast your directory owner can answer questions about dormant accounts. A reasonable plan separates the read-only inventory from the later migration, so the inventory can finish while the Duo contract is still active. Ask the provider for a timeline tied to named milestones and to the decision points your team must sign off, not a single total number. Your contract end date should set the deadline for the inventory, and the migration plan should leave room for a parallel run.

What does the team need in place before the export starts?

Four things should be ready before anyone calls the Admin API. First, a Duo administrator account with the permissions needed to read users, phones, tokens and logs, confirmed with your Duo account team. Second, a staging environment where privacyIDEA or Keycloak can be tested against copied data, so production users are not affected. Third, a named directory owner who can confirm which identities in Active Directory or LDAP are current and who should keep access. Fourth, a help desk plan covering how users re-enroll, how lost hardware tokens are handled and who approves exceptions during cutover. Without the help desk plan, the export can be correct and users can still be locked out.

Does an export alone satisfy our audit requirements?

No. A data export shows what identities and devices existed on a given day, but auditors usually also want evidence of the controls around them. That includes how access was approved, how tokens were issued and revoked, how changes were logged and who reviewed the results. The inventory is a useful input to a compliance review, but DeployOpen prepares systems, controls and evidence for assessments and does not issue audit reports or certifications. Independent auditors and certification bodies make those determinations. Ask your auditor early which evidence they expect, and treat the Duo authentication logs as part of the record for the period before cutover.

What does a fixed-scope Duo export engagement cover?

Most DeployOpen engagements are fixed-scope, which means the scope, deliverables and timeline are agreed in writing before work starts. For a Duo export, a written scope would typically name the systems in scope, the data sets to extract from the Admin API, the integrations to be traced, the reconciliation rules against the directory, the format of the user and token inventory, and the handover to your team. It would also name what stays out of scope, such as the cutover itself or re-enrollment support, unless those are added. DeployOpen does not publish a price list. A quote follows from the written scope, so the most useful preparation is an accurate count of users, token types and integrations. Ongoing support and continuous testing are available as separate retainers.

How DeployOpen scopes and delivers a Duo data exit

DeployOpen is a Chainscore Labs company that plans, implements, integrates, documents and supports self-hosted open-source platforms inside the client's own infrastructure. For a Duo data exit, we turn the export into a written, fixed-scope inventory of users, phones, hardware tokens and integrations that your privacyIDEA or Keycloak migration can rely on.

How we scope

Written scope lists which Duo tenants, user groups, phones and hardware tokens are included in the export.
We confirm which Duo plan and API permissions your administrators can use before any extraction starts.
Scope names the target platform, whether privacyIDEA, Keycloak or both, and the identity sources feeding it.

How we build

We build the export scripts against the Duo Admin API and run them under a dedicated, least-privilege read-only account.
Rate limits and paging are handled in the code so large directories export completely and repeatably.
We reconcile exported users and tokens against your directory to flag orphaned accounts, duplicates and unmatched devices.

How we hand over

You receive the user and token inventory in agreed formats, with a documented data dictionary for each field.
Handover documents which records could not be mapped, with the reason and the owner who must resolve each one.
Hardware token seed files are handled under your key management process, and the transfer log is delivered with the inventory.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work begins.
Ongoing support, upgrades and continuous testing are available as a retainer after the export is complete.
A quote follows from the written scope, so ask for the cost components, one-time versus recurring items and assumptions in writing.

How to export users and devices from Cisco Duo