In this project we are going to develop and integrate a custom rest api in keycloak server.

About Keycloak

Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code. It provides with following features,

• Single-Sign On
• Identity Brokering and Social Login
• User Federation
• Client Adapters
• Admin Console
• Account Management Console
• Standard Protocols: OpenID Connect, OAuth 2.0, and SAML.

Keycloak setup

We are going to use docker container to run Keycloak along with postgreSQL. We have integrated PostgreSQL with Keycloak inside docker-compose.yml file.

docker-compose -f ./docker-compose.yml up -d

Now, your keycloak should run locally on 8090 port.

Keycloak setup and adding user

URL for keycloak http://localhost:8090/

Note: By default keycloak uses Master realm. As you can see we added user in Demo realm. In order to create new realm, do as follow

Now lets create a maven project. I will use VS Code as IDE for this project.However, you can use any IDE of your choice. You can check this link to configure VS Code for Java development.

Project Structure

pom.xml file contains all the required dependencies. You can copy the dependencies in your project.

Create a mapper class that will map keycloak's UserModel class object to UserDto class object. Use import org.keycloak.models.UserModel; to import UserModel class.

    @GET
    @Path("users/search-by-attr")
    @NoCache
    @Produces({ MediaType.APPLICATION_JSON })
    @Encoded
    public List<UserDto> searchUsersByAttribute(@DefaultValue(defaultAttr) @QueryParam("attr") String attr,
            @QueryParam("value") String value) {
        return session.users().searchForUserByUserAttribute(attr, value, session.getContext().getRealm())
                .stream().map(e -> userMapper.mapToUserDto(e)).collect(Collectors.toList());
    }

The above method filters user list based on user attribute. Default filter attribute is merchant_id.

KeyCloakUserApiProvider class

Use import org.keycloak.services.resource.RealmResourceProvider; to import the interface.

KeyCloakUserApiProviderFactory class

Note: Factory instance will remain through out the lifecycle of keycloak server but KeyCloakUserApiProvider instance will be created at run time.

Register the KeyCloakUserApiProviderFactory class to keycloak by creating org.keycloak.services.resource.RealmResourceProviderFactory file under src\main\resources\META-INF\services\ folder.
Next copy the KeyCloakUserApiProviderFactory class name including package information into that file. For an example,

Copy that jar file to the Keycloak's standalone/deployments/ directory. For an example, If you run your Keycloak in docker container, you can use the following command:

docker cp <jar_file_path> keycloak:/opt/jboss/keycloak/standalone/deployments/

Test our custom api

Get list of users with merchant_id 1

curl --location --request GET 'http://localhost:8090/auth/realms/demo/userapi-rest/users/search-by-attr?attr=merchant_id&value=1'

You can find the project on this GitHub repository.

If you find this article useful, kindly give a start on GitHub.