Managing Keycloak user metadata and custom attributes

Each user that is stored in Keycloak can store basic Metadata information such as name and email. Besides that, you can store arbitrary user attributes, also called Custom Attributes. In this tutorial, we will show an example application which retrieves User Metadata and Custom Attributes for a Keycloak Realm.

This tutorial assumes that you are using the latest version of Keycloak,(powered by Quarkus). If you are new to Keycloak we recommend checking this introduction tutorial: Getting started with Keycloak powered by Quarkus

Firstly, start Keycloak server. We will use port 8180 to avoid conflicts with our application running on Port 8080:

./ start-dev --http-port=8180

Next, create an Admin user. We assume that you have an admin user with “admin” as user and password.

Then, we will create a Realm with an User and some MetaData information in it. You can either create the Keycloak Realm from the UI, or you can use the script available in the “bin” folder of Keycloak.

Here is a basic script which will create:

  • A Keycloak Realm named “security-realm”
  • A Role named “customer-manager”
  • An User named “customer-admin” belonging to the “customer-manager” Role with an email as MetaData
  • A Client application named “customer-manager-client” redirecting to “http://localhost:8080” after login:
./ config credentials --server http://localhost:8180 --realm master --user admin --password admin

./ create realms -s realm=security-realm -s enabled=true -o

./ create users -r security-realm -s username=customer-admin -s enabled=true -s [email protected]

./ set-password -r security-realm --username customer-admin --new-password admin

./ create clients -r security-realm -s clientId=customer-manager-client -s secret="mysecret" -s "redirectUris=[\"http://localhost:8080/*\"]" -s enabled=true

./ create roles -r security-realm -s name=customer-manager

./ add-roles --uusername customer-admin --rolename customer-manager -r security-realm

Creating an application which manages Keycloak’s User Metadata and Custom Attributes

In order to manage Keycloak metadata and attributes we will need the following API:

  • org.keycloak.KeycloakSecurityContext: this interface is required if you need to access to the tokens directly.
  • org.keycloak.KeycloakPrincipal: this class is required to access information (such as MetaData or attributes) from a Keycloak User

Here is a sample Spring Boot Controller which access our user’s MetaData:

package com.example.keycloak.web;

import java.util.Map;
import org.keycloak.KeycloakPrincipal;
import org.keycloak.KeycloakSecurityContext;
import org.keycloak.adapters.springsecurity.token.KeycloakAuthenticationToken;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

public class MyResource {

	@GetMapping(path = "users")
	public String user(KeycloakAuthenticationToken keycloakAuthenticationToken) {
		KeycloakPrincipal<KeycloakSecurityContext> principal = (KeycloakPrincipal<KeycloakSecurityContext>) keycloakAuthenticationToken

		StringBuffer html = new StringBuffer();
		html.append("Principal: "+principal.getName());
		html.append("<br />");   

		html.append("<br />");   

		return html.toString();


As you can see from the code, we are retrieving the Principal’s name and some Metadata (the email address).

In order to bind the “/users” REST Endpoint with the “customer-manager” Role, we need to plug-in a org.keycloak.adapters.springsecurity.KeycloakConfiguration class:

public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

	public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
		KeycloakAuthenticationProvider keycloakAuthenticationProvider = keycloakAuthenticationProvider();
		keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(new SimpleAuthorityMapper());

	protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
		return new RegisterSessionAuthenticationStrategy(new SessionRegistryImpl());

	public KeycloakConfigResolver KeycloakConfigResolver() {
		return new KeycloakSpringBootConfigResolver();

	protected void configure(HttpSecurity http) throws Exception {



Finally, we need to specify the Client information and the Keycloak Realm in the configuration file:


keycloak.realm = security-realm
keycloak.auth-server-url = http://localhost:8180
keycloak.resource = customer-manager-client
keycloak.credentials.secret = mysecret

The full source code for this application is available at the end of this tutorial.

Next, start the Spring Boot application:

$ mvn install spring-boot:run

Then, move to the following pag: http://localhost:8080/users

The keycloak Login UI will prompt:

Enter “customer-admin” / “admin” as User and Password. You will see that the Principal’s name and the email will be printed on the screen:
Principal: cc0f4da7-eeb5-4925-906b-1032e561a9fc
[email protected]

Adding Custom attributes to our Realm

Well done! the first part of our example is now complete. Let’s add a Custom Attribute to our user. Custom Attributes are used to extend the basic Metadata information available to Users.

We will add a Custom Attribute from Keycloak Admin application. Select the Users Panel and check the Attributes Tab. There Click to Add an Attribute and Save it.

keycloak custom attributes tutorial
We have now added the Custom Attribute. To make this attribute available to our Client application, we need to create a Protocol Mapper. From your Clients Panel, select the customer-manager-client and the Mappers Tab and click on Create:

Above you can see the Mapper that has been added for the User attribute ““. Save the Mapper.

Fetching Custom attributes from your application

Now that your Keycloak Realm includes a Custom attribute, let’s enhance our application to iterate through the Custom Attributes. Within our Controller application, we will add the following iteration:

Map<String, Object> customClaims = (principal.getKeycloakSecurityContext().getToken().getOtherClaims());
for (Map.Entry<String, Object> entry : customClaims.entrySet()) {
	html.append(entry.getKey() + "/" + entry.getValue());
	html.append("<br />");

As you can see, from your Keycloak Token we collect the “other claims” and we print the list of keys, values.

If you run again the application, you will see all Custom Attributes available in the Token;

Principal: cc0f4da7-eeb5-4925-906b-1032e561a9fc
[email protected]


We have covered how to define MetaData and Custom Attributes for Keycloak Users and how to fetch them from a Java application. The source code for this tutorial is available here: