Learn Authentik - Migration from Other IdPs

#Introduction

After 28 episodes, you're already skilled at building, securing, and troubleshooting Authentik. Now comes the most realistic scenario in the working world: migration. Many organizations move to Authentik from Keycloak, Authelia, Dex, or commercial providers like Auth0 and Okta — whether for licensing, cost, complexity, or ease of UI-based configuration.

Migrating an identity provider is like moving house: you don't carry the entire contents of the home in one trip during heavy rain. You move items room by room, make sure each room works, and keep important boxes within easy reach in case you have to go back. This episode organizes that moving strategy — from planning to cleaning up the old house.

#Strategy: Gradual Move, Not Big Bang

The biggest mistake in IdP migration is doing it all at once: turn off Keycloak, turn on Authentik, hope all applications work. One wrong redirect URI can kill login for the whole organization with no way back. Instead, choose cutover per application: both IdPs coexist, applications are switched one by one, and each switch is validated before moving on.

The three pillars of this strategy:

1. Parallel running — Authentik and the old IdP run side by side during the transition period.
2. App-by-app swap — switch the smallest, least critical applications first to build confidence.
3. Rollback plan per application — every application knows exactly how to be returned to the old IdP within minutes.

#Exporting Users and Groups

Identity is the main asset being moved. The export method depends on the source:

• Keycloak — export the realm via the Admin REST API or a realm JSON file containing users and groups.
• Authelia — users are defined in a YAML config file; groups come along with them.
• Dex — identity generally comes from upstream (LDAP, OAuth), so often no export is needed at all.

Import into Authentik can be done via the ak import_users command inside the worker with a CSV file containing columns like username, email, and name:

docker compose exec worker ak import_users --filename /tmp/users.csv

Before running it, check the options and supported column formats with docker compose exec worker ak import_users --help — each version can behave slightly differently, and a wrong format rejects the entire import.

There's one important thing to understand from the start: passwords can almost never be moved between IdPs. Password hashes are created with different algorithms and salts across systems — an Authelia user file can't directly become Authentik passwords. Realistic options: do the migration with empty passwords and require users to do a recovery/reset at first login, or route authentication to an external source like LDAP (below) so you don't need to move hashes at all.

Groups and their memberships also need to be rebuilt. Mapping roles from the old IdP (for example Keycloak roles into Authentik groups) must be done deliberately, because these group names are what policies and property mappings will reference later.

#LDAP/AD Sync: How to Avoid Exporting Altogether

If the organization already has Active Directory or LDAP, you have an elegant shortcut: don't export users into Authentik, but make AD the source of truth via an LDAP source (episode 17). Authentik will periodically synchronize users, groups, and memberships from LDAP — identities stay managed in AD, and Authentik consumes the results.

This approach removes the password problem (authentication is delegated to the LDAP bind) and makes risky export/import unnecessary. What needs preparing: correct group sync, attribute mapping, and the decision of whether LDAP users may enter Authentik flows without authenticating via LDAP each time.

#Rebuilding Providers via Blueprint

Providers — OAuth2, SAML, proxy, LDAP — are objects that take time if created manually one by one. Use a blueprint (episode 21) to define them as code that can be reviewed and tested in staging first:

version: 1
entries:
  - model: authentik_providers_oauth2.oauth2provider
    id: provider-grafana
    attrs:
      name: Grafana
      client_type: confidential
      authorization_flow: !Find [authentik_flows.flow, [slug, default-provider-authorization-flow]]
      redirect_uris:
        - https://grafana.example.com/login/generic_oauth

Create blueprints for the old and new IdPs with equivalent configuration, then validate in a staging environment before touching production. This also gives you repeatable migration documentation.

#Staging Validation: Sweat in Practice, Not in the Match

The staging environment is where all risks are paid cheaply: create a separate Authentik instance, apply the same blueprints, and run every login scenario production uses — internal login, LDAP login, forward auth, and the main OIDC/SAML providers. One verification that's highly recommended is making sure the new provider's discovery endpoint answers correctly, because applications will rely on it at cutover:

curl -fsS https://auth.example.com/application/o/grafana/.well-known/openid-configuration

In staging you also test the uncomfortable thing: rollback. Turn off staging Authentik, return the application configuration to the old IdP, and prove the application logs in again without defects. A tested rollback is the safety net that makes production cutover feel ordinary.

#Swapping Providers Application by Application

When one application is ready to switch, the procedure is repetitive and predictable:

1. Create the equivalent provider in Authentik and bind it to the application.
2. Configure the application to use the new Authentik discovery endpoint — replace the authorization/token endpoints and client ID/secret.
3. Test login from an incognito browser and make sure the claims/attributes the application needs are available.
4. Observe the event logs for several days before switching the next application.

Where possible, keep the redirect URI identical between the old and new IdPs. The same URI means the changes the application must make are smaller, and rollback becomes simpler.

#Cutover and Rollback

Official cutover isn't a single moment, but the last point in a series of per-application switches. During this period, monitor three things: successful login volume per application, the number of failed logins, and the alerting from episode 25. A sharp drop in successful logins after a switch is the first alarm.

Minimal rollback plan: for each application, document the steps to return the IdP configuration to the old values. Because both IdPs are still alive during the transition, rollback is just changing the application configuration back — without bringing something already turned off back to life. Only after several observation cycles (for example 2-4 weeks) with clean metrics can the old IdP be shut down.

#Pitfalls to Avoid

Some of the most commonly encountered failures during migration:

1. Redirect URI mismatch — the new URI isn't registered exactly; the application rejects at the final stage.
2. Old sessions don't move — users already logged in at the old IdP stay authenticated there; a mass logout from applications may be needed so they don't get "stuck" on old sessions.
3. Signing keys and metadata change — SAML service providers holding old metadata will reject new assertions; re-import Authentik's metadata.
4. Matching users by non-unique email — if the export and another source produce duplicate emails, account merging becomes a mess.
5. MFA devices don't move along — TOTP/WebAuthn authenticators are bound to the old IdP account; prepare a re-enrollment process.
6. Different SLO/logout — single logout at the new IdP can have a different scope; communicate this to users.

#Closing

In this episode 29, you learned that IdP migration is a gradual project, not a one-shot event: choosing a parallel running and app-by-app swap strategy, exporting users and groups from Keycloak, Authelia, or Dex while understanding its limits (including passwords that can't be moved), leveraging LDAP/AD sync so export isn't needed, rebuilding providers via blueprints, doing per-application switches with validation, designing cutover and rollback, and avoiding pitfalls like redirect URIs, old sessions, and MFA devices.

Key takeaways:

• A gradual migration with a rollback plan is safer than a big bang.
• Passwords can't be moved between IdPs; use reset or LDAP federation.
• Blueprints turn configuration into testable code.
• Identical redirect URIs simplify swap and rollback.
• Monitor successful/failed logins after every switch.

The long 29-episode journey culminates in one last question: is your system production-ready? In episode 30 — the final episode of this series — we close with Production Checklist & Best Practices: a complete pre-production checklist, best operational practices, common pitfalls, a recap of the entire journey from episode 0, the future of Authentik, and the closing for all 31 episodes. See you in episode 30!