Clients

Клиенты - сущности, которые могут отправлять запрос в Keycloak на аутентификацию пользователя. Чтобы приложение могло использовать ресурсы keycloak, оно должно быть зарегистрировано. Клиенты делятся по идентификаторам.

Настройка через консоль управления реалмом, раздел клиенты. Желательно настраивать на каждый сервер / сервис отдельный клиент.

Раздел Clients

Client list

Client list - список клиентов. Параметры настройки клиента:

Клиенты по умолчанию в Master realm:

Название	Описание	Адрес
account	Клиент пользовательского личного кабинета. Управление профилем, просмотр сеансов входа и разрешения.	/realms/{realm}/account
account-console	Фронтенд клиента account, вызывающий API account.
admin-cli	Клиент взаимодействия с Keycloak через CLI или REST API. Например получение токена через kcadm.sh или curl для скриптов/CI/CD. Поддерживает client_credentials и password гранты.
broker	Внутренний клиент для федерации идентичности (SSO между провайдерами). Пример: Keycloak как Identity Broker между Google, GitHub и другим Keycloak сервером.
master-realm	Формальный клиент, представляющий сам master realm. Часто используется для определённых внутренних механизмов и ссылок в Admin Console.
security-admin-console	Клиент для административной консоли Keycloak. Используется при входе в админ-панель, управлении реалмами, пользователями и клиентами.	/admin/{realm}/console

Пример работы с admin-cli:

import requests

def get_keycloak_token():
    url = "http://192.168.1.195:9090/realms/master/protocol/openid-connect/token"
    payload = {
        "grant_type": "password",
        "client_id": "admin-cli",
        "username": "admin",
        "password": "admin",
    }
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    response = requests.post(url, data=payload, headers=headers)
    # Проверка на ошибки HTTP
    response.raise_for_status()
    print(response.json())

get_keycloak_token()

Ответ сервера:

{
  'access_token': hbG...L7A', 
  'expires_in': 60, 
  'refresh_expires_in': 1800, 
  'refresh_token': 'hbG...gcQ', 
  'token_type': 'Bearer', 
  'not-before-policy': 0, 
  'session_state': 'f...c', 
  'scope': 'profile email'
}

Если затем сформировать например get запрос к endpoint /admin/realms с заголовком Authorization Brearer <access_token> то будет доступ. Полный пример запроса:

import requests

BASE_URL = "http://192.168.1.195:9090"

def get_keycloak_token():
    url = f"{BASE_URL}/realms/master/protocol/openid-connect/token"
    payload = {
        "grant_type": "password",
        "client_id": "admin-cli",
        "username": "admin",
        "password": "admin",
    }
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    response = requests.post(url, data=payload, headers=headers)
    response.raise_for_status()
    return response.json()["access_token"]

def get_realms(access_token: str):
    url = f"{BASE_URL}/admin/realms"
    headers = {
        "Authorization": f"Bearer {access_token}"
    }
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()

if __name__ == "__main__":
    try:
        token = get_keycloak_token()
        realms = get_realms(token)
        print("Realms:")
        for realm in realms:
            print("-", realm.get("realm"))
    except requests.HTTPError as e:
        print("HTTP error:", e.response.text)
    except Exception as e:
        print("Unexpected error:", str(e))

Client registration

Параметры, которые будут применяться к пользователям, зарегистрированным в клиентах.

Раздел client scopes

Определяет данные и разрешения, получаемые клиентом в access token / ID token при аутентификации пользователя.

Типы scope:

Default: всегда включается в токен по умолчанию, даже если клиент не запрашивает его явно.

Optional: будет включен в токен в случае явного запроса клиентом в параметре scope=... при авторизации.

(Unassigned): не применяется клиенту вообще, пока его не назначат вручную или не укажут явно в токене.

Стандартные scopes:

Название	Тип	Протокол	Назначение
acr	Default	OpenID Connect	добавляет в токен acr (Authentication Context Class Reference) - уровень аутентификации (например, MFA, пароль и т. д.).
address	Optional	OpenID Connect	добавляет адрес пользователя (address claim) в токен (если заполнено в профиле).
basic	Default	OpenID Connect	включает базовые claims - sub, name, preferred_username, given_name, family_name
e-mail	Default	OpenID Connect	добавляет email и email_verified в ID и Access токены
microprofile-jwt	Optional	OpenID Connect	обеспечивает совместимость с Eclipse MicroProfile JWT - популярным стандартом для Java microservices
offline_access	Optional	OpenID Connect	разрешает выдачу offline refresh token (живёт долго и используется без пользовательского взаимодействия).
role_list	Default	SAML	включает список ролей (roles) пользователя в SAML assertions
roles	Default	OpenID Connect	добавляет роли пользователя (realm roles и client roles) в access token (в realm_access.roles и resource_access)

Также есть phone, profile