Migration of existing users-hashed passwords to Keycloak

6,787 views
Skip to first unread message

Navin Kaushik

unread,
May 12, 2021, 2:42:49 AM5/12/21
to Keycloak User
Hello All,

How can existing users with hashed passwords in our current application can be moved to Keycloak so that there is no need to force users to set password.

Summary, migration of users-hashed passwords to Keycloak.

-Regards,
Navin

Garth

unread,
May 12, 2021, 6:17:11 AM5/12/21
to keyclo...@googlegroups.com
Look at the org.keycloak.credential.hash package in the javdocs. You can implement your own PasswordHashProvider, or use an existing one, if it's compatible with the hashing algorithm you used.
> --
> You received this message because you are subscribed to the Google
> Groups "Keycloak User" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to keycloak-use...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/keycloak-user/b93cf96b-f56d-4c8e-a2c0-e2958b0acbf7n%40googlegroups.com <https://groups.google.com/d/msgid/keycloak-user/b93cf96b-f56d-4c8e-a2c0-e2958b0acbf7n%40googlegroups.com?utm_medium=email&utm_source=footer>.

Navin Kaushik

unread,
May 12, 2021, 7:56:23 AM5/12/21
to Keycloak User
Thanks Garth for the quick response. I don't see about this in Keycloak Server Developer Guide https://www.keycloak.org/docs/latest/server_development/#_auth_spi

Will there be a risk of breaking it in future if provided own implementation ?

-Thanks,
Navin

Garth

unread,
May 12, 2021, 9:02:32 AM5/12/21
to keyclo...@googlegroups.com
Once you implement your own provider, you have to register it by putting the class name in `META-INF/services/org.keycloak.credential.hash.PasswordHashProviderFactory` in your jar.

You then set the algorithm used in "Authentication"->"Password Policy" in the Admin UI for the realm you want to change it for.

As long as you set it properly, there isn't a risk of "breaking" anything in the future.
> https://groups.google.com/d/msgid/keycloak-user/fbc3558d-60a8-4a4f-8643-cf31ce6a5318n%40googlegroups.com <https://groups.google.com/d/msgid/keycloak-user/fbc3558d-60a8-4a4f-8643-cf31ce6a5318n%40googlegroups.com?utm_medium=email&utm_source=footer>.

Navin Kaushik

unread,
May 13, 2021, 12:53:21 AM5/13/21
to Keycloak User
Thanks Garth for the confirmation.  It is clear that how hash would be created in case of new user and how it would be verified.

Last question, users can be created into Keycloak but hash doesn't need to created but imported ? I mean, do we need to create & insert secret & credential data directly into database or some other mechanism.

-Thanks,
Navin 

Andrey Kotov

unread,
May 13, 2021, 3:32:36 AM5/13/21
to Keycloak User
I am not sure you can use Keycloak API while adding hashes.

I had experience importing >100K users with custom algorithm (MD5 in my case), I've choose to add data to database directly.

Garth

unread,
May 13, 2021, 6:34:12 AM5/13/21
to keyclo...@googlegroups.com
Agreed. You can import users using the API, but you'll have to write the password hash value to the `CREDENTIAL` table directly. Once you've set up your `PasswordHashProvider`, add a user and a password using the Admin UI, then look at the `SECRET_DATA` and `CREDENTIAL_DATA` columns in the `CREDENTIAL` table to see the format you should use.
> https://groups.google.com/d/msgid/keycloak-user/691d3fa1-9624-4466-8a89-c0d0fe226769n%40googlegroups.com <https://groups.google.com/d/msgid/keycloak-user/691d3fa1-9624-4466-8a89-c0d0fe226769n%40googlegroups.com?utm_medium=email&utm_source=footer>.

Navin Kaushik

unread,
May 13, 2021, 10:13:48 AM5/13/21
to Keycloak User
Thanks Andrey & Garth for the information.

-Regards,
Navin

Nicola Beghin

unread,
May 13, 2021, 5:15:01 PM5/13/21
to Keycloak User
If useful, here's an example implementation with custom hash provider and relative REST call to import users with such custom hash provider 

Navin Kaushik

unread,
May 18, 2021, 12:52:11 AM5/18/21
to Keycloak User
Thanks Nicola for sharing it, it's very helpful!

-Regards,
Navin

Navin Kaushik

unread,
May 20, 2021, 7:39:42 AM5/20/21
to Keycloak User
Here is the update:

I did a POC which is successful:

1. Created my own custom hash class which can verify passwords based upon version field which is stored in additional parameters part of credential data.
2. If user sets password or new user created, it would be based upon pbkdf2, it means over the period of time, all passwords will move from legacy to pbkdf2.
3. During migration, first all users will be migrated along with dummy password, then for each user, directly secret & credential data string will be inserted into database.

Thanks everyone for the help.

-Regards,
Navin

Garth

unread,
May 20, 2021, 7:46:53 AM5/20/21
to keyclo...@googlegroups.com
Thank you for sharing your results. If you can, would be great to see your POC code, as I've seen this problem several times on the lists, and I'm sure others would benefit from seeing your approach.
> https://groups.google.com/d/msgid/keycloak-user/54fe1369-738c-47be-9b47-e3bf2ad4e2c9n%40googlegroups.com <https://groups.google.com/d/msgid/keycloak-user/54fe1369-738c-47be-9b47-e3bf2ad4e2c9n%40googlegroups.com?utm_medium=email&utm_source=footer>.

Lars Van Casteren

unread,
May 20, 2021, 3:36:26 PM5/20/21
to keyclo...@googlegroups.com
I followed this thread as I'm going be in the same boat in 2-3 months migrating users from a legacy system that uses a SSHA512 hash.
The https://github.com/nicolabeghin/keycloak-sha1-salted was key in coming up with a solution in no-time.

The legacy component uses the raw password + random salt to create a single ssha512 hash where the salt is part of the hash.

1) Changed the keycloak-sha1-salted repo to sha512 and set it's id to sha512-salted.
2) Import users from legacy system using the API (POST auth/admin/realms/<realm>/users)

{
"firstName":"<firstname> ",
"lastName":"<lastname>",
"email":"add...@email.com",
"credentials":[
{
"type":"password",
"secretData":"{\"value\":\"<legacy SSHA512 password>\",\"salt\":\"\"}",
"credentialData":"{\"algorithm\":\"sha512-salted\",\"hashIterations\":0}"
}
],
"username":"<username>",
"emailVerified":true,
"enabled":true
}

3) Added a function to keycloak-sha512-salted custom hash provider to extract the salt from the SSHA512 hash/secret.
3) Use raw passwd + extracted salt to create a SSHA512 hash and check it against the stored SSHA512 hash.
4) If matched, verify returns true and the user is authenticated and to top it off with a cherry, Keycloak automagically migrates the SSHA512 password to the default PBKDF2 algorithm.

Another option was to pre-process the LDIF export containing the legacy users, extract the salt and import with the secret + salt separately but doing it in the custom hash provider seemed cleaner than messing with the exported hash before importing. I settled on using a bash script that loops over the LDAP ldiff export and fires curl API calls to create the users.

Without the https://github.com/nicolabeghin/keycloak-sha1-salted tip it would have taken me a while longer to figure out a migration path, thanks Nicola!

Gr,
L
To view this discussion on the web visit https://groups.google.com/d/msgid/keycloak-user/84b04c8f-02c6-45bd-ac02-d9e900e85a23%40www.fastmail.com.

Nicola Beghin

unread,
May 20, 2021, 4:45:24 PM5/20/21
to Keycloak User
Glad to be of help Lars! 
I really think Keycloak is a terrific tool but most of the time I have to delve into the source code itself to figure out how to do things, so hope more people will follow by sharing useful snippet/tutorials.

nicola

Navin Kaushik

unread,
May 21, 2021, 6:26:12 AM5/21/21
to Keycloak User
Well, perfectly described above that https://github.com/nicolabeghin/keycloak-sha1-salted  made the life much easier.

Just would like to add one more point that if you are bringing/migrating users from multiple systems and these systems stored password differently, in that case

Either you can utilize the additional params in credential data to store version or you can provide multiple custom hash providers for each system.

-Thanks,
Navin

Reply all
Reply to author
Forward
0 new messages