How to Use the Command 'kcadm.sh' (with Examples)

The kcadm.sh command-line tool is a powerful utility for administering Keycloak, an open-source identity and access management solution. Keycloak provides features such as single sign-on, identity brokering, and user federation. The kcadm.sh tool allows administrators to perform various administrative tasks by interacting with the Keycloak server from a terminal, offering a scriptable approach to manage and automate system administration tasks. This article covers several key use cases of the kcadm.sh command, providing you with examples to demonstrate its practical applications.

Use case 1: Start an Authenticated Session

Code:

kcadm.sh config credentials --server host --realm realm_name --user username --password password

Motivation: Starting an authenticated session is typically the first step when using the kcadm.sh tool. To perform any administrative operation on the Keycloak server, you need to establish a session with the correct credentials. This session verifies your identity and grants you access rights to interact with specific realms or perform administrative tasks.

Explanation:

• config credentials: This is the primary action of configuring and establishing credentials.
• --server host: Specifies the Keycloak server’s URL where the administration tasks will be performed.
• --realm realm_name: Indicates the realm under which the session will be authenticated. A realm in Keycloak is a space where users, roles, and clients exist.
• --user username: Provides the username of the account you will authenticate as. This user must have the necessary permissions to perform admin tasks on the specified realm.
• --password password: Supplies the password for the specified username to authenticate the session.

Example output:
Upon successful execution, the command does not produce verbose output but establishes the session. However, if credentials are incorrect or the server is unreachable, it might return an error such as “Invalid username or password” or a “Server not found” message.

Use case 2: Create a User

Code:

kcadm.sh create users -s username=username -r realm_name

Motivation: Creating a user is a fundamental administrative task that allows you to add new identities into the Keycloak system for authentication and authorization. Whether you’re setting up a new system or expanding existing user capabilities, adding users is one of the core functions of identity management.

Explanation:

• create users: Indicates the creation of a new user account within Keycloak.
• -s username=username: Utilizes the -s flag to set the attribute for the user with the specified username. This is the identifier for the new user being created.
• -r realm_name: Denotes the realm within which the new user will be created. Users are scoped to realms, and this specifies the container for managing users and permissions.

Example output: Upon successful execution, Keycloak creates the user with minimal output. You may receive JSON feedback showing user details if verbose mode was enabled or an error message if the operation fails (e.g., “User already exists”).

Use case 3: List All Realms

Code:

kcadm.sh get realms

Motivation: Listing all realms is essential for administrators to understand the different authentication environments configured within Keycloak. As realms are segmentation boundaries containing separate sets of users, roles, and clients, grasping their configuration is crucial for system overview and management.

Explanation:

• get realms: The action get retrieves information about specified entities, in this case, all available realms in the Keycloak system. Without additional filters, this command provides a complete list.

Example output:
Execution results in a JSON format list of all realms configured in the system. A typical output might include properties such as realm names, IDs, and other configuration settings related to each available realm.

Use case 4: Update a Realm with JSON Config

Code:

kcadm.sh update realms/realm_name -f path/to/file.json

Motivation: Updating a realm’s configuration allows administrators to modify existing realm settings or import configurations from an external source to align with security policies or new business rules. This task is especially useful when deploying changes across various environments or applying comprehensive settings updates.

Explanation:

• update realms/realm_name: Specifies the update action on a particular realm. Here, realm_name denotes the exact realm you intend to update.
• -f path/to/file.json: The -f flag introduces a file input, representing a JSON configuration file. This file contains the key-value pairs of settings to be applied to the realm, ensuring consistency and accuracy in configuration management.

Example output: This command generally returns success confirmation without extensive output, reflecting the updated configuration applied to the specified realm. However, errors can occur if the JSON file contains invalid syntax or non-existing paths, leading to feedback such as “Invalid JSON configuration”.

Conclusion:

The kcadm.sh tool provides a versatile command-line interface for efficiently managing Keycloak environments. By understanding and leveraging its various commands, administrators can automate tasks, reduce manual configuration overhead, and ensure consistent application of identity and access management policies across their systems. Each use case demonstrated above shows how powerful and essential this tool is for maintaining secure and well-managed authentication environments in Keycloak.