Keycloak : Retrieve custom attributes in Access Token

Keycloak is an open-source Identity and Access Management (IAM) solution aimed at modern applications and services. Keycloak provides out-of-the-box authentication and authorization services as well as advanced features like User Federation, Identity Brokering, and Social Login.

We are going to see how Keycloak gives us control, to transfer custom attributes to the applications that receive ID Tokens, Access Tokens. Keycloak provides us lot of control of what exactly goes back to the client. To demonstrate this we will configure custom attribute for an user and map that attribute to the Access Token using Mappers.

Spring Boot and Keycloak

We will write a RESTful service with SpringBoot and then secure it with Keycloak. We will be writing an application providing REST API, which returns custom attributes in response. Before looking at application we will setup Keycloak Server and then configure it.

Set Up Keycloak


In your browser, go to http://localhost:8080/auth/

Since it’s the first time that the Keycloak server is running, you will have to create an admin user, so let’s create an admin user with admin as the username.

Now, log in to Keycloak using admin user and start configuring Keycloak, the admin user is created in the default realm called master.

A realm secures and manages security metadata for a set of users, applications, and registered oauth clients. Users can be created within a specific realm within the Administration console. Roles (permission types) can be defined at the realm level and you can also set up user role mappings to assign these permissions to specific users.

Creating a Realm

Now, create a client called springboot-user-attributes under springboot-keycloak realm, here we are securing our client which provides REST Service.

Creating role and assign to user

Now we will create user bob and assign him the role user

Lets now create a custom variable with key as mobile for user bob

This the user attribute we want transfer to the client/application as part of the AccessToken

Now our user bob got the custom attribute it has to be pushed to AccessToken . Keycloak gives us control on what metadata you to push as part of AccessToken and this can be done using mappers.

Note : Protocol mappers are available only for public or Confidential clients

Here we will create public client named postman under realm springboot-keycloak and we use this client for our testing as well.

Now create a mapper for client postman, map mobile user attribute and enable Add to access token

Now we have finished configuring the Keycloak , its time to jump into application, you can find the spring-boot application springboot-user-attributes on github

Spring-boot Application

There are 2 endpoints exposed by this service:

public : requires no authentication
userinfo : can be invoked by users with the user role and returns login user attributes.

Here is the code snippet on how we can retrieve custom attribute in application using KeycloakPrincipal

@GetMapping(value = "/userinfo", produces = MediaType.APPLICATION_JSON_VALUE)
public UserData handleUserInfoRequest(Principal principal) {
UserData user = new UserData();
if (principal instanceof KeycloakPrincipal) {

KeycloakPrincipal<KeycloakSecurityContext> kp = (KeycloakPrincipal<KeycloakSecurityContext>) principal;
AccessToken token = kp.getKeycloakSecurityContext().getToken();
Map<String, Object> otherClaims = token.getOtherClaims();

Testing Time

First we need to get access token from below url and use the access token for testing the REST API


Note : After Request Token you need to click Use Token to use token for calling the API.

When we call GET userinfo , we are able to see custom attribute of our login user bob


Source code for this demonstration can be found here.

Java enthusiast and open source contributor

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store