Creating and Configuring Clients in Keycloak

client in Keycloak represents an application or service that uses Keycloak to authenticate users. Clients can be web apps, REST APIs, mobile apps, or even CLI tools. This guide explains how to create and configure clients through the Admin Console, REST API, and CLI (Docker), and also includes roles, best practices, and common troubleshooting steps.

Creating Clients via Keycloak Admin Console

This is the simplest way to register and configure a client visually.

Access the Admin Console

Log in to:

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

Choose the realm where the client should be added.

Add a New Client

  1. Go to Clients > Create

  2. Fill in the fields:

     

    • Client ID: A unique name, e.g., frontend-app or api-service

    • Client Type: Choose between OpenID Connect (default) or SAML

    • Root URL: The application base URL (e.g., http://localhost:3000)

     

  3. Click Next, then Saveimage.png

Configure Client Settings

Creating Clients via Keycloak REST API

Get Access Token

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"

Save the access_token.

Create a Client

curl -X POST "https://<keycloak-domain>/admin/realms/<realm>/clients" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-app",
    "enabled": true,
    "publicClient": false,
    "redirectUris": ["http://localhost:3000/*"],
    "webOrigins": ["http://localhost:3000"],
    "protocol": "openid-connect"
  }'

This creates a confidential client named my-app.

Creating Clients via Docker CLI 

Step into the Container

docker exec -it keycloak bash

Authenticate and Create Client

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

/opt/keycloak/bin/kcadm.sh create clients -r <realm> \
  -s clientId=my-cli-client \
  -s enabled=true \
  -s publicClient=false \
  -s redirectUris='["http://localhost:3000/*"]' \
  -s webOrigins='["http://localhost:3000"]'

Required Permissions for Client Management

To grant roles via Admin Console:

Users > admin > Role Mappings > Realm Roles > Assign 'manage-clients'

Best Practices for Client Configuration

Common Issues and Troubleshooting

Issue

Possible Cause

Solution

Invalid redirect URI

Redirect URI doesn’t match registered value

Ensure exact match in Valid Redirect URIs

Client not visible after creation

UI or API delay

Refresh or re-login to see updated clients

Access token doesn’t include roles

Missing mappers

Add protocol mapper for client roles under Client > Mappers

403 Forbidden when using client credentials

Client type is public or secret is wrong

Verify publicClient=false and check the client secret

Invalid client credentials error

Wrong client ID or secret

Verify spelling and match values from Admin Console

 


Revision #1
Created 17 June 2025 11:46:20 by kaiwalya
Updated 17 June 2025 11:58:06 by kaiwalya