Hello and welcome to the second article in a series showing how to secure Spring Boot applications with Keycloak. In the previous tutorial, we’ve learned how to set up the Keycloak server and secure Spring Boot REST API endpoints with it. I highly encourage you to check it out before starting this guide.

In today’s article, I would like to show you how to set up the Keycloak admin client with Spring Boot and Kotlin. I will walk you step by step through the process of setting roles, groups, and users with the Keycloak Admin REST Client.

2. Run Keycloak Server

Just like in the previous article, we will bootstrap the Keycloak server using the docker run command:

docker run -p 8090:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:11.0.3

After the server is ready, let’s head to the admin console under the http://localhost:8090/auth/admin address and create a new realm called example (I have described it thoroughly in the 3rd paragraph of the previous post).

2. Create and Configure Admin Client

[elementor-template id=”9007393″]

2.1. Create New Client

As the next step, let’s create the admin client within our realm. Let’s hit the Create button on the Clients page and name and set up a new client called admin-spring-boot:

2.2. Configure Access Type

On the next page, let’s configure our client as follows:

Please notice two things here. Confidential access-type indicates, that we will need a secret to authenticate this client against the Keycloak server. On the other hand, the service accounts enabled set to ON allows us to generate a token dedicated to this client.

2.3. Obtain Client Credentials

Nextly, let’s go to the Credentials tab and copy the secret:

The above value will be used later in our Spring Boot application to set up the connection.

2.4. Assign Roles to Service Account

The last step, we will need to do in Keycloak is to assign the appropriate roles to the service account associated with our client. Let’s switch to the Service Account Roles panel and add the following roles from the realm-management set:

Please keep in mind, that I have chosen these roles for demonstrational purposes. In real-life scenarios, we should always follow the Least Privilege rule.

3. Set Up Spring Boot Application

With all the above being done, we can start creating our Spring Boot project. In this paragraph, we will see how to set it up from scratch and interact with the Keycloak service using the admin client library.

3.1. Imports

As always, let’s start with the imports. Let’s head to the build.gradle.kts and add the following lines:

implementation("org.keycloak:keycloak-spring-boot-starter:11.0.3")
implementation("org.keycloak:keycloak-admin-client:11.0.3")
implementation("org.springframework.boot:spring-boot-starter-web")

Technically, we do not need the web starter to interact with Keycloak. However, in this guide, we will create a few endpoints to better illustrate the fully-working system.

3.2. Configure Application Properties

As the next step, let’s go to the application.yaml file and put the following configuration there:

keycloak:
  realm: example
  resource: admin-spring-boot
  auth-server-url: http://localhost:8090/auth
  credentials:
    secret: <KEYCLOAK-CLIENT-CREDENTIALS>

The secret should be set with the value from paragraph 2.3.

3.3. Create Keycloak Client Config

Nextly, let’s create the KeycloakClientConfig class:

@Configuration
class KeycloakClientConfig(
    @Value("\${keycloak.credentials.secret}")
    private val secretKey: String,
    @Value("\${keycloak.resource}")
    private val clientId: String,
    @Value("\${keycloak.auth-server-url}")
    private val authUrl: String,
    @Value("\${keycloak.realm}")
    private val realm: String
) {

    @Bean
    fun keycloak(): Keycloak {
        return KeycloakBuilder.builder()
            .grantType(CLIENT_CREDENTIALS)
            .serverUrl(authUrl)
            .realm(realm)
            .clientId(clientId)
            .clientSecret(secretKey)
            .build()
    }
}

In this configuration, we use the KeycloakBuilder class to customize the RESTEasy client used to communicate with the Keycloak server. Additionally, we annotate the keycloak() function with @Bean annotation, so that we will be able to inject this bean into our services later.

Thanks to the @Value annotation, the content of the application.yaml file is injected into our properties

3.4. Manage Roles

This time, instead of defining services first, and then implementing the controllers’ layer and testing, we will focus on Keycloak groups, roles, and users separately.

As the first step, let’s create the RoleService class with three functions:

@Service
class RoleService(
    private val keycloak: Keycloak,
    @Value("\${keycloak.realm}")
    private val realm: String
) {
    fun create(name: String) {
        val role = RoleRepresentation()
        role.name = name

        keycloak
            .realm(realm)
            .roles()
            .create(role)
    }

    fun findAll(): List<RoleRepresentation> =
        keycloak
            .realm(realm)
            .roles()
            .list()

    fun findByName(roleName: String): RoleRepresentation =
        keycloak
            .realm(realm)
            .roles()
            .get(roleName)
            .toRepresentation()
}

As you might have noticed- the first function will create a new role within the Keycloak instance. The second one will be used to obtain already created roles. On the other hand, the third one will be used by the UserController later, to obtain the RoleRepresentation.

Let’s create a controller class, which will utilize these functions:

@RestController
@RequestMapping("/api/role")
class RoleController(
    private val roleService: RoleService
) {
    @GetMapping
    fun findAll() =
        roleService.findAll()

    @PostMapping
    fun createRole(@RequestParam name: String) =
        roleService.create(name)
}

Finally, let’s build and run the application. To test if everything is working as expected, let’s use the cURL command to create a new role:

curl --location --request POST 'localhost:8080/api/role?name=ROLE_EXAMPLE'

To verify, we can either utilize the second endpoint:

curl 'localhost:8080/api/role'

Or use the Keycloak Admin Console:

3.5. Manage Groups

Similarly, let’s implement the logic responsible for Keycloak group management. Just like in the previous paragraph, let’s start with the service layer:

@Service
class GroupService(
    private val keycloak: Keycloak,
    @Value("\${keycloak.realm}")
    private val realm: String
) {
    fun create(name: String) {
        val group = GroupRepresentation()
        group.name = name

        keycloak
            .realm(realm)
            .groups()
            .add(group)
    }

    fun findAll(): List<GroupRepresentation> =
        keycloak
            .realm(realm)
            .groups()
            .groups()
}

This service looks almost the same, as the RoleService. You might have also noticed that in the second function, we’ve used groups() method two times. It’s not a typo- the creators decided to use this name in GroupsResource class instead of the list() (unfortunately).

We might want to test the group’s functionality as well.  Let’s implement the GroupController:

@RestController
@RequestMapping("/api/group")
class GroupController(
    private val groupService: GroupService
) {
    @GetMapping
    fun findAll() =
        groupService.findAll()

    @PostMapping
    fun createGroup(@RequestParam name: String) =
        groupService.create(name)
}

Similarly, after the following command:

curl --location --request POST 'localhost:8080/api/group?name=example_group'

We should see the newly created group:

curl 'localhost:8080/api/group'

3.6. Manage Users

As the last example, let’s create the logic responsible for user management. Let’s start by adding the UserRequest class to the project:

class UserRequest(
    val username: String,
    val password: String
)

This simple class will be used to create new users later.

With that being done, let’s create the UserService class:

@Service
class UserService(
    private val keycloak: Keycloak,
    @Value("\${keycloak.realm}")
    private val realm: String
) {
    fun findAll(): List<UserRepresentation> =
        keycloak
            .realm(realm)
            .users()
            .list()

    fun findByUsername(username: String): List<UserRepresentation> =
        keycloak
            .realm(realm)
            .users()
            .search(username)

    fun findById(id: String): UserRepresentation =
        keycloak
            .realm(realm)
            .users()
            .get(id)
            .toRepresentation()

    fun assignToGroup(userId: String, groupId: String) {
        keycloak
            .realm(realm)
            .users()
            .get(userId)
            .joinGroup(groupId)
    }

    fun assignRole(userId: String, roleRepresentation: RoleRepresentation) {
        keycloak
            .realm(realm)
            .users()
            .get(userId)
            .roles()
            .realmLevel()
            .add(listOf(roleRepresentation))
    }

    fun create(request: UserRequest): Response {
        val password = preparePasswordRepresentation(request.password)
        val user = prepareUserRepresentation(request, password)

        return keycloak
            .realm(realm)
            .users()
            .create(user)
    }

    private fun preparePasswordRepresentation(
        password: String
    ): CredentialRepresentation {
        val cR = CredentialRepresentation()
        cR.isTemporary = false
        cR.type = CredentialRepresentation.PASSWORD
        cR.value = password
        return cR
    }

    private fun prepareUserRepresentation(
        request: UserRequest,
        cR: CredentialRepresentation
    ): UserRepresentation {
        val newUser = UserRepresentation()
        newUser.username = request.username
        newUser.credentials = listOf(cR)
        newUser.isEnabled = true
        return newUser
    }
}

The responsibility of the three first functions is pretty simple- they allow us to find all users, or alternatively to fetch specific ones based on the username or the identifier.

Let’s analyze the logic responsible for users creation:

fun create(request: UserRequest): Response {
    val password = preparePasswordRepresentation(request.password)
    val user = prepareUserRepresentation(request, password)

    return keycloak
        .realm(realm)
        .users()
        .create(user)
}

private fun preparePasswordRepresentation(
    password: String
): CredentialRepresentation {
    val cR = CredentialRepresentation()
    cR.isTemporary = false
    cR.type = CredentialRepresentation.PASSWORD
    cR.value = password
    return cR
}

private fun prepareUserRepresentation(
    request: UserRequest,
    cR: CredentialRepresentation
): UserRepresentation {
    val newUser = UserRepresentation()
    newUser.username = request.username
    newUser.credentials = listOf(cR)
    newUser.isEnabled = true
    return newUser
}

The public function create() takes the userRequest as a parameter and prepares CredentialRepresentation first- setting the password value and making it non-temporary. Nextly,  this password representation is passed to the prepareUserRepresentation() function and assigned to the UserRepresentation. In this function, the desired user is annotated as enabled as well.

The UserService class contains two additional functions as well: assignToGroup and assignRole, which might be used to add groups/roles to the user.

Finally, let’s create the UserController function:

@RestController
@RequestMapping("/api/user")
class UserController(
    private val userService: UserService,
    private val roleService: RoleService
) {
    @GetMapping
    fun findAll() =
        userService.findAll()

    @GetMapping("/{id}")
    fun findById(@PathVariable id: String) =
        userService.findById(id)

    @GetMapping("/username/{username}")
    fun findByUsername(@PathVariable username: String) =
        userService.findByUsername(username)

    @PostMapping
    fun create(@RequestBody userRequest: UserRequest): ResponseEntity<URI> {
        val response = userService.create(userRequest)

        if (response.status != 201)
            throw RuntimeException("User was not created")

        return ResponseEntity.created(response.location).build()
    }

    @PostMapping("/{userId}/group/{groupId}")
    fun assignToGroup(
        @PathVariable userId: String,
        @PathVariable groupId: String
    ) {
        userService.assignToGroup(userId, groupId)
    }

    @PostMapping("/{userId}/role/{roleName}")
    fun assignRole(
        @PathVariable userId: String,
        @PathVariable roleName: String
    ) {
        val role = roleService.findByName(roleName)

        userService.assignRole(userId, role)
    }
}

In order to test if everything is good, let’s start by creating a new user:

curl -i --location --request POST 'localhost:8080/api/user' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "user",
    "password": "password"
}'

Please notice one, very important thing. When the Keycloak user is created successfully, the response body will be empty. If we would like to obtain the user ID, for instance, to save it in our database, we would need to extract it from the Location header of the response (that’s why we’ve used the -i flag in our command):

Location: http://localhost:8090/auth/admin/realms/example/users/[CREATED-USER-ID]

Additionally, we can check the Users page in the Keycloak Admin Console:

From now on, we should be able to sign in using the provided username and password combination. Nevertheless,  we would have to set up a new client for this purpose (I’ve described this process in this tutorial).

Following, let’s add our user to the group:

curl --location --request POST 'localhost:8080/api/user/35520db6-3df0-4693-b8b1-f9abc09d7b86/group/7eb8db7a-7693-4df3-b682-d955da67d453'

After the operation finishes, we should see the following in the user Groups tab:

As the last step, let’s assign the ROLE_EXAMPLE to our user:

curl --location --request POST 'localhost:8080/api/user/35520db6-3df0-4693-b8b1-f9abc09d7b86/role/ROLE_EXAMPLE'

Similarly, when we head to the Role Mappings tab, we should see that the role has been assigned successfully:

4. Summary

And that would be all for this article. We’ve learned today, how to set up the Keycloak Admin Client with Spring Boot and Kotlin. I hope you really liked the two most recent articles related to this topic. If you would like me to cover some special aspects of the Keycloak/Spring Boot integration, please let me know in the comments, or by the contact form.

Also, for the source code, please refer to this GitHub repository.

The post How to Set Up Keycloak Admin Client with Spring Boot and Kotlin? appeared first on Codersee blog- Kotlin on the backend.

Hello and welcome to the first article in a series showing how to use Keycloak with Spring Boot applications.

In this step by step guide, I will show you how to set up a Keycloak server and connect to it using Spring Boot and Kotlin. Additionally, you will learn how to secure REST endpoints with Keycloak combined with the @PreAuthorize annotation.

2. What is Keycloak?

According to the documentation, Keycloak is the Open Source Identity and Access Management solution. In simple terms, it allows us to add authentication and secure our applications with minimum effort. With Keycloak, plenty of topics, like user storage, authentication, and many many more, are available out of the box.

In addition, the keycloak-spring-boot-starter makes all the process of configuration really straightforward, thus saving our precious time.

3. Install Keycloak

As the first step in this tutorial will be the installation of the Keycloak server. There are plenty of ways to achieve that, and I highly recommend you visit the official documentation to choose the most suitable one for you.

To keep this tutorial as simple as possible, I’ve decided to deploy it as a Docker container. If you have the Docker environment already installed on your machine, all you need to do is to type the following command:

docker run -p 8090:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -e DB_VENDOR=h2 quay.io/keycloak/keycloak:11.0.3

With this command, we create a container using the keycloak:11.0.3 image and publish it’s 8080 port to the 8180 port of the host. Additionally, we pass the KEYCLOAK_USER and KEYCLOAK_PASSWORD environment variables for the initial admin user (root).

However, the simplicity comes with its own restrictions. By default, the Keycloak server runs using the H2 database, so all the configuration will be lost after the container is terminated. To prevent that we can export a realm configuration to the JSON file (I will show you this step later).

3. Configure Keycloak

Once the Keycloak server is up and running, let’s head to the administration console. All we need to do is to type http://localhost:8090 in the address bar of the browser. We should see the following page:

On the next page, we should see the login form. Let’s enter the credentials for the admin account we’ve already configured:

3.1. Create Realm

After we’ve authenticated successfully, we can create a new realm. In Keycloak, realms manage a set of users, credentials, roles, and groups. Each user belongs to and logs into some realm. Moreover, they are completely isolated environments, which introduce an additional layer of security to our application.

As the next step, let’s navigate to the Add realm button:

On the next page, let’s type the name for the new realm and hit the create button:

Please remember this name, we will need it to configure the Spring Boot application later.

3.2. Create Roles

Nextly, let’s create some roles for our future users. Let’s navigate to the Roles tab on the left sidebar. On the next screen, we should see the list of already existing roles. Let’s click the Add role button placed in the right part of the screen.

Firstly, let’s type the ROLE_USER and click save. After that, let’s add the ROLE_ADMIN which will be a composite role associated with the previous one:

Please notice two important things here:

• A composite role combines together multiple roles. To put it simply- a user with the ROLE_ADMIN will be able to access all endpoints restricted for ROLE_USER. It helps to clean the architecture of the security a lot, however, please be careful not to introduce an additional gap to the system when using it.
• Both roles have been prefixed with a ROLE_. Spring Security will automatically prefix hasRole checks with the same value.

3.3. Create Clients

As the next step, let’s create clients. Most often, Keycloak clients are the applications and services we would like to secure, or which are obtaining tokens to access other applications.

For the purpose of this tutorial, we will create two clients. Let’s start the one, we will use to configure our Spring Boot application:

Please notice, that we’ve set the Access Type to bearer-only. It means, that our application will not initiate a login, it’ll just pass received tokens to verify them with Keycloak. Most of the time, you will set this type of access type for the Spring Boot backends, which don’t need to call another microservices secured by Keycloak, or to use a service account.

Nextly, let’s create the public client, which will be used to get access tokens on behalf of the user:

This time, only the Direct Access Grants flow is enabled and the Access Type is set to public.
The public access type is used for clients, which cannot keep secrets securely, like frontend applications for instance.

3.4. Create Users

As the last step for Keycloak configuration, we will create users. Let’s head to the Users page, and create a user names example_user:

Let’s mark him enabled and his email verified as well.

The next important thing we need to do is to set the password for the user in the Credentials tab:

And as the last step, let’s add the desired role to the user. Let’s select the ROLE_USER and hit the Add selected button, just like below:

Please repeat the same steps for the admin user. The only difference will be the selection of the ROLE_ADMIN instead.

4. Configure Spring Boot App

4.1. Imports

As usual, we will start the configuration of our Spring Boot application with imports. Let’s head to the build.gradle.kts file and add the following dependencies:

implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.keycloak:keycloak-spring-boot-starter:11.0.3")
implementation("org.springframework.boot:spring-boot-starter-security:2.4.0")

4.2. Configure Application Properties

As the next step, let’s open the /resources/application.yaml file and paste the following config:

keycloak:
  realm: example
  resource: spring-boot
  bearer-only: true
  auth-server-url: http://localhost:8090/auth

Let’s see what each of the above configs mean:

• realm– as the name suggests, it is the name of the created realm,
• resource– matches the name of the created client,
• bearer-only– this flag indicates, that our service has been created as a bearer-only, by default it is set to false,
• auth-server-url– it is the URL of our Keycloak server

4.3. Configure Spring Security

As the next step, let’s create the WebSecurityConfig class:

@KeycloakConfiguration
@EnableGlobalMethodSecurity(prePostEnabled = true)
class WebSecurityConfig : KeycloakWebSecurityConfigurerAdapter() {

    @Autowired
    fun configureGlobal(auth: AuthenticationManagerBuilder) {
        val keycloakAuthenticationProvider = keycloakAuthenticationProvider()
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(SimpleAuthorityMapper())
        auth.authenticationProvider(keycloakAuthenticationProvider)
    }

    @Bean
    override fun sessionAuthenticationStrategy(): SessionAuthenticationStrategy {
        return NullAuthenticatedSessionStrategy()
    }

    @Bean
    fun keycloakConfigResolver(): KeycloakConfigResolver {
        return KeycloakSpringBootConfigResolver()
    }

    override fun configure(http: HttpSecurity) {
        super.configure(http)
        http
            .authorizeRequests()
            .antMatchers("/api/public/**").permitAll()
            .anyRequest().fullyAuthenticated()
    }
}

I totally understand that this config might be a little overwhelming, so let’s just break it down:

@KeycloakConfiguration
@EnableGlobalMethodSecurity(prePostEnabled = true)
class WebSecurityConfig : KeycloakWebSecurityConfigurerAdapter()

@KeycloakConfiguration annotation provides a Keycloak based Spring security configuration. It is used with classes extending KeycloakWebSecurityConfigurerAdapter, just like in our case. The @EnableGlobalMethodSecurity with prePostEnabled set to true enables the Spring Security global method security and @PreAuthorize annotations.

@Autowired
fun configureGlobal(auth: AuthenticationManagerBuilder) {
    val keycloakAuthenticationProvider = keycloakAuthenticationProvider()
    keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(SimpleAuthorityMapper())
    auth.authenticationProvider(keycloakAuthenticationProvider)
}

The configureGlobal function takes the AuthenticationManagerBuilder bean as a parameter and sets the KeycloakAuthenticationProvider as the authentication provider. Additionally, it sets the SimpleAuthorityMapper as the authority mapper.

@Bean
override fun sessionAuthenticationStrategy(): SessionAuthenticationStrategy {
    return NullAuthenticatedSessionStrategy()
}

@Bean
fun keycloakConfigResolver(): KeycloakConfigResolver {
    return KeycloakSpringBootConfigResolver()
}

With these two functions, we declare the KeycloakSpringBootConfigResolver bean and that we do not want the session to be created, as well.

override fun configure(http: HttpSecurity) {
    super.configure(http)
    http
        .authorizeRequests()
        .antMatchers("/api/public/**").permitAll()
        .anyRequest().fullyAuthenticated()
}

Finally, we override the configure method derived from the KeycloakWebSecurityConfigurerAdapter. With this config, all requests except the /api/public/** need to be fully authenticated.

5. Create Rest Controller

With all the above being done, we can create an ExampleController class, which consists of three endpoints:

@RestController
@RequestMapping("/api")
class ExampleController {

    @GetMapping("/example")
    @PreAuthorize("hasRole('USER')")
    fun getUserInfo(): ResponseEntity<String> =
        ResponseEntity.ok("User info")

    @GetMapping("/example/admin")
    @PreAuthorize("hasRole('ADMIN')")
    fun getAdminInfo(): ResponseEntity<String> =
        ResponseEntity.ok("Admin info")

    @GetMapping("/public/example")
    fun getPublicInfo(): ResponseEntity<String> =
        ResponseEntity.ok("Public info")
}

The first two of them require the user to either have the ROLE_USER or ROLE_ADMIN assigned to him. Nevertheless, the last endpoint permits anyone, even without the token.

6. Testing with cURL

Finally, we can validate if everything is working as expected.

Let’s start by obtaining the access token:

curl --location --request POST 'http://localhost:8090/auth/realms/example/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=some_user' \
--data-urlencode 'password=password' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=public'

As the result we should get the following JSON object:

{
    "access_token":  [TOKEN],
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": [TOKEN],
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "7981f2e1-4e50-44d6-ac81-2ba508a59680",
    "scope": "email profile"
}

The most important part of the response for us is the JWT access token, which we will use to query our endpoints. If you would like to see, how many informations are encoded within it, I highly recommend to visit jwt.io and check it out.

To fully validate our endpoints, let’s query all of them with different tokens and see if results correspond to our assumptions:

curl --location --request GET 'http://localhost:8080/api/example' \
--header 'Authorization: Bearer [TOKEN]' 

## Result for both admin and user:
User info

curl --location --request GET 'http://localhost:8080/api/example/admin' \
--header 'Authorization: Bearer [TOKEN]' 

## Result only for admin:
Admin info

curl --location --request GET 'http://localhost:8080/api/public/example' 

## Result for any request:
Public info

7. Export Realm Configuration

In the beginning, I’ve promised to show you how to export the realm configuration. The only thing we need to do is to click the Export tab on the left sidebar and nextly the Export button on the next page:

As a result, a JSON file will be generated.

If we would like to import the configuration, all we need is to head to the Import section:

8. Conclusion

And that would be all for this article. We’ve covered step by step, how to set up the Keycloak server with Spring Boot and Kotlin. Moreover, we’ve had a chance to see how to use it to secure Spring Boot REST endpoints with @PreAuthorize.

As I have written in the beginning, this is the first article in a series. If you would like me to cover some special aspects of the Keycloak/Spring Boot integration, please let me know in the comments, or by the contact form.

Also, to see the fully working project, please refer to this GitHub repository.

The post Keycloak with Spring Boot and Kotlin- Introduction appeared first on Codersee blog- Kotlin on the backend.