#Manage Clients

A Client in Keycloak represents an application or service that can request authentication. Each client is registered within a Realm and configured with a specific protocol (OpenID Connect or SAML).

#Client Types

#Create an OIDC Client

# Obtain an admin access token
ACCESS_TOKEN=$(curl -s -X POST \
  "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=<admin-user>" \
  -d "password=<admin-password>" \
  -d "grant_type=password" | jq -r '.access_token')

# Create a confidential OIDC client
curl -s -X POST \
  "https://<keycloak-host>/admin/realms/<realm>/clients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-web-app",
    "enabled": true,
    "protocol": "openid-connect",
    "publicClient": false,
    "redirectUris": ["https://my-app.example.com/*"],
    "webOrigins": ["https://my-app.example.com"],
    "standardFlowEnabled": true,
    "directAccessGrantsEnabled": false,
    "serviceAccountsEnabled": false
  }'

#Create a SAML Client

#Client Secret Management

For confidential clients, Keycloak generates a client secret automatically.

#View or Regenerate a Client Secret

1. In the Admin Console, go to Clients and select the target client.
2. Click the Credentials tab.
3. The current client secret is displayed. Click Regenerate to create a new secret.

#Client Secret Rotation

Client secret rotation is a separate, policy-controlled mechanism that allows zero-downtime secret updates. When rotation is configured, Keycloak maintains multiple active secrets simultaneously during a transition period.

To use client secret rotation:

1. Create a client policy with a Secret Rotation executor (see Client Policies below).
2. Configure the rotation parameters:
   • Secret expiration period — How long a secret remains valid after creation.
   • Rotated secret expiration period — How long the previous (rotated-out) secret remains valid alongside the new one.
   • Remaining expiration period — Minimum remaining validity to trigger rotation.
3. Apply the policy to the target clients.
4. When the policy triggers rotation, Keycloak generates a new secret while keeping the previous secret valid for the configured grace period.
5. Update your application to use the new secret within the grace period.

#Protocol Mappers

Protocol Mappers control what claims are included in the tokens (OIDC) or assertions (SAML) issued for a client.

#Add a Protocol Mapper

1. In the client's detail view, click the Client scopes tab.
2. Click the dedicated scope (for example, my-web-app-dedicated).
3. Click Configure a new mapper or Add mapper > By configuration.
4. Select the mapper type:

5. Configure the mapper name, token claim name, and claim type.
6. Click Save.

#Client Scopes

Client Scopes define reusable sets of protocol mappers and role scope mappings that can be shared across multiple clients.

#Default vs Optional Scopes

#Create a Client Scope

1. In the Admin Console, go to Client scopes.
2. Click Create client scope.
3. Enter a Name (for example, custom-profile).
4. Set Protocol to OpenID Connect or SAML.
5. Set Include in token scope to On if the scope name should appear in the token's scope claim.
6. Click Save.
7. Add protocol mappers to define what claims this scope provides.

#Assign a Client Scope to a Client

1. In the client's detail view, click the Client scopes tab.
2. Click Add client scope.
3. Select the scope and set it as Default or Optional.
4. Click Add.

#Evaluate Scopes

The Evaluate sub-tab in the client scopes view lets you preview the exact token content for a given user and scope combination, which is useful for debugging token claim issues.

#Service Accounts

A Service Account allows a confidential client to authenticate and obtain tokens without a user context (using the client_credentials grant).

#Enable a Service Account

1. In the client Settings tab, enable Service accounts roles.
2. Click Save.
3. Go to the Service account roles tab.
4. Assign realm or client roles to define what the service account can access.

#Obtain a Token with Service Account

curl -s -X POST \
  "https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token" \
  -d "client_id=my-service" \
  -d "client_secret=<client-secret>" \
  -d "grant_type=client_credentials" | jq .

#Client Policies

Client Policies allow administrators to enforce rules on client configurations. A policy consists of conditions (when the policy applies) and profiles (what rules to enforce).

#Built-in Profiles

Keycloak includes profiles for common compliance standards:

#Create a Client Policy

1. Go to Realm Settings > Client policies tab.
2. Click Create policy.
3. Enter a name and description.
4. Add conditions to define which clients the policy applies to (for example, by client role, client scope, or client access type).
5. Add profiles to define the rules enforced on matching clients.
6. Click Save.