How to migrate from Okta to Keycloak
Map every Okta app, build a Keycloak realm, federate or broker users, move apps one at a time with a way back, then retire Okta. What users see at each step.
- Collaboration and identity
- 7 steps
In short
- Okta never returns passwords or their hashes, so people either keep the password their directory already checks or set a new one once in Keycloak.
- Second factors do not move: Okta Verify stays with Okta, and security keys and passkeys are bound to the site they were registered with.
- Okta can stay the identity provider behind Keycloak while applications move one at a time, each with its previous Okta settings kept as the way back.
- Okta is switched off only once its System Log shows no more sign-ins to the applications that moved, and the log is exported first: Okta keeps it for 90 days.
On this page (10)
Moving from Okta to Keycloak is a re-wiring, not a data export. Users and groups can be read out of Okta through its API and every application is rebuilt as a Keycloak client, but passwords and second factors stay behind. The work is mapping the applications, deciding where passwords will be checked, and moving applications one at a time with a way back. This guide covers the order we do it in, and what people see at each stage.
Why teams move from Okta to Keycloak
Three reasons come up again and again.
- The key to every other system. Whoever runs sign-on can open every application behind it. Keycloak runs on machines you control, in the country you choose.
- No per-user bill. Okta is priced per user per month. Keycloak costs the machines it runs on and its operation, so contractors, students and partner accounts cost nothing extra.
- Internal applications stay internal. Keycloak can answer on your private network, next to your directory, so the login page of an internal tool is never published to the internet.
What you give up is real: Okta’s catalogue of thousands of pre-built integrations, Okta Verify push with adaptive policies, and provisioning into SaaS applications from its console. Keycloak speaks OIDC and SAML to any application that supports them and enforces one-time codes, security keys and passkeys per group. And someone has to run it, which is the part Pilae takes on.
Step 1: map every application that signs in through Okta
The applications decide the length of the project, so list them first.
- Export the app list. In the Okta Admin Console, Applications and Resources, then Applications, lists every app integration, and each one’s Sign On tab shows how it signs people in. The API returns the same list (
GET /api/v1/apps), and/api/v1/apps/{appId}/usersand/groupsreturn who is assigned to each. - Find the live ones. The System Log records a
user.authentication.ssoevent each time someone opens an app through Okta. Okta keeps the log for 90 days, so export it now. - Record each app’s wiring. For OIDC, the redirect URIs, scopes and claims. For SAML, the entity ID, assertion consumer URL, NameID format and attribute statements. For both, what the app matches accounts on: email, username, NameID or Okta’s subject identifier.
- Flag what has no direct equivalent. Apps on Secure Web Authentication (SWA), where the Okta Browser Plugin fills in a stored password, use neither OIDC nor SAML: their credentials move to a password manager such as Vaultwarden. Apps that Okta provisions accounts into need their own answer, because Keycloak does not push accounts into SaaS applications out of the box.
- Name an owner and a test account per group for every app you keep.
Step 2: find out where passwords and second factors live
This step decides what people experience. Read the users through the API (GET /api/v1/users) and look at each person’s credentials.provider.type, which Okta documents as the provider that validates that user’s password.
| Provider type | Who checks the password | In Keycloak |
|---|---|---|
ACTIVE_DIRECTORY or LDAP |
Your directory, through Okta’s agent | The same directory, federated: no reset |
OKTA or IMPORT |
Okta | Nothing to carry over: one reset per person |
FEDERATION or SOCIAL |
Another identity provider | Keycloak brokers that provider directly |
Okta never hands out a password. For a user who has one, its API returns an empty password object (password: {}), which says that a password exists and nothing more; a hash can be written to Okta, never read back. Okta’s password import hook works in the other direction, into Okta. So for people whose password Okta holds, plan one reset each and promise nothing else.
Second factors stay behind in every case. Okta Verify is Okta’s own authenticator, and security keys and passkeys are scoped to the site they were registered with, so they cannot answer for your Keycloak hostname. Authenticator app codes stay behind too: the API shows an app’s shared secret only in the response that enrols it. GET /api/v1/users/{userId}/factors lists what each person has enrolled, which tells you how many people need a security key in hand on the day.
Write the outcome down per group: same password or one reset, and which second factor it enrols.
Step 3: build the realm
A realm holds the clients, users, groups, roles and sign-in flows of one organisation.
| Okta | Keycloak |
|---|---|
| Okta org | Realm |
| OIDC or SAML app integration | OpenID Connect or SAML client |
| Universal Directory | Realm users, or LDAP and Active Directory federation |
| Groups | Groups, read from the directory or created in the realm |
| App assignments | Roles or groups, checked by the app or the sign-in flow |
| Attribute statements and claims | Protocol mappers on each client |
| Authentication policies | Authentication flows and required actions |
| Okta Verify, authenticator apps | One-time codes (OTP) |
| Security keys and passkeys | WebAuthn |
- Choose the hostname once. The token issuer URL derives from it, and security keys and passkeys registered in Keycloak are bound to it.
- Create one client per application from the step 1 record, with protocol mappers that send each application the claims or attributes it read from Okta, under the same names.
- Rebuild access. In Okta, a person reaches an app once it is assigned to them or their group. In Keycloak, the equivalent is a role or group: the application checks it in the token, or the sign-in flow refuses people without it, with the User Role condition and the Deny Access step. Okta group rules do not move: their membership is set in the directory or in the realm.
- Set the second-factor policy per group, with stronger rules for administrators, and connect an SMTP relay for the set-password and enrolment emails.
- Keep the realm as a file in your repository. Partial export, in the Action menu of Realm settings, writes the configuration with secrets masked;
kc.sh exportwrites a full export, with the Keycloak nodes stopped for a consistent copy.
Step 4: federate, broker or import the users
Three ways bring people into the realm, and step 2 decides which one each group uses.
Three ways to bring users into the realm
Federate the directory
When Active Directory or LDAP checks the passwords. People sign in to Keycloak with the password they already have.
Broker Okta
When Okta holds the passwords. People keep signing in at Okta until their group switches, then set a new password once.
Import from the API
When Okta holds the passwords and accounts should exist first. People receive an email to set a password and enrol a second factor.
Federate the directory. In User federation, add an LDAP provider for your Active Directory or LDAP server in READ_ONLY edit mode. Keycloak never imports passwords: validation always happens on the directory server, so people keep theirs. An LDAP group mapper brings the groups across.
Broker Okta during the move. Brokering lets applications move before anyone’s password does. In Okta, create an app integration (Create App Integration, Classic experience, OIDC - OpenID Connect, Web Application) whose sign-in redirect URI is the Redirect URI Keycloak shows for the new provider, and assign it to the groups that will sign in through Keycloak. In Keycloak, add an OpenID Connect v1.0 identity provider from your Okta domain’s discovery endpoint (/.well-known/openid-configuration) with that client ID and secret. Set Okta as the default identity provider of the Identity Provider Redirector in the browser flow, and Keycloak sends people straight to Okta, which still checks passwords and second factors. On each person’s first sign-in, Keycloak creates a local account linked to their Okta identity.
Import from the API. Read users, groups and memberships from /api/v1/users, /api/v1/groups and /api/v1/groups/{groupId}/users, and create them through Keycloak’s Admin REST API (POST /admin/realms/{realm}/users) or a Partial import file. Keep each Okta user ID as an attribute, declared in the realm’s user profile first, because Keycloak ignores undeclared attributes by default. No password comes with them: credentials are set in step 6.
Step 5: move applications one at a time
Start with an internal application people use daily, where an hour of failed sign-ins would hurt nobody. Then move the rest in order of risk.
Moving one application, with a way back
- Record: The app’s current Okta settings go into the runbook.
- Switch: The app is pointed at its Keycloak client.
- Test: Real accounts from each group sign in, get the right role and sign out.
- Watch: The System Log shows nobody reaching the app through Okta.
- Roll back if needed: The recorded Okta settings are restored.
- Keep the way back open. Copy the app’s current Okta settings (issuer or metadata URL, client ID, signing certificate) into the runbook, and leave its Okta app integration active and assigned. Rolling back is restoring those settings.
- Switch to the new issuer, client ID and secret for OIDC, or the new metadata, sign-on URL and certificate for SAML. Some applications accept one identity provider at a time, so switch those in a window. People sign in to the app again once.
- Test with real accounts from each group: sign-in, the right role, sign-out, a disabled account refused.
- Watch for duplicate accounts. Keycloak issues its own subject identifier, so an app that matched people on Okta’s may create a second account. Match on email or username, or re-link accounts before the switch.
- Watch the System Log until it shows no more
user.authentication.ssoevents for the app, then the Okta side can go.
Step 6: switch sign-in and enrol second factors
When a group’s applications have all moved, that group stops signing in at Okta. Move one group at a time, starting with a pilot.
- People whose directory checks the password sign in to Keycloak with it, and enrol a second factor.
- People whose password Okta held receive an email to set one. Credential Reset, on a user’s Credentials tab, sends the Update Password link; for a whole group, a script calls the Admin REST API per user (
execute-actions-email). - Everyone enrols a second factor through the Configure OTP or WebAuthn Register required action. Default actions apply to new users only, so set them on existing users directly.
While Okta is brokered, turn off the automatic redirect when the first group switches: the Keycloak sign-in page then shows its own form and an Okta button to everyone, and each group is told to move from the button to the form on its date. Tell people in advance what they will see: a new sign-in page, their directory password or a link to set a new one, a prompt to register an authenticator app or security key, and one more sign-in per application. Brief the service desk on recovering a lost second factor first.
Step 7: retire Okta
- Check the log. No
user.authentication.ssoevents for the moved applications over a full cycle, monthly jobs included, means Okta is no longer in use. - Export what you keep. The System Log, the app list and the user and group export, before Okta deletes log data older than 90 days.
- Remove the links. Disable the Okta identity provider in the realm, deactivate the app integrations and uninstall the Okta agents from your servers.
- End the contract once the list from step 1 is empty, not before.
Running Keycloak in production
Every realm, session and token signing key lives in Keycloak’s PostgreSQL database, so the database is what gets backed up, with the realm file beside it. Keycloak releases often and its upgrades have changed token handling, so each one is tested against a copy of the realm before it reaches production.
Pilae operates Keycloak this way: daily encrypted backups stored offsite and, on Enterprise, a restore test every month recorded in the console. The Pilae Agent plans each upgrade, tests it against a copy of your realm, waits for your approval and applies it in your window. It runs on your premises or on dedicated machines in Pilae Cloud, answering only on your private network. If you are comparing more broadly first, see our page on Okta alternatives.
Let Pilae run the move
Pilae runs Okta to Keycloak migrations at a fixed price: the application inventory, the realm, directory federation or brokering, the move of each application with its way back, and the switch of every group. Then we operate Keycloak for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us what signs in through Okta today and we will scope it.
Questions
Can we export password hashes from Okta?
Do people have to enrol their second factor again?
Can Okta and Keycloak run side by side during the move?
Is Keycloak open source?
How long does an Okta to Keycloak migration take?
What happens to applications that Okta provisions accounts into?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
