Staged identity provider migration with the authentik source stage: when it fits
The source stage fits when a legacy identity provider still serves users and applications and you need to move them to authentik gradually rather than in one cutover. It sends a user from an authentik flow to an external OAuth or SAML source, such as Entra ID, Google Workspace or Okta, and returns them to the same flow once that source has authenticated them. The effort depends less on the stage itself than on how many applications and user populations depend on the legacy IdP, because each population needs its own flow design, attribute mapping and testing. The source stage is an Enterprise feature, so confirm it against your licensing before you design around it. Much of the rest of a migration, including standing up the server, building providers for applications and moving users, can run on the Open Source edition, which is licensed under MIT for most of the code.
A plain source is often enough when you only need to federate a legacy directory for sign-in and do not need to control how each user passes through it. In that case, a source configured for user login may cover the need without the stage. The source stage adds value when you want to route selected users or applications through the legacy IdP inside an authentik flow, capture attributes on the way back, and set a resume timeout that defines how long the flow waits for the external login to complete. Confirm with your own environment which applications send their users through the legacy IdP at each wave, and which must move to authentik before the flow is safe to change. Those answers determine whether you need the stage at all.
What maps cleanly from a legacy IdP and what does not
This table compares common capabilities of a legacy identity provider with the authentik objects that replace them during a staged migration. Read each row as a question: can the capability move as a provider, source, or property, or does it need rebuilding as a flow or policy?
| Legacy capability | Where it lands in authentik | What to plan |
|---|---|---|
| OIDC and SAML client registrations | OAuth2/OIDC and SAML providers with applications bound to them | Recreate each client, then confirm redirect URIs, entity IDs and signing settings with the application owner before cutover |
| User directory | Users stored in authentik's PostgreSQL database, or synced in from an upstream directory | Decide whether accounts are imported, just-in-time created on first source login, or synced; identify which attributes the apps need |
| Group membership | Groups and group-based policy bindings | Map legacy roles to groups, then check that each application reads the claim or attribute it expects |
| Password verification during cutover | Legacy IdP stays the authority through the source stage, so users keep their existing password | Confirm the legacy IdP supports browser-based OAuth or SAML sign-in; the source stage does not authenticate LDAP or Kerberos-only directories |
| Attribute capture at first login | Property mappings and the source stage's attribute capture, written to the authentik user record | Agree the attribute list up front (for example, email, name, department) and test that each mapping returns a value |
| MFA and step-up rules | Authenticator stages inside the authentik flow, with the legacy IdP's MFA either honored upstream or replaced | Decide whether authentik or the legacy IdP enforces MFA during the transition; the source's own flow must not contain a user login stage |
| Login policies, lockout and conditional access | Policies bound to flow stages and applications | Rebuild each rule as a policy, such as group checks or GeoIP conditions; rules that depend on the legacy IdP's session data need a replacement design |
| Custom login logic and scripts | Flows with expression policies, custom stages or property mappings | Treat each custom script as a rebuild item with its own test cases; scripted logic rarely copies over unchanged |
| Branding per login page | Flow and brand settings in authentik | Plan branding per domain or tenant separately from the migration itself |
Documented paths for moving identity sources and users
authentik documents several ways to bring a legacy identity provider, directory or password store into a migration. Each path answers a different question: how users sign in during cutover, how accounts get created, and whether passwords must change. Confirm each path against your authentik version before you commit to a sequence.
Legacy IdP as an OAuth or SAML source
Register the existing identity provider in authentik as an OAuth or SAML source so users can authenticate against it from authentik's login flow. This keeps the legacy IdP as the system of record while applications move. Check the redirect URIs, metadata and entity IDs on both sides, and confirm which user attributes the upstream provider returns before you map them.
Source stage inside flows
The source stage sends a user to a browser-based source and returns them to the current flow, which is how a staged migration is built. Confirm that the source's own flow does not include a user login stage, and set the resume timeout to match how long a user may take to complete the upstream sign-in. The stage is an Enterprise feature, so check your edition before design.
LDAP and directory sync
When users live in a directory rather than a hosted IdP, authentik's directory sync options determine who exists in authentik before any login happens. Decide whether accounts are pre-created, synced on a schedule, or created on first sign-in, because each choice changes how group membership and attributes arrive. Test the sync with a copy of production-like data and confirm the attribute mappings for your version.
Password hash import for users
Users who should not reset passwords at cutover may be moved with their existing password hashes, using the import path described in the authentik documentation. Confirm which hash formats your version accepts and whether any formats need conversion first. Hashes imported this way are not written back to the legacy directory, so plan for the legacy store to keep its own copy during coexistence.
Blueprints and the password-hash API
Account and provider setup can be scripted with blueprints, and the password-hash API supports bulk loading of credentials. Scripted imports make a migration repeatable across test and production, which matters when a cutover is rehearsed more than once. Store blueprints in version control, review the generated accounts before each run, and confirm the endpoints and file format against the release you deploy.
How a staged cutover runs from inventory to decommission
The sequence moves users from a legacy identity provider to authentik-native login in controlled waves, so each group is verified before the next one is switched. Each step produces a record the next step depends on, and the legacy IdP is retired only after nothing still signs in through it.
Inventory applications, users and attributes
Start by listing every application that signs users in through the legacy IdP, the user populations behind them, and the attributes each application reads from its token or assertion, such as email, group membership and employee ID. Record which applications can be repointed to authentik directly and which need the legacy IdP to remain in the login path during transition. Ask the legacy IdP owner which login methods, MFA factors and session lifetimes are in use, since these affect how users experience the source stage. The step is done when you have a signed-off list of applications, user groups and required attributes, with an owner for each.
Design the source flow and its decisions
Build the flow that will send users through the legacy IdP, using an OAuth or SAML source and the Enterprise source stage. Decide the resume timeout now, because it controls how long the flow waits for the user to return from the legacy IdP, and test it with the slowest realistic login path. Decide which attributes to capture from the legacy IdP during this pass, and map them to authentik user fields or attributes so they persist after cutover. Confirm that the source's own flow does not include a user login stage, since the source stage only works with browser-based sources and that setup would conflict with it. The step is done when the flow diagram, timeout value and attribute mapping are written down and reviewed by the identity and application owners.
Run a pilot with a small group
Bind the new flow to a small, named group of users and a single low-risk application, and ask them to sign in through it while the legacy IdP stays fully operational. Watch for stalled logins caused by the resume timeout, missing attributes in the application, and users who land in the wrong account because of mismatched identifiers. Keep a rollback path that routes the pilot group back to the original login without changes to the application. The step is done when the pilot group has completed normal sign-ins for the agreed test period and each issue found has a fix or an accepted workaround recorded.
Run the parallel period
Extend the source-stage flow to more groups and applications while the legacy IdP keeps authenticating users behind the scenes. During this period, users pass through both systems, so check that accounts are matched correctly, captured attributes are updated on each sign-in, and group-based access in authentik matches what the applications expect. Compare session behavior and MFA prompts between the two paths and document any differences users will notice. The step is done when every application in the inventory has completed the parallel run and the attribute and access checks show no open discrepancies.
Cut over to authentik-native login
Remove the source stage from the login flow for each application and make authentik the sole login path. Users who were captured during the parallel run should now authenticate directly against authentik using their stored identity data, so confirm that credentials, MFA enrollment and recovery options are in place before the switch. Communicate the change to users and keep the legacy IdP reachable for a defined fallback window agreed with the business owners. The step is done when each application signs users in through authentik without the legacy IdP in the path and a fallback procedure has been tested.
Decommission the legacy IdP
Once no application or source flow depends on the legacy IdP, disable the source and stop issuing tokens or assertions from it. Retain the legacy configuration, logs and any exported user data according to your records and retention policy, and confirm this with your compliance owner. Remove service accounts, application registrations and DNS or certificate entries that existed only for the legacy IdP. The step is done when the legacy IdP shows no successful sign-ins over an observation period you agreed in advance, and the removal is recorded in your change log.
Questions buyers ask before a staged IdP migration
Is a plain source enough instead of the authentik source stage?
A plain source is enough when every user can move to authentik in one cutover, or when the legacy IdP can be turned off for a group without users noticing. The source stage matters when users must keep signing in through the legacy IdP while applications move one at a time, and you want authentik to remain the front door throughout. In that case, the source stage sends users to an OAuth or SAML source and returns them to the current flow, so authentik can capture attributes and record the migration as it happens. If your users all sign in through one flow and you can switch them together, a plain source configuration is simpler to build and to test. Confirm which approach fits with a list of applications and their cutover order before choosing.
Does the source stage require an authentik Enterprise license?
Yes. The source stage is an Enterprise feature, so you need an Enterprise subscription for it, while the rest of authentik's code is under the MIT license. The authentik pricing page lists Enterprise at $5 per user per month billed annually, plus $0.02 per external user per month, and Enterprise Plus starting at $20k annually. Enterprise features also include Google Workspace and Microsoft Entra ID integrations, which matter if your legacy IdP is one of those. Ask your team to count licensed users, including the users who will pass through the migration flow, and confirm the current figures on the pricing page before budgeting. Licensing is recurring, so plan for it across the full migration period.
How long does a staged identity provider migration take?
The duration depends on the number of applications, how many of them use a browser-based protocol, how many users must be moved, and how much testing each cutover needs. The source stage works only with browser-based sources such as OAuth or SAML, so applications that rely on LDAP binds or other non-browser paths need their own migration plan that runs in parallel. Other drivers include the resume timeout you configure, because it sets how long a user can leave the legacy login and return, and the number of approval steps your change process requires. Ask for a timeline built from a written scope, and treat any duration without that scope as a guess. Because the work is typically fixed-scope, agree on the application list and cutover order before work starts.
What must our team provide before a staged migration starts?
Your team provides the inputs that decide the design, and missing inputs are the most common cause of delay. Prepare:
- An application inventory with protocol, owner, login path, and the order each app should move
- Attribute mappings showing which claims or SAML attributes each application expects, and where those values come from in the legacy IdP
- Test accounts for each user type, including administrators, contractors and users with unusual group memberships
- The legacy IdP configuration, including client settings, metadata or endpoints, and a named contact who can change them
- Rollback criteria and an agreed window for each cutover
Attribute capture is only useful if the expected values are known in advance, so the mapping list usually takes the most review time.
Can our internal team run a staged IdP migration without a partner?
Often yes, if your team already runs authentik and the legacy IdP, has someone who can write and test authentik flows, and can staff a cutover calendar. The work is mostly flow design, attribute mapping, test planning and coordination with application owners, and a team with those skills can do it in-house. A partner adds value when the team lacks the time or experience in one of those areas, when several legacy systems are involved, or when the migration must be evidenced for an assessment. DeployOpen plans, implements and documents this kind of work inside your own infrastructure under a written scope. Ask any partner for a written scope, deliverables and a dependency list before deciding who does which part.
What breaks most often during a staged migration?
Most problems come from attribute differences, not from the flow itself. Common failures include a missing or differently formatted claim that an application needs for authorization, a user who leaves the legacy login mid-flow and runs into the resume timeout, and a source configuration that includes a user login stage, which the source stage does not support. Also check that the legacy IdP keeps its own sessions and MFA behavior in line with what users expect. Test each application with real and test accounts before moving its users, keep the legacy IdP available until rollback is no longer needed, and record which users have passed through each flow so support staff can answer questions during the cutover.
How do we check that the migration is secure and complete?
Verification should show that each application signs in through authentik, that the attributes it receives match the mapping list, and that users who should have been moved are no longer depending on the legacy IdP. Use test accounts to confirm login, logout, MFA prompts and group-based access, and review audit logs for the flow runs. Enterprise also lists enhanced audit logging among its features, which can help with this review. Confirm your retention and access rules for those logs with your security and compliance team before the cutover. DeployOpen can prepare the test plan and the evidence for these checks, but independent auditors and certification bodies are the ones who issue any audit report or certification.
What usually goes wrong during a staged IdP migration
Staged migrations fail in predictable places: flow routing, login timing, attribute capture and application configuration. The cards below cover the risks that most often surface between the first pilot user and the final cutover, with a prevention step for each.
Users looping between flows
If the source stage sends a user back into a flow that contains the same source stage, or two flows route to each other, the user never reaches the end of the chain. Map every flow transition on paper before you bind flows to applications. Test with a pilot group that has one account in each legacy state, such as a user who already exists in authentik and a user who does not. Confirm that the flow ends with a session the application accepts.
Resume timeouts expiring mid-login
The source stage keeps the user's place in the flow for a configurable resume timeout. If a user must complete MFA, a password reset or a consent screen at the legacy IdP, a short timeout sends them back to the start with no error they understand. Set the timeout against the slowest realistic login path in your environment, including first-time MFA enrollment. Ask the pilot group to report where they were when the flow restarted.
Attributes missing after capture
Users who pass through the legacy IdP may arrive in authentik without the email, group or department values that your applications and policies expect, because attribute capture was not configured on the source or the flow. Compare the claims or assertions the legacy IdP sends with the attributes authentik stores before the pilot begins. Check a migrated account's profile after its first login, and confirm that group-based access still works for it.
Applications still pointing at the legacy IdP
A migration can look finished while some applications still send users to the old identity provider, so accounts keep signing in there and the stage is never exercised. Keep an inventory of every relationship with the legacy IdP, including SAML metadata URLs, OIDC issuers and redirect URIs. Change one application at a time, and check the sign-in logs on both systems for each cutover step before you retire a source.
Source flow includes a user login stage
The source stage only works when the source's own flow does not contain a user login stage. If someone copies a default login flow when building the source flow, users will see a second login prompt or a loop. Review the source flow's stage list before enabling it, and use a test flow with a single pilot application to confirm that the user reaches the login stage only once.
Browser-only sources in headless paths
The source stage relies on the browser being redirected to the legacy IdP and back, so it cannot serve API clients, scripts, mobile apps using non-browser flows or LDAP and RADIUS binds. Inventory which access paths are browser-based before you place the stage in a shared flow. Route non-browser clients to a separate path, and keep their credentials managed until they move to a supported method.
What drives the cost and duration of the move
This table lists the factors that change the effort and cost of a staged migration, whether each one is paid once or recurs, and what to ask for in a written quote. Use it to compare scope options before you request a fixed-scope proposal. The main takeaway is that the number of applications, login logic and the legacy IdP admin team usually matter more than the choice of source type.
| Driver | Why it changes cost or effort | One-time or recurring | What to ask for in a quote |
|---|---|---|---|
| Applications and protocols | Each app needs its own provider or SAML/OIDC client, and each must be tested through the source stage handoff | One-time | Itemized list of apps, protocol per app, and which apps cut over in each wave |
| User populations | Separate directories, domains or groups may need different source routing, resume timeouts and rollout waves | One-time | Count of populations, how each is identified, and the routing rule for each |
| Legacy login logic | Custom scripts, conditional access, or branded pages on the old IdP must be reproduced or retired before users pass through the stage | One-time | Written inventory of legacy login behavior and a decision on what is kept |
| MFA and policy complexity | Step-up rules and factor enrollment must be mapped so users are not prompted twice or left without a factor | One-time, with ongoing policy changes | Mapping of current MFA rules to authentik stages and policies, and who approves changes |
| Attribute mapping depth | Attributes captured at the source stage must match what downstream apps expect, including multi-valued and group data | One-time, with ongoing maintenance as apps change | Attribute list per app and the source-to-property mapping for each |
| Access to the legacy IdP admin team | Source configuration, client registration and metadata exchange need admin time on the old platform, which can set the pace | One-time, sometimes recurring during parallel running | Named contact, change window, and who creates the client on the legacy side |
| Testing scope | Each wave needs sign-in, resume-after-timeout and fallback tests, and the scope grows with the number of paths | One-time per wave, plus regression on later changes | Test matrix covering browsers, protocols and failure paths, and the sign-off owner |
| Parallel running period | Users sign in through two systems while cutover is incomplete, which adds support and monitoring work | Recurring until the legacy IdP is retired | Planned length of the overlap, monitoring responsibilities, and the retirement criteria |
Choosing between the source stage and a plain source
Use a plain source when users can be sent to the legacy IdP once, and accepting a single change of sign-in path is acceptable. In that case the legacy provider is attached as a source and users who choose it are redirected there from the login page, with no additional flow logic to maintain. Use the source stage when users must pass through the legacy IdP inside a larger authentik flow while other users already sign in directly against authentik. The source stage is an Enterprise feature, so confirm licensing before you design around it. The decision usually turns on whether the flow itself has to change for some users, for example when the legacy login must happen before an enrollment, consent or policy step that authentik enforces.
The source stage has a hard limit: it works only with browser-based sources such as OAuth or SAML, so a directory bind such as LDAP cannot be used in this position. Check every legacy system you plan to route through a flow against that limit before committing to the design. The other constraint is structural. The source's own flow must not include a user login stage, because a second login inside the handoff produces a loop or a duplicate prompt. Review the source flow with an authentik administrator who has not built it, and test it with a user who already has an active authentik session. Also set the resume timeout deliberately, since it controls how long authentik waits for the user to return from the legacy IdP. Confirm the exact behavior and defaults for your version in the source stage documentation.
How DeployOpen scopes and delivers a staged IdP migration
A staged migration touches the legacy IdP, authentik flows, every application that signs in, and the users who will be sent through the source stage. DeployOpen treats these as one plan, agreed in writing before work starts and carried out inside your own infrastructure.
Written scope before any build
DeployOpen agrees the scope, deliverables and timeline in writing before work starts. For a staged migration, the scope should name the legacy IdP, the applications moving to authentik, the flows that send users through the source stage, and the user groups in each wave. Ask for the exclusions in writing too, such as applications that will stay on the legacy IdP after cutover.
Flow and source stage design
The work starts with the authentik flow that wraps the source stage, the source's own flow (which must not include a user login stage), and the resume timeout that governs how long a user can stay on the legacy IdP before the flow fails. DeployOpen documents these choices so the flow design can be reviewed by your identity team before any user reaches it.
Attribute capture and mapping
During each sign-in through the legacy IdP, the attributes you need (username, email, group membership, and any custom claims) must be captured and mapped onto the authentik user. Errors here surface later as duplicate accounts or missing group access. DeployOpen tests the mapping with representative users from each group before a wave goes live.
Test waves and rollback
Migration runs in waves, with a test group first and a rollback path for each wave. DeployOpen plans the test cases (new user, existing user, expired legacy session, timeout), the rollback steps for each application, and the evidence each wave must produce before the next starts. Ask for the rollback criteria to be written into the plan.
Build inside your environment
DeployOpen builds and tests the migration in the infrastructure you control, whether that is your cloud accounts, data centers or an air-gapped network. authentik runs as a server and worker with PostgreSQL behind it, so the deployment, backups and access paths are set up in your environment. Confirm who holds administrator access and where configuration is stored.
Documentation and post-cutover support
DeployOpen documents the final flows, mappings, wave records and runbooks so your team can operate them after cutover. Ongoing support, upgrades and continuous testing are available as a retainer, which suits the period after the legacy IdP is retired. Ask what support is included in the retainer and how upgrades to new authentik releases are handled.
