How to Programmatically Manage Keycloak Users with the Admin Client

When using Keycloak, many developers notice that user management is performed through the Keycloak UI, which is convenient but not suitable for programmatic use. To avoid requiring end‑users to access the Admin Console directly, the functionality must be exposed via APIs.

Keycloak Admin Client Introduction

All operations in the Keycloak Admin Console are backed by a specific RESTful API collectively called the Keycloak Admin REST API. The Keycloak Admin Client is a Java HTTP client wrapper for this API, allowing integration by adding a single dependency.

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>${version}</version>
</dependency>

The client is built on JBoss's RestEasy library, which provides annotation‑driven, configuration‑free REST client capabilities and integrates with the JBoss Seam programming model.

No configuration files are needed; annotations and POJOs suffice.

Leverages the JBoss Seam programming model.

These details are optional knowledge; the Keycloak Admin Client abstracts away the complexity.

Using the Keycloak Admin Client

All requests to the Keycloak Admin REST API must include a Bearer Token in the Authorization header. The client must be authenticated with sufficient permissions to perform the desired operations. The following example demonstrates registering a new user.

Create a New User with the Admin Account

The admin user in the Master realm has the highest privileges and can perform any operation.

Keycloak adminCli = KeycloakBuilder.builder()
    .serverUrl("http://localhost:8011/auth/")
    .realm("master")
    .clientId("admin-cli")
    .clientSecret("f7da6497-98ee-455a-87ba-158793134e56")
    .username("admin")
    .password("admin")
    .grantType(OAuth2Constants.PASSWORD)
    .build();

This uses the password grant type, which requires the Direct Access Grants Enabled setting for the admin-cli client.

UserRepresentation user = new UserRepresentation();
user.setUsername("apicreated");
user.setEnabled(true);

CredentialRepresentation cred = new CredentialRepresentation();
cred.setTemporary(false);
cred.setType(CredentialRepresentation.PASSWORD);
cred.setValue("123456");

user.setCredentials(Collections.singletonList(cred));

RealmResource realm = adminCli.realm("master");
UsersResource users = realm.users();
Response response = users.create(user);
System.out.println("response = " + response.readEntity(String.class));

The UserRepresentation object defines the new user with username apicreated and password 123456, which is then created in the Master realm.

Create a User in a Specific Realm

To create a user in a custom realm (e.g., felord.cn), assign the manager‑users role to a Master user and use that account.

Keycloak adminCli = KeycloakBuilder.builder()
    .serverUrl("http://localhost:8011/auth/")
    .realm("master")
    .clientId("admin-cli")
    .clientSecret("86ef2225-14d4-49b1-908e-2b5e058030cc")
    .username("felordadmin")
    .password("123456")
    .grantType(OAuth2Constants.PASSWORD)
    .build();

UserRepresentation user = new UserRepresentation();
user.setUsername("apicreated2");
user.setEnabled(true);

CredentialRepresentation cred = new CredentialRepresentation();
cred.setTemporary(false);
cred.setType(CredentialRepresentation.PASSWORD);
cred.setValue("123456");

user.setCredentials(Collections.singletonList(cred));

RealmResource realm = adminCli.realm("felord.cn");
UsersResource users = realm.users();
Response response = users.create(user);

Use a Service Account to Create Users

Each realm includes a realm-management client that can be enabled for service‑account usage. By configuring client credentials, the client can obtain its own token and perform user management without a human user.

Keycloak adminCli = KeycloakBuilder.builder()
    .serverUrl("http://localhost:8011/auth/")
    .realm("felord.cn")
    .clientId("realm-management")
    .clientSecret("38836e47-2c82-4412-a858-9be2a35aa366")
    .grantType(OAuth2Constants.CLIENT_CREDENTIALS)
    .build();

In this mode, the grant_type is client credentials , meaning the token represents the client rather than a user.

Summary

Creating users via the Keycloak Admin REST API follows the same pattern across different authentication methods. The tutorial covered using the admin‑cli client with password grants, managing users in custom realms, and leveraging service‑account tokens. Future articles will explore Keycloak’s management roles in more depth.