# Adding and Managing Users in Keycloak

Users in Keycloak represent the individuals or system accounts that authenticate and interact with your applications. This guide explains multiple methods to create and manage users via the Admin Console, REST API, and Docker CLI while covering required roles, best practices, and common issues.

## **Creating Users via Keycloak Admin Console**

The Admin Console is the most user-friendly method to manage users and assign roles.

#### **Access the Admin Console**

Log in to your Keycloak Admin Console:

```
http://<your-keycloak-domain>/admin/
```

Choose the realm where you want to manage users.

#### **Add a New User**

1. <span class="s1">Go to </span>**Users &gt; Add User**
2. Fill in the following:
    
    
    - <span class="s1">**Username**</span> (required)
    - <span class="s1">**Email**</span>, <span class="s1">**First Name**</span>, <span class="s1">**Last Name**</span> (optional but recommended)
    - Set <span class="s1">**Email Verified**</span> if applicable
3. Click <span class="s1">**Create**</span>

[![image.png](https://docs.elest.io/uploads/images/gallery/2025-06/scaled-1680-/Sdmimage.png)](https://docs.elest.io/uploads/images/gallery/2025-06/Sdmimage.png)

#### **Set Credentials**

After creating the user:

1. Go to the <span class="s1">**Credentials**</span> tab
2. Set a password
3. Toggle <span class="s1">**Temporary**</span> to <span class="s2">OFF</span> if you don’t want the user to reset on first login
4. <span class="s1">Click </span>**Set Password**

## **Creating Users via Keycloak REST API**

This method is suitable for CI/CD pipelines or automated scripts.

#### **Get Access Token**

```bash
curl -X POST "https://<keycloak-domain>/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin-password" \
  -d "grant_type=password" \
  -d "client_id=admin-cli"
```

Copy the <span class="s1">access\_token</span> from the response.

#### **Create User**

```bash
curl -X POST "https://<keycloak-domain>/admin/realms/<realm>/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "username": "johndoe",
    "email": "johndoe@example.com",
    "enabled": true,
    "emailVerified": true,
    "firstName": "John",
    "lastName": "Doe"
  }'
```

#### **Set Password**

```bash
curl -X PUT "https://<keycloak-domain>/admin/realms/<realm>/users/<user-id>/reset-password" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "password",
    "value": "StrongPassword123!",
    "temporary": false
  }'
```

To get <span class="s1">&lt;user-id&gt;</span>, call:

```bash
curl -H "Authorization: Bearer <access_token>" \
  https://<keycloak-domain>/admin/realms/<realm>/users?username=johndoe
```

## **Creating Users via Docker CLI** 

#### **Step into the Container**

```bash
docker exec -it keycloak bash
```

#### **Use Admin CLI Script**

```bash
/opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 \
  --realm master --user admin --password admin

/opt/keycloak/bin/kcadm.sh create users -r <realm> -s username=jane -s enabled=true
```

#### **Set Password**

```
/opt/keycloak/bin/kcadm.sh set-password -r <realm> --username jane --new-password "SecurePass!123"
```

### **Required Permissions for User Management**

- Requires <span class="s1">manage-users</span> role in the realm.
- Admin token used via CLI or REST must be scoped with user management privileges.

To assign permission via Admin Console:

```bash
Users > admin > Role Mappings > Realm Roles > Assign 'manage-users'
```

## **Best Practices for Managing Users**

**Use Verified Emails**

Ensure <span class="s2">emailVerified</span> is set to true for pre-created users to skip email confirmation.

**Avoid Temporary Passwords for API Imports**

If scripting user creation, set <span class="s2">temporary: false</span> to avoid forcing password reset on first login.

**Group Users by Role or Department**

Organize users into <span class="s3">**groups**</span> (e.g., devs, sales, ops) for easier role management and policy application.

**Monitor Login History**

Enable event logging to track user login activity under <span class="s3">**Events &gt; Settings**</span>.

**Enforce Strong Passwords**

Go to <span class="s3">**Authentication &gt; Password Policy**</span> and configure rules like minimum length, digits, special chars, etc.

## **Common Issues and Troubleshooting**

<table border="1" id="bkmrk-issue-possible-cause" style="border-collapse: collapse; border-color: rgb(0, 0, 0);"><thead><tr><th style="border-color: rgb(0, 0, 0);">**Issue**

</th><th style="border-color: rgb(0, 0, 0);">**Possible Cause**

</th><th style="border-color: rgb(0, 0, 0);">**Solution**

</th></tr></thead><tbody><tr><td style="border-color: rgb(0, 0, 0);">409 Conflict: User exists

</td><td style="border-color: rgb(0, 0, 0);">Username already taken

</td><td style="border-color: rgb(0, 0, 0);">Use a unique username or search existing users

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">403 Forbidden<span class="s1"> on API</span>

</td><td style="border-color: rgb(0, 0, 0);">Missing permission or token scope

</td><td style="border-color: rgb(0, 0, 0);">Ensure admin has <span class="s1">manage-users</span> in the correct realm

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">User not able to log in

</td><td style="border-color: rgb(0, 0, 0);">Password not set or user is disabled

</td><td style="border-color: rgb(0, 0, 0);">Check status under the user’s profile and verify credentials

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Password reset fails

</td><td style="border-color: rgb(0, 0, 0);">Temporary password not set correctly

</td><td style="border-color: rgb(0, 0, 0);">Use <span class="s1">"temporary": false</span> if you want permanent password via API

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Email not received for verification

</td><td style="border-color: rgb(0, 0, 0);">SMTP not configured

</td><td style="border-color: rgb(0, 0, 0);">Go to <span class="s1">**Realm Settings &gt; Email**</span> and add SMTP server details

</td></tr></tbody></table>