Avoid using UserCredentialManager from user storage extensions #43695

mposolda · 2025-10-24T09:33:44Z

There is an issue #43626 for make sure keycloak-model-storage does not have dependency on keycloak-server-spi-private .

In the PR for that issue, I took the approach of moving UserCredentialManager to the keycloak-server-spi-private. But this means that people cannot use the UserCredentialManager from their user-storage providers anymore (due the fact that if they use it, they will need dependency on keycloak-server-spi-private). However this might be a backwards incompatible change as people may already use UserCredentialManager in their providers similarly like for example our quickstart is doing: https://github.com/keycloak/keycloak-quickstarts/blob/main/extension/user-storage-simple/src/main/java/org/keycloak/quickstart/readonly/PropertyFileUserStorageProvider.java#L88 .

So was thinking about doing this in multiple steps:

In 26.5, make sure that constructor new UserCredentialManager() is not recommended for the use, so people have a chance to migrate to avoid using this class directly, but rather access it via the method on KeycloakSession
In 27.0 move the UserCredentialManager to keycloak-server-spi-private and make sure that keycloak-model-storage can remove the dependency on keycloak-server-spi-private (will require few other minor things done in .

The alternative approach is to keep UserCredentialManager in keycloak-model-storage, but this does not seem right to me TBH as this class contains lots of logic, which does not need to be directly accessible to people in their applications. Among other things, it would also require moving few other classes (like DatastoreProvider for example) to keycloak-server-spi or keycloak-model-storage and it would mean that people will need to declare dependency on opentelemetry in their user-storage providers (as UserCredentialManager is using opentelemetry). But I can revisit if you think this would be better?

What do you think?

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2025-10-24T10:48:41Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.federation.ldap.LDAPProvidersIntegrationTest#updateLDAPUsernameTest

Keycloak CI - Base IT (5)

org.keycloak.testsuite.runonserver.RunOnServerException: java.lang.NullPointerException
	at org.keycloak.testsuite.client.KeycloakTestingClient$Server.fetchString(KeycloakTestingClient.java:185)
	at org.keycloak.testsuite.federation.ldap.LDAPProvidersIntegrationTest.updateLDAPUsernameTest(LDAPProvidersIntegrationTest.java:1656)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)
...

Report flaky test

pedroigor

For 27, my proposal would be:

Rename org.keycloak.credential.UserCredentialManager to org.keycloak.credential.DefaultUserCredentialManager (and make it private as you are proposing)
Rename org.keycloak.models.SubjectCredentialManager to org.keycloak.models.UserCredentialManager

pedroigor · 2025-10-24T13:38:06Z

server-spi/src/main/java/org/keycloak/models/KeycloakSession.java

+     *
+     * @return user credential manager
+     */
+    SubjectCredentialManager getUserCredentialManager(UserModel user);


Is it the best place to have this method? It seems a bit weird that we now have this:

session.users()

and:

session.getUserCredentialManager()

Instead of something like this:

session.users().getCredentialManager(user)

That should work as well.

Was thinking about this and originally did not used this just because we have multiple implementations of UserProvider and the jpa/infinispan implementations are more towards to have mostly logic related to CRUD of particular storage (EG. JpaUserProvider has mostly methods related to CRUD of users to the DB). At the same time, introducing the method to KeycloakSession is also not great... So I've updated to use the approach you suggest.

closes keycloak#43694 Signed-off-by: mposolda <[email protected]>

Signed-off-by: mposolda <[email protected]>

mposolda · 2025-10-29T10:57:27Z

For 27, my proposal would be:

* Rename `org.keycloak.credential.UserCredentialManager` to `org.keycloak.credential.DefaultUserCredentialManager` (and make it private as you are proposing)

* Rename `org.keycloak.models.SubjectCredentialManager` to `org.keycloak.models.UserCredentialManager`

This works.

Considering this, I wonder that it is possible to introduce already class org.keycloak.models.UserCredentialManager? In this case, people have already the possibility to update using that class instead of having breaking changes later as they can use something like:

@Override
public org.keycloak.models.UserCredentialManager credentialManager() {
    return keycloakSession.users().getUserCredentialManager(this);
}

in their UserModel implementations. This means that if they update their code now, they will not need to update the code again once switching from 26.5 to 27. WDYT?

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2025-10-29T12:12:33Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.forms.AuthenticatorSubflowsTest2#testSubflow2

Keycloak CI - Forms IT (chrome)

java.lang.AssertionError: Expected AppPage but was PushTheButton (https://localhost:8543/auth/realms/test/login-actions/authenticate?execution=0b5cf183-110c-4477-90a0-3f4beb7da6ed&client_id=test-app&tab_id=IyL8IrAXVZs&client_data=eyJydSI6Imh0dHBzOi8vbG9jYWxob3N0Ojg1NDMvYXV0aC9yZWFsbXMvbWFzdGVyL2FwcC9hdXRoIiwicnQiOiJjb2RlIn0)
	at org.junit.Assert.fail(Assert.java:89)
	at org.junit.Assert.assertTrue(Assert.java:42)
	at org.keycloak.testsuite.pages.AbstractPage.assertCurrent(AbstractPage.java:38)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
...

Report flaky test

keycloak-github-bot

Unreported flaky test detected, please review

keycloak-github-bot · 2025-10-29T14:43:58Z

Unreported flaky test detected

If the flaky tests below are affected by the changes, please review and update the changes accordingly. Otherwise, a maintainer should report the flaky tests prior to merging the PR.

org.keycloak.testsuite.forms.AuthenticatorSubflowsTest2#testSubflow2

Keycloak CI - Forms IT (chrome)

java.lang.AssertionError: Expected AppPage but was PushTheButton (https://localhost:8543/auth/realms/test/login-actions/authenticate?execution=0b5cf183-110c-4477-90a0-3f4beb7da6ed&client_id=test-app&tab_id=IyL8IrAXVZs&client_data=eyJydSI6Imh0dHBzOi8vbG9jYWxob3N0Ojg1NDMvYXV0aC9yZWFsbXMvbWFzdGVyL2FwcC9hdXRoIiwicnQiOiJjb2RlIn0)
	at org.junit.Assert.fail(Assert.java:89)
	at org.junit.Assert.assertTrue(Assert.java:42)
	at org.keycloak.testsuite.pages.AbstractPage.assertCurrent(AbstractPage.java:38)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
...

Report flaky test

mposolda · 2025-10-29T15:26:45Z

@pedroigor Thanks!

mposolda self-assigned this Oct 24, 2025

keycloak-github-bot bot added the flaky-test label Oct 24, 2025

keycloak-github-bot bot reviewed Oct 24, 2025

View reviewed changes

pedroigor reviewed Oct 24, 2025

View reviewed changes

Avoid using UserCredentialManager from user storage extensions

4e5823b

closes keycloak#43694 Signed-off-by: mposolda <[email protected]>

mposolda force-pushed the 43694 branch from 725922f to 623ddcf Compare October 29, 2025 10:47

Updating per code review

91ec63d

Signed-off-by: mposolda <[email protected]>

mposolda force-pushed the 43694 branch from 623ddcf to 91ec63d Compare October 29, 2025 10:55

pedroigor approved these changes Oct 29, 2025

View reviewed changes

keycloak-github-bot bot reviewed Oct 29, 2025

View reviewed changes

mposolda marked this pull request as ready for review October 29, 2025 15:26

mposolda requested review from a team as code owners October 29, 2025 15:26

keycloak-github-bot bot added team/cloud-native team/core-clients team/core-iam team/sre labels Oct 29, 2025

mposolda merged commit 2fc5419 into keycloak:main Oct 29, 2025
127 of 129 checks passed

mposolda mentioned this pull request Oct 29, 2025

Remove dependency on keycloak-server-spi-private from keycloak-model-storage #43626

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Avoid using UserCredentialManager from user storage extensions #43695

Avoid using UserCredentialManager from user storage extensions #43695

Uh oh!

mposolda commented Oct 24, 2025 •

edited

Loading

Uh oh!

keycloak-github-bot bot left a comment

Uh oh!

keycloak-github-bot bot commented Oct 24, 2025

Uh oh!

pedroigor left a comment •

edited

Loading

Uh oh!

pedroigor Oct 24, 2025

Uh oh!

mposolda Oct 29, 2025

Uh oh!

mposolda commented Oct 29, 2025

Uh oh!

keycloak-github-bot bot left a comment

Uh oh!

keycloak-github-bot bot commented Oct 29, 2025

Uh oh!

keycloak-github-bot bot left a comment

Uh oh!

keycloak-github-bot bot commented Oct 29, 2025

Uh oh!

mposolda commented Oct 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Avoid using UserCredentialManager from user storage extensions #43695

Avoid using UserCredentialManager from user storage extensions #43695

Uh oh!

Conversation

mposolda commented Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

keycloak-github-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

keycloak-github-bot bot commented Oct 24, 2025

Unreported flaky test detected

org.keycloak.testsuite.federation.ldap.LDAPProvidersIntegrationTest#updateLDAPUsernameTest

Uh oh!

pedroigor left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pedroigor Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

mposolda Oct 29, 2025

Choose a reason for hiding this comment

Uh oh!

mposolda commented Oct 29, 2025

Uh oh!

keycloak-github-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

keycloak-github-bot bot commented Oct 29, 2025

Unreported flaky test detected

org.keycloak.testsuite.forms.AuthenticatorSubflowsTest2#testSubflow2

Uh oh!

keycloak-github-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

keycloak-github-bot bot commented Oct 29, 2025

Unreported flaky test detected

org.keycloak.testsuite.forms.AuthenticatorSubflowsTest2#testSubflow2

Uh oh!

mposolda commented Oct 29, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mposolda commented Oct 24, 2025 •

edited

Loading

pedroigor left a comment •

edited

Loading