Whatever field or industry your company operates in, you’ll need a way to authenticate users of your systems and applications. Many businesses simply buy an off-the-shelf product such as Okta and forget about the issue, but the reality is that this is often a suboptimal solution. There are better options that let you optimize the long-term operational costs significantly.

Thankfully, migrating from one solution to another isn’t that difficult, and if you play your cards right, you can even do it without affecting the continuity of system operations.

Okta and Keycloak – what are they?

First, let us summarize both tools described in this article:

• Okta – a cloud-based system that offers a wide range of functions related to authentication, authorization and user management. It’s a paid solution, and the price starts from $2/month for one user, depending on the selected product. It’s worth noting that Okta isn’t technically a full-blown Identity Access Management (IAM) solution, but we use this term for the sake of simplicity 
• Keycloak – an open-source identity and access management system with authentication and user management features. Due to the open nature of the solution, the list of its functionalities is virtually unlimited because you can expand the system’s main core with dedicated extensions (plugins). If you want to learn more, we have a detailed article on the advantages of Keycloak SSO. Our take is based on our own experience.  

Here’s a direct comparison of both solutions.

Okta to Keycloak – when should you consider a migration?

In essence, there are two scenarios when it’s worth considering moving from Okta to Keycloak:

1. Significant growth – Okta seems attractive for small companies, startups, etc. – generally, it’s good when the number of users isn’t very high. However, it becomes problematic when your business starts growing significantly, and costs grow along with it, especially when your revenue doesn’t increase at the same pace. Sometimes it can result in huge licensing costs
2. A specific need – Sometimes, a company develops particular needs that an off-the-shelf product like Okta or One Trust can’t quite meet. In such cases, it’s better to implement Keycloak and then write some custom extensions for that solution

The key point in the analysis and planning of the entire user migration process is the choice of migration strategy. You have two options: Mass (which we sometimes like to call “Big Bang”) and Just-In-Time (JIT). How do they differ? When to use each of the approaches? Let’s look at them in more detail.

Mass migration

Mass user migration is the one-time transfer of user accounts, along with their credentials and associated data, from one system to another. During this process, the application is shut down, eliminating the risk of changing data during migration and ensuring consistency. After the migration is complete, the system is restored to normal operation. 

Benefits of mass migration:

• Simplicity
• Faster migration
• No risk of data changes
• The ability to thoroughly test the new system before restoring the application to operation
• The option to get rid of the old user management system after the migration is complete

Disadvantages of mass migration:

• The main disadvantage is the downtime (disabling the system for the time of the migration), which may be unacceptable for some business environments. 

Read more: How to prevent system downtime? 10 things you can do to keep your systems running

Who and when should use mass migration?

If a company can afford some downtime of the migrated application, the mass migration approach is by far the preferred method due to its simplicity and security.

Okta-Keycloak – Mass migration process

To migrate from Okta to Keycloak, you must first deploy and configure Keycloak and then move your current users to the new system. In other words, user migration consists of exporting data from the old system, processing it and then importing it to the new solution. Here are more details regarding each of the necessary steps:

1. Analysis and planning

• Defining the scope of migration (which users, what data)
• Assessment of the current system and data structure
• Selection of migration tools
• Planning a strategy for preparing compatible versions of applications using IAM (token verification, token model with roles)
• Planning a strategy for testing and validating the migrated data

2. Communication with users

• Informing users about the upcoming migration, possible interruptions and any changes that may affect them

3. Installing and configuring Keycloak

• Choosing the right infrastructure to host the new IAM system
• Installation of the Keycloak server with possible extensions
• Configuration of server settings and additional extensions
• Preparation of new versions of applications integrated with the previous IAM system so that they are compatible with Keycloak
• Creating application clients in Keycloak

4. Exporting data

• Downloading users from the current system in the appropriate format

5. Processing data

• Data cleaning and normalization
• Mapping user attributes from the current to the new system

6. Importing data

• Uploading user data to the new system

7. Validation and testing

• Verifying that all users have been transferred
• Testing functionalities such as logging in, resetting passwords and accessing resources
• Comparison of users (with key attributes)

8. Archivization

• Keeping a backup copy of exported data in case of problems

9. Application update and configuration

• Uploading and configuring new versions of the application for the production environment that are compatible with Keycloak
• Testing the integration of these applications with Keycloak

It’s a good idea to start with a test migration on a selected user subresource. It’ll allow you to see whether the migration actually works and determine if it has no run-time errors. You’ll also find out how long the migration takes.

Mass migration – how to

First, we need to export data from Okta. There are several ways to do this, summarized in the table below. Important: Always remember to keep your exported user data safe. Don’t send the file through unsecured channels, and secure it with the appropriate access password. 

The second step is importing user data to Keycloak. It’s best to do it via the API. You’ll need to prepare a tool for this purpose that will call a new user creation via REST API (POST /admin/realms/{realm}/users) for each imported user. Check out the API documentation for the current version of Keycloak (22 at the time of writing this article) if you have any doubts or questions.

Important: One key thing to note is that there is currently no public way to export users from Okta with their passwords or password hashes. As a consequence, this strategy will require an additional step. You’ll need to schedule and send all migrated users a form allowing them to set up a new password in Keycloak. This will generate many actions and events in a short time.

Just-In-Time Migration

Just-In-Time Migration (JIT) of users is a strategy where user accounts are moved from one system to another in real-time when they attempt to log in. Instead of migrating all data simultaneously, the migration is done gradually every time a user signs in. When the user is already registered in the new system, authentication takes place there. If not, the system checks with the old system and transfers the user’s data to the new system after successful authentication. 

Benefits of Just-In-Time migration:

• The application runs continuously
• The migration is invisible to users
• The process is less risky because you do things step-by-step and can monitor everything better

Disadvantages of Just-In-Time migration:

• The need to maintain both systems for some time (3 months, for example)
• Potential security challenges such as having to touch plaintext passwords when validating credentials on the old system

Okta-Keycloak – JIT migration process

1. Analysis and planning

• Defining the scope of migration (which users, what data)
• Assessment of the current system and data structure
• Planning a strategy for preparing compatible versions of applications using IAM (token verification, token model with roles)
• Planning a strategy for testing and validating the migrated data

2. Communication with users

• Informing users about the upcoming migration, possible interruptions and any changes that may affect them

3. Installing and configuring Keycloak

• Choosing the right infrastructure to host the new IAM system
• Installation of the Keycloak server with Okta provider and other possible extensions
• Configuration of server settings, Okta provider and additional extensions
• Creating application clients in Keycloak
• Preparation of new versions of applications integrated with the previous IAM system so that they are compatible with Keycloak

4. Testing

• Testing functionalities such as logging in, resetting passwords and accessing resources

5. Application update and configuration

• Uploading and configuring new versions of the application for the production environment that are compatible with Keycloak
• Testing the integration of these applications with Keycloak

Who and when should use JIT migration?

Just-In-Time migration is preferred for applications that need to run 24/7 and cannot afford downtime (even if it’s “just an hour”) during migration.

JIT migration – how to

You can use the Keycloak’s User Federation functionality to implement this migration strategy. It allows federation of existing external user databases, such as Active Directory. Thanks to the Keycloak User Storage SPI interface, you can create an extension for a custom user database – in this case, Okta.

When a user tries to log in, Keycloak searches local data stores for information about that user. If the system doesn’t find this user in the root vault, it searches within the user’s configured federations. Data from external stores is then mapped to the standard Keycloak user model.

However, it’s worth pointing out that you don’t necessarily need to write an extension yourself – we’ve already made one, and we can make it available or help you with the entire migration. If you’re interested, contact us at hello@pretius.com and tell us your needs. We’ll see what we can do for you. 

The following example shows how to use our extension to carry out a Just-In-Time migration from Okta to Keycloak.

1. Install the extension in Keycloak
2. Log in to the Keycloak admin panel
3. Go to the User Federation configuration section and use the Add new provider option to indicate Okta
4. Fill in the necessary configuration details and sav

Log in sequence diagram

The following diagram visualizes the entire log in sequence in Keycloak – you can use it if you want. 

Description of key method implementations

Here’s a description of key method implementations for Just-In-Time migration from Okta to Keycloak with our extension.

1. Get user (getUserById / getUserByUsername / getUserByEmail)

Downloading the user consists of searching for an active user by the selected attribute via the Okta API (together with the API token provided during provider configuration). If a user is found, it is imported to Keycloak.

The import consists of creating a new user in the local Keycloak database and marking it as a federated user from Okta, thanks to which we get the effect that the next time you try to log in, the indicated user will be found immediately in the local Keycloak database.

All data in Okta about the user is also transferred, such as identifier, status, attributes and groups in which this user is located.

If you need help with obtaining an API Token from Okta, here’s a quick instruction

• In the administrator console, from the side panel, select Security → API
• Change the tab to Tokens
• Choose Create token and give it a name, e.g. keycloak
• Save the created token in a safe place

2. Credential Validation (isValid)

Unfortunately, Okta does not issue an API to validate credentials, so the only option is to obtain an access token using the OAuth2 protocol, specifically the “Password grant” flow.

As a consequence, validation consists of obtaining an access token using the Okta API by passing the username and password. After receiving and verifying the token, we are sure that the login details provided in Keycloak are those that were taken from Okta, and such a user is correctly migrated to Keycloak.

After successful migration, one of the two following actions takes place:

• Saving the entered credentials as valid for a given user – for security reasons, this is not a recommended action
• Adding the required action to update the password – in this way, the user will be transferred to the new password form right after logging in

The credentials you enter will be saved in a hashed form based on the currently configured password policies (the hashing algorithm can be configured in the Keycloak admin panel Authentication -> Policies -> Password policy -> Hashing Algorithm).

In addition, the Keycloak user ID is saved in the custom KEYCLOAK_ID attribute on the Okta user. This way, you get a bilaterally linked, migrated Okta ↔ Keycloak user, which may be helpful in case you run into any problems.

3. Credential validation (isValid) – alternative version

There is an alternative implementation method that starts the same way – by validating the credentials based on the obtained access token. However, in this case, the process ends at this stage. Although the user would already have all data imported in Keycloak, the credentials would still be validated in Okta every time they log in.

At any time, an organization may decide to perform a manual action that would require a group of users to set a new password in Keycloak. After this action, validation for these users would only take place in Keycloak, which finalizes the migration process for this group. 

This approach enables a smooth transition of users from Okta to Keycloak, minimizing possible risks. It also offers enhanced security by requiring users to set a new password.

Additional options for the extension

Each extension that implements Keycloak User Storage SPI may also implement the following provider actions related to global user synchronization. Both may be useful during a test migration or cyclical import of users (e.g., from a given group in Okta) by changing the implementation accordingly (you must take the group name from the current provider configuration). 

Thanks to this, the import isn’t performed during the first login, which may degrade the user experience with the new IAM system.

1. “Sync all users” action

The action consists of searching for all active users via the Okta API, and then performing the same import action as when downloading the user at login.

2. “Sync changed users” action

The action allows you to use the Okta API to search for all active users that have been created or modified since the last import date. For a new user, the same import action as when downloading a user at login is performed. For an existing user, all user data from Okta is updated.

Conclusion

In some circumstances, migrating from Okta to Keycloak might be pretty beneficial for your business. It’s also not all that complicated or problematic. The most important decision you must make is choosing the implementation strategy. Which approach will be better for your company? You can find a quick summary of them in the table below.

Need help with an Okta – Keycloak migration?

If you have any questions or doubts, you can always hire a team of dedicated migration specialists who’ll carry this work out for you. Our team at Pretius has a great deal of experience with similar projects, and we’ll be glad to help you. Write to us at hello@pretius.com or use the contact form below – we’ll see what we can do for you. Initial consultations are always free.