How authentik uses Duo as an authenticator for Duo MFA
A team that already runs Duo and wants authentik as its single sign-on layer does not have to re-enroll every user to get there. authentik uses a Duo stage backed by Duo Auth API credentials and an API hostname, and it can optionally add Duo Admin API credentials so that existing Duo users and their enrolled authenticators are imported rather than created from scratch. The Auth API handles the second-factor checks at login, while the Admin API is only needed for the import and lookup work. This page covers the decisions that come before the build: which Duo edition and licensing your users need, how the Duo stage fits into your authentication flow, how users are matched between the two systems, and the order in which to configure and test everything. The two second-factor methods a Duo user will see are push and passcode. A push sends a login approval request to the Duo Mobile app on the user's enrolled device, and the user approves or denies it. A passcode is a one-time code the user enters from a token, the Duo Mobile app or a text message, depending on what Duo has enrolled for them. Push is usually the faster experience, but it depends on the phone and on Duo's cloud service being reachable, and passcodes give users a fallback when the phone is unavailable. Which methods your users can choose is governed by what is enrolled in Duo and by the policy you set in the flow, so confirm it with a pilot group before you change the default. Before you change anything in production, confirm three things with your Duo administrator: that your Duo license includes the features authentik needs for automatic user import, that the Admin API is available on your plan, and that the hosts running authentik can reach Duo's API hostname. Export a list of existing Duo usernames and compare them with the usernames in your authentik directory, because a user who already exists in Duo with the same username cannot be enrolled a second time without the Admin API. Then build the Duo stage, attach it to a test flow, and verify push and passcode logins with a small set of accounts before you require Duo for everyone.
What you need before connecting authentik to Duo
Connecting authentik to Duo depends on four things lining up: Duo credentials, a Duo license tier that matches the import you want, network paths from your authentik server to Duo, and an authentik release your team can keep patched. Check each item before you create the stage, because a missing credential or license usually shows up later as a failed enrollment rather than a clear error.
Duo application and Auth API credentials
The authentik Duo stage needs a Duo Auth API integration key, secret key and API hostname. Create the application in the Duo Admin Panel for the authentik stage and record these values before you open authentik. The Auth API is what performs push and passcode checks, so it is the minimum you need for Duo to work as a second factor. Store the secret key in your secrets manager, not in a shared configuration file, and confirm which Duo tenant the hostname belongs to.
Optional Admin API credentials
Admin API credentials are optional, but they are required if you want authentik to read existing Duo users and authenticators during enrollment. The Admin API is available to paying Essentials, Advantage and Premier customers, so confirm your Duo edition before you plan a migration. Create a separate Admin API application with the narrowest permissions your import needs, and rotate its secret after the migration if it is no longer required.
Duo MFA or higher license for import
authentik imports existing Duo users automatically only when a Duo MFA or higher license is active. Without the Admin API, a user who already exists in Duo with the same username fails to enroll. Ask your Duo account team or reseller to confirm which license your tenant holds and whether it includes the features you expect. Because Duo sells self-service licenses in increments of 10 users below 100 and 25 above 100, size the license to the population you will import.
Outbound reachability to Duo
Second-factor checks depend on your authentik server reaching Duo's cloud service. If you route MFA through the Duo Authentication Proxy for RADIUS or LDAP clients, the proxy communicates with Duo over TCP port 443 and keeps persistent outbound connections. Test that the authentik server, and any proxy host, can reach your Duo API hostname over port 443 through your firewall and egress proxy. Confirm this from the same network segment that authentik uses in production.
Supported authentik release and deployment
Confirm the authentik version you run against the supported release lines in the security policy, which currently list 2026.5.x and 2026.8.x for security fixes. Also confirm your deployment shape: Docker Compose suits test and small production setups, while Kubernetes with a separately managed PostgreSQL is the recommended production pattern. Plan the Duo stage around a version you can keep patched, because security releases are announced at least 24 hours in advance.
Configuring the Duo stage and enrolling users step by step
This sequence takes an authentik administrator from a Duo stage with working API credentials to a pilot user who has enrolled a Duo push or passcode and signed in with it. Each step ends with a check that confirms the stage, the flow binding or the enrollment is working before the next step starts.
Confirm the Duo account and API applications
Before touching authentik, the Duo administrator confirms that the account has an active Duo license and creates an Auth API application that authentik will use for second-factor checks. Ask whether the organization also wants an Admin API application, because it is needed later for importing existing Duo users. Record the Auth API integration key, secret key and API hostname in your secrets store, not in a shared document. Done when the Auth API application appears in the Duo admin console with its hostname and both keys are stored where the authentik administrator can retrieve them.
Create the Duo authenticator stage
In the authentik admin interface, the administrator creates a Duo authenticator setup stage and enters the Auth API integration key, secret key and API hostname. The Admin API credentials are optional at this point, so leave them empty unless you have already decided to import existing Duo users. Check the stage's saved settings against the values in Duo. Done when the stage saves without errors and a test enrollment from an administrator account can reach Duo's service.
Enable the Admin API for user import
If the organization wants existing Duo users and their authenticators to carry over, the administrator adds the Admin API integration key and secret key to the same stage. The Admin API application must be one that the Duo plan supports for this feature, so confirm the plan with Duo before relying on it. Duo's documentation describes an Admin API that can read users and authenticators, which is what the import depends on. Done when the stage shows the Admin API credentials saved and a test lookup for a known Duo user returns that user's record.
Bind the stage into an authenticator validation flow
The administrator adds the Duo stage to an authenticator setup flow and binds it, together with an authenticator validation stage, into the login flow used by the pilot group. Use a dedicated pilot group or a test application so the change does not affect every user. Confirm the order of stages so that the primary password check runs first and the second factor follows it. Done when the flow diagram shows the Duo stage in the intended position and the binding is limited to the pilot group.
Import existing Duo users if required
With the Admin API configured and a Duo MFA or higher license active, authentik can import existing Duo users when they first sign in, provided their authentik username matches. Without the Admin API, a user who already exists in Duo with the same username will fail to enroll, so run this step only after the import path has been tested. For a large population, check Duo's Admin API limits on bulk creation before planning the import. Done when a pilot user who already exists in Duo signs in without a second enrollment and the user appears once in the Duo admin console.
Enroll a pilot user with push and passcode
A pilot user signs in to authentik with a password, is directed to Duo, and enrolls a device for push. The same user then enrolls or uses a passcode to confirm that both methods work with the stage. Check that the enrollment appears under the user in the Duo admin console and that the authentik audit view records the enrollment event. Done when the pilot user can approve a push and enter a passcode, and both are visible in Duo's logs.
Test login and record the result
The administrator signs out, starts a new login as the pilot user and completes the Duo challenge. The test should also cover a failed attempt, such as a declined push or a wrong passcode, to confirm that the flow denies access. Record the stage settings, the flow name, the pilot group and the test results in your change record so the rollout can be repeated for other groups. Done when a successful login and a denied login both behave as expected and the change record is complete.
How existing Duo users are imported into authentik
Automatic import of existing Duo users depends on two things: a Duo MFA or higher license that is active on your Duo account, and Duo Admin API credentials configured in the authentik Duo stage. The Auth API credentials and API hostname are enough to enroll users one at a time, but without the Admin API, enrolling a user who already exists in Duo under the same username fails. Confirm the license edition with your Duo account owner before you plan the cutover, because the Admin API is only available to paying Essentials, Advantage and Premier customers, and the Free tier cannot supply the import path. Treat the Admin API key as a privileged secret: give it read and write scope only for the objects authentik needs.
What moves across is the set of Duo users and their enrolled authenticators, such as phones and hardware tokens, so that existing Duo Mobile or token enrollments are not repeated by every user. Usernames are the join key, so the username in authentik must match the username in Duo exactly, including case and domain suffixes. Before cutover, export the user list from Duo, compare it with the authentik user store, and resolve duplicates, retired accounts, and users who are in Duo but not in your directory. Decide which system owns the username, and confirm which users must enroll fresh because their device has changed. Test the import with a small pilot group and a user who has a phone and a hardware token.
For large populations, plan around the Duo Admin API bulk user creation limit of 50 calls per minute with at most 100 users per request. At that rate, the number of requests and the minutes they take are simple arithmetic on your user count, so a directory of several thousand users needs a scheduled window rather than a single run. Ask your implementation partner or internal team to script the import in batches, record failures per batch, and rerun only the failed usernames. Schedule the cutover so that users can still log in through Duo during the transition, and keep the Duo tenant available until every user has been verified in authentik.
Mapping authentik users, groups and Duo identities
This table compares each identity object across authentik and Duo, showing which values must match exactly for import and login to work and which need manual reconciliation. Read it before enabling the Duo Admin API so that existing users are linked rather than rejected as duplicates.
| Identity object | What must match | Manual reconciliation needed |
|---|---|---|
| Username | Duo username must equal the authentik username exactly, including case as Duo stores it; without the Admin API, an existing Duo user with the same username causes enrollment to fail | Rename conflicting accounts in one system before import, and confirm the case rule with a test user |
| Email attribute | Email is not the matching key for the Duo stage; confirm which attribute your Duo records and authentik users carry before relying on it | Check for users with shared, role or former-employee mailboxes that Duo may already hold under another name |
| Duo user record | Created or imported once per person; the authentik user should map to exactly one Duo user | Merge or delete duplicate Duo accounts created by earlier pilots or manual enrollment |
| Groups to flows and policies | Only users in the group bound to the Duo stage through a flow or policy are challenged; group membership in authentik is the control point | Duo groups do not drive authentik enforcement; review nested or legacy groups that may skip the binding |
| Duo phones | Phone numbers in Duo are device data, not login identifiers; imported phones attach to the matching Duo user | Verify numbers are current, remove retired devices and confirm ownership before users rely on push |
| Hardware tokens | Imported Duo hardware tokens must belong to the matching Duo user to appear in the authentik device list | Reconcile serial numbers and reassign tokens from departed staff; tokens cannot be inferred from names |
| authentik authenticator devices | Each Duo device an authentik user enrolls or imports is stored against that user's authentik account | After import, confirm each user sees the expected devices and remove stale entries in the authentik admin interface |
| Duo license tier | Automatic import of existing users requires a Duo MFA or higher license to be active | Confirm the tier with Duo before planning the import; without it, plan manual enrollment per user |
Securing Duo credentials and the login flow
The Duo stage holds credentials that can read and change your user directory, so its security depends on how those keys are stored, how far the Admin API integration reaches, and who can edit the flows that decide when Duo is asked. The cards below cover those controls in the order most teams encounter them during a build, plus the one case where the Duo Authentication Proxy enters the picture.
Store Duo keys as secrets
The Auth API secret key and, if you use import, the Admin API secret key should live in a secret store or an environment variable supplied at runtime, not in a flow export, a Git-tracked blueprint or a shared configuration file. Check that blueprints and backups do not carry the key values in clear text, and that the Duo stage's API hostname is recorded alongside the keys so rotation is repeatable. Confirm the rotation process with your secret store owner before go-live.
Scope the Admin API integration
The Admin API integration can create, update and delete users and authenticators, which is far more than the Auth API needs. Create a dedicated Admin API integration in Duo with only the permissions that the one-time import requires, and leave it out of the running configuration once the import is complete if your team does not need ongoing sync. Record who created the integration, when, and which Duo tenant it belongs to.
Restrict who edits authenticator stages
Anyone who can edit the Duo authenticator stage or the flow that binds it can remove the second factor or point it at a different Duo tenant. Limit edit rights for authenticator stages and flow bindings to a small named group of authentik administrators, and require a second reviewer for changes to Duo settings. Review the audit trail after each change window and alert on edits to stages that reference Duo.
Require Duo on the right flows
Bind the Duo stage to the authentication flow that every user passes through, not only to a flow that some users reach. Include administrator accounts and any group with access to the authentik admin interface, since those accounts can change the rest of the login path. Check the policy bindings on each flow in a test account that belongs to each group, and confirm that a user who has not enrolled in Duo is handled by the not-configured action you intend.
Keep the Duo proxy out of scope
The Duo Authentication Proxy is needed only when LDAP or RADIUS clients must trigger a Duo second factor, because those protocols do not call authentik's flows directly. For browser and OIDC or SAML applications, authentik's Duo stage calls Duo's service without the proxy, so do not install the proxy by default. If a legacy client does require it, plan a separate host with outbound access on TCP port 443 and the supported operating system versions, and treat it as its own security boundary.
Common Duo enrollment and login failures
This table lists the failures teams most often hit when binding a Duo stage to authentik, with the likely cause and the first check for each. Read it in order during rollout, since several failures only appear after the stage is bound to a flow.
| Failure | Likely cause | Check or fix |
|---|---|---|
| Enrollment fails for a user who already exists in Duo | The Admin API is not configured, so authentik cannot link the existing Duo user with the same username and enrolls a duplicate. | Add Duo Admin API credentials to the stage, then retry enrollment. Confirm the username matches the Duo account exactly. |
| Existing Duo users are not imported | No Duo MFA or higher license is active on the Duo account, so automatic import does not run. | Check the license tier in the Duo admin console. Confirm with Duo which plan includes the Admin API and import before go-live. |
| Bulk import stops or slows partway through | Duo's Admin API bulk user creation is rate limited to 50 calls per minute with at most 100 users per request. | Split the import into batches sized to the limits, and pace runs so they stay under 50 calls per minute. |
| Duo API unreachable from the authentik server | Outbound HTTPS to the Duo API hostname is blocked by a firewall, proxy or DNS issue on the authentik host or worker. | Test outbound connectivity to the API hostname from the server and worker containers. Check the API hostname value in the stage configuration. |
| Duo push or passcode check fails for a user who has an account | The username in authentik does not match the username in Duo, so Duo cannot find the matching account. | Compare the authentik username with the Duo username for the same person. Correct the mapping or the source attribute, then retest. |
| Users locked out after the stage is bound | The Duo stage was added to a login flow or validation stage without a path for users who have not enrolled, so they cannot complete the flow. | Confirm how unenrolled users are handled before binding the stage. Test enrollment with a pilot account and keep an administrator path to recover accounts. |
| Duo prompts fail only for LDAP or RADIUS clients | The Duo stage is bound to the web login flow but not to the bind flow used by LDAP or RADIUS clients. | Review which flow each client uses and bind the second factor to that flow. Test one client at a time. |
Testing Duo with a pilot group before requiring it
Run a pilot with a small group of users and one administrator account before Duo is required at login for everyone. Choose pilot users who represent the real mix of devices and roles, including at least one person who uses a phone the Duo Mobile app has not been installed on, and keep a separate administrator account that can change the authentik Duo stage and the flows that call it without depending on the pilot users. Test both push and passcode enrollment and login, and confirm which authenticator the Duo stage offers first, since that order determines what users see by default. Test fallback behavior deliberately: deny a push, let it time out, enter a wrong passcode several times, and confirm what authentik shows the user at each step.
Check audit trails in both systems for the same test logins. In authentik, confirm the login events and the Duo stage outcomes appear in the event log for each pilot user. In the Duo admin console, confirm the authentication logs show the matching push or passcode events, and that any users imported through the Admin API match the usernames authentik expects. Where an identity exists in Duo but not in authentik, or the reverse, record the mismatch before enforcement. Agree in advance who reviews these logs and how long the pilot runs. Your own team should set that duration based on how many users and scenarios need to be covered, and your partner or Duo's documentation should confirm any limits that apply to your plan.
Write the rollback plan and the user recovery path before you enforce anything. Rollback means being able to remove Duo from the login flow quickly, through the stage binding in authentik, while keeping the pilot users' accounts intact. Recovery covers users who lose or replace their phone: decide who verifies identity, whether a Duo administrator can reset or remove a device in the Duo admin console, and what temporary access, if any, you permit. Enforcement should follow a successful pilot in which these paths have been tested end to end, not a pilot that only proved push works. Confirm the exact steps with your Duo account team and your authentik administrators, and document them where your help desk can find them.
Duo MFA with authentik: cost, effort and ownership questions
What drives the cost of adding Duo MFA to authentik?
The cost has three main parts: your Duo edition and seat count, your authentik edition, and the scope of the work. Duo prices per user per month, with Duo Free at $0 for up to 10 users, Essentials at $3, Advantage at $6 and Premier at $9, according to Duo's pricing page. Self-service licenses are bought in increments of 10 below 100 users and increments of 25 above 100 users, so your seat count rounds up to those steps. authentik's Open Source edition is free, while Enterprise is listed at $5 per user per month billed annually plus $0.02 per external user per month, per the authentik pricing page. Services fees depend on how many flows, directories and user groups must be configured and tested. Ask any partner for a fixed-scope quote that names each of these items.
Does importing existing Duo users require a paid Duo license?
Yes. authentik can import existing Duo users automatically only when a Duo MFA or higher license is active, according to authentik's Duo stage documentation. Without the Duo Admin API, enrolling a user who already exists in Duo with the same username fails. The Admin API is available to paying Essentials, Advantage and Premier customers, according to Duo's Admin API documentation. Confirm your current Duo edition with your Duo administrator before planning the import, because the answer changes the migration steps for existing users.
How long does a Duo MFA rollout with authentik take?
Duration depends mainly on the number of users, the number of login flows that require Duo, and whether existing Duo users must be imported. A small pilot with one flow and a handful of test accounts is quicker than a rollout that covers several applications, directories and user groups. Bulk user creation through the Duo Admin API is limited to 50 calls per minute with at most 100 users per request, so large imports take longer and should be scheduled. DeployOpen does not publish timelines; the written scope will set the schedule, and you should ask for milestones tied to pilot, import and cutover.
What does our team need to provide before an engagement starts?
Plan to provide four things. First, Duo administrator access, including the ability to create Auth API and Admin API credentials and to confirm the API hostname. Second, a licensing decision: which Duo edition you will hold and whether you need automatic import. Third, a group of pilot users who can test push and passcode logins across devices. Fourth, a change window for cutover, along with a rollback plan that your operations team approves. You should also name who signs off on flow changes and who owns the Duo and authentik accounts after handover.
Can our internal team set up Duo MFA with authentik alone?
Often yes, if your team already operates authentik and has a Duo administrator. The core work is creating Duo API credentials, configuring the authenticator stage in authentik, binding it to the right flows, and testing enrollment and login. The harder parts are importing existing users without enrollment conflicts, testing fallback behavior for users without a device, and documenting how MFA behaves for LDAP and RADIUS clients. If your team has no recent authentik flow experience, a fixed-scope partner engagement can shorten the learning curve. Either way, assign a named owner for Duo licenses, credentials and the change record.
What recurs after go-live for Duo with authentik?
Three costs recur. Duo licensing is billed per user per month, so every new hire adds seats and every leaver should free one, subject to Duo's increment rules. Upgrades to authentik are ongoing, and the authentik security policy lists 2026.5.x and 2026.8.x as the supported versions receiving security fixes, with security releases announced at least 24 hours in advance. Duo API credentials also need periodic rotation under your own policy. Ask any partner whether upgrades, credential rotation and monitoring are included in a retainer or billed separately.
What breaks if Duo cannot be reached from authentik?
Second-factor checks depend on reaching Duo's cloud service. The Duo Authentication Proxy, which sits in front of LDAP or RADIUS clients, communicates with Duo over TCP port 443 and keeps persistent outbound connections, so a blocked or unstable path stops those logins. Plan outbound access from every host that runs the proxy and test it during the pilot. Also decide in advance how administrators will handle an outage, including who can approve temporary bypasses and how those bypasses are logged, so your team is not improvising during an incident.
Does Duo MFA meet our compliance requirements on its own?
No single product certifies compliance. DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations. For Duo MFA, gather evidence such as the enforced login flows, the authenticator configuration, the list of users and devices, and the admin log history. Confirm with your auditor which controls apply to your sector and whether Duo's own compliance documentation covers your edition.
How DeployOpen scopes and delivers Duo MFA for authentik
DeployOpen treats Duo MFA for authentik as a written, fixed-scope piece of work covering the Duo stage, the credentials and license decisions, and the login flows that enforce it. Each engagement is planned, built, tested and handed over inside infrastructure you control.
How we scope
- Confirm which Duo edition and license level your account holds before committing to automatic user import.
- Record which authentik flows and applications will require Duo, and which clients stay on other factors.
- Agree in writing whether the Duo Authentication Proxy is in scope for LDAP or RADIUS clients.
How we build
- Configure the Duo stage with Auth API credentials and the correct API hostname in a non-production authentik instance first.
- Add Admin API credentials only when existing Duo users must be imported, and test enrollment for a user already present in Duo.
- Test push and passcode enrollment, lockout behavior and recovery paths before enforcing Duo on production login flows.
How we hand over
- Deliver the written configuration record, including credential storage locations, stage bindings and the flows that call them.
- Document the rollback steps, the user enrollment procedure and the support path for users who lose access to their Duo device.
- Walk your operations and security teams through monitoring of Duo authentication logs and failed-login alerts.
How we support
- Offer ongoing support, upgrades and continuous testing for authentik and the Duo integration as a retainer.
- Re-test the Duo stage after each authentik upgrade, since release notes can change flow and stage behavior.
- Review Duo credential rotation and Admin API permissions on a schedule you agree with us in the written scope.
