How to search keycloak users by employeeNumber or by custom attributes?

Question

I wanted to search keycloak user using employeeNumber. I tried checking keycloak documentation but didn't find any API which will search based on employeeNumber/custom attributes. I m using below API to search the users with admin access.

http://localhost:8080/auth/admin/realms/Demo-Realm/users/?firstName=akshay

also tried with

http://localhost:8080/auth/admin/realms/Demo-Realm/users/?search=akshay

Answer 1

Although not mentioned on the release notes it is possible after Keycloak version 15.1.0 (as pointed out by @Darko) to search users by custom attributes, introduced with this commit. As one can now see on the GET /{realm}/users endpoint of the Keycloak Admin Rest API:

So in your case you would call that endpoint with the query parameter q=employeeNumber, for instances with curl:

curl 'https://${KEYCLOAL_HOST}/auth/admin/realms/${REALM_NAME}/users?q=employeeNumber:444555'

Bear in mind that the /auth path was removed starting with Keycloak 17 Quarkus distribution. So you might need to remove the /auth, namely:

curl 'https://${KEYCLOAL_HOST}/admin/realms/${REALM_NAME}/users?q=employeeNumber:444555'

---

Keycloak version before 15.1.0

For those with Keycloak version before 15.1.0, out-of-the-box you can use the Keycloak Admin API endpoint:

GET /{realm}/users

one can read that :

Get users Returns a list of users, filtered according to query parameters

those (optional) query parameters being:

• briefRepresentation (boolean);
• email (string);
• first (string);
• firstName (string);
• lastName (string);
• max (Maximum results size (defaults to 100)) (integer);
• search (A String contained in username, first or last name, or email);
• username (string).

As you can see you cannot search for custom attributes. A not so great solution is to get all the users (max=-1), and filter afterwards by the custom attribute.

The other option is to extend Keycloak functionality by adding your own custom Service Provider Interfaces (SPI) and adding your custom endpoint. There you can take advantage of the searchForUserByUserAttribute method from the UserQueryProvider interface.