How to get users by custom attributes in keycloak? - keycloak

Question

I know that there is admin APIs to get the list of users which returns the user representation array.
GET /admin/realms/{realm}/groups/{id}/members
returns
https://www.keycloak.org/docs-api/2.5/rest-api/index.html#_userrepresentation
but is there a way to get users by custom attribute ?

Answer 1

This is not possible by default, but Keycloak offers the possibility to extend its functionalities via a system of Service Provider Interfaces which is very easy to implement.
Here is an example of new route that allows to search by custom attributes :
public class SearchByAttributeResourceProvider implements RealmResourceProvider {
private KeycloakSession session;
public SearchByAttributeResourceProvider(KeycloakSession session) {
this.session = session;
}
#Override
public Object getResource() {
return this;
}
#GET
#Path("search-by-stuff/{stuffValue}")
#Produces({MediaType.APPLICATION_JSON})
public List<UserRepresentation> getUsersByStuff(#PathParam("stuffValue") String stuffValue) {
return session
.users()
.searchForUserByUserAttribute("stuff", stuffValue, session.getContext().getRealm())
.stream()
.map(userModel -> ModelToRepresentation.toRepresentation(session, session.getContext().getRealm(), userModel))
.collect(toList());
}
#Override
public void close() {
}
}
You'll find more details here : https://www.keycloak.org/docs/latest/server_development/index.html#_extensions_rest

Answer 2

This is enabled out of the box from Keycloak version 15.1.0
Using GET /{realm}/users API, parameter q is introduced: A query to search for custom attributes, in the format 'key1:value2 key2:value2'
curl 'http://{{keycloak_url}}/auth/admin/realms/{{realm}}/users?q=phone:[phone]'
You can also combine several attributes within this parameter using space ' ' delimiter
curl 'http://{{keycloak_url}}/auth/admin/realms/{{realm}}/users?q=phone:[phone] country:USA'
Docs: https://www.keycloak.org/docs-api/15.1/rest-api/index.html#_users_resource

Answer 3

With latest version of keycloak (18.01), we have api in
#GET
#Produces(MediaType.APPLICATION_JSON)
#Consumes(MediaType.APPLICATION_JSON)
List<UserRepresentation> searchByAttributes(#QueryParam("q") String searchQuery);
The query param is of format 'key:value' . Using this we can get list of all users by custom attributes

Answer 4

Update: The /auth path was removed starting with Keycloak 17 Quarkus distribution. So you might need to remove the /auth from the endpoint calls presented on this answer.
Keycloak versions from 15.1.0 upwards
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:
Form example:
curl 'https://${KEYCLOAL_HOST}/auth/admin/realms/${REALM_NAME}/users?q=employeeNumber:444555'
Keycloak versions before 15.1.0
For 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 (pointed out by #Lucas) 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.
Step-by-step with Keycloak Admin API versions from 15.1.0 upwards
To use the Keycloak Admin REST API, you need an access token from a user with the proper permissions. For now, I will be using the admin user from the master realm, and later explain how to use another user:
curl “https://${KEYCLOAK_HOST}/auth/realms/master/protocol/openid-connect/token” \
-d "client_id=admin-cli" \
-d "username=${ADMIN_NAME}” \
-d "password=${ADMIN_PASSWORD}" \
-d "grant_type=password"
You get a JSON response with the admin's token. Extract the value of property access_token from that response. Let us save it in the variable $ACCESS_TOKEN for later reference.
To get the list of users from your realm $REALM_NAME with a given set of attributes (i.e., ${ATTRIBUTES}).
curl -X GET “https://${KEYCLOAK_HOST}/auth/admin/realms/${REALM_NAME}/users?q=${ATTRIBUTES}” \
-H "Content-Type: application/json" \
-H "Authorization: bearer ${ACCESS_TOKEN}”
I have the aforementioned steps coded in the script getUserByAttributes.sh on my GitHub repo for those that are interested. An example :
sh getUserByAttributes.sh localhost:8080 admin admin test_realm 'employeeNumber:4445 something:a'
Assigning the proper user permissions
For those that do not want to get an access token from the master admin user, you can get it from another user but that user needs the permission manage-users from the realm-management client. For that you can check this answer on how to do it

Answer 5

Current Keycloak API version is 4.8 and there is API:
Get users Returns a list of users, filtered according to query parameters
GET /{realm}/users
See doc: https://www.keycloak.org/docs-api/4.8/rest-api/index.html#_users_resource
Only this "search" is available from the API. If you need search by user attributes, then you need to implement it in your own code.

Answer 6

You can filter keycloak users using their custom attributes by passing the 'q' get parameter:
IN SUMMARY:
<get-users-url>?q=key1:value1 key2:value2
EXAMPLE:
curl --location --request GET 'http://localhost:8080/admin/realms/realm-name/users?q=key1:value1 key2:value2' \
--header 'Authorization: Bearer <your-token>'