Keycloak API

Keycloak provides Admin REST API for realm management and standard OIDC endpoints.

Overview

Admin API

https://keycloak-01.inside.domusdigitalis.dev/admin/realms/{realm}/

OIDC

https://keycloak-01.inside.domusdigitalis.dev/realms/{realm}/protocol/openid-connect/

Auth

Bearer token (admin-cli client)

Format

JSON

Realm

domus

Get Admin Token

# Get admin token using admin-cli client
TOKEN=$(curl -ks -X POST \
  "https://$KC_HOST/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=$KC_USER" \
  -d "password=$KC_PASS" \
  -d "grant_type=password" | jq -r '.access_token')

Admin API Examples

List Realms

curl -ks -H "Authorization: Bearer $TOKEN" \
  "https://$KC_HOST/admin/realms" | jq '.[].realm'

List Users

curl -ks -H "Authorization: Bearer $TOKEN" \
  "https://$KC_HOST/admin/realms/domus/users" | jq '.[] | {username, email, enabled}'

List Clients

curl -ks -H "Authorization: Bearer $TOKEN" \
  "https://$KC_HOST/admin/realms/domus/clients" | jq '.[] | {clientId, enabled}'

Get User Sessions

curl -ks -H "Authorization: Bearer $TOKEN" \
  "https://$KC_HOST/admin/realms/domus/users/{user-id}/sessions" | jq

OIDC Endpoints

# OIDC Endpoints:
# /realms/{realm}/protocol/openid-connect/auth - Authorization
# /realms/{realm}/protocol/openid-connect/token - Token
# /realms/{realm}/protocol/openid-connect/userinfo - UserInfo
# /realms/{realm}/protocol/openid-connect/logout - Logout
# /realms/{realm}/protocol/openid-connect/certs - JWKS
# /realms/{realm}/.well-known/openid-configuration - Discovery

OIDC Examples

Get OIDC Config

curl -ks "https://$KC_HOST/realms/domus/.well-known/openid-configuration" | jq

Client Credentials Flow

curl -ks -X POST "https://$KC_HOST/realms/domus/protocol/openid-connect/token" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq

Environment Setup

# Load from dsec
dsource d000 dev/identity

# Or manually
export KC_HOST="keycloak-01.inside.domusdigitalis.dev"
export KC_USER="admin"
export KC_PASS="<from gopass>"
export KC_REALM="domus"

Learnings

Keycloak API Gotchas

  • Admin token obtained via admin-cli client credentials

  • Token expires - refresh or re-authenticate for long sessions

  • User IDs are UUIDs, not usernames

  • Realm name is case-sensitive

  • Standard OIDC endpoints at /.well-known/openid-configuration