Keycloak

• Установка
• Теория
• Realms
• Clients
• Users
• Roles (роли)
• Группы (groups)
• Практика
• Общая задача
• Базовая авторизация
• Добавление ролей
• Добавление декораторов

Установка

Официальный сайт

Docker:

Для 26 версии:

docker run 
    -p 8080:8080 
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin 
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin 
    quay.io/keycloak/keycloak:26.2.5 start-dev

Для 22 версии:

 docker run 
    -e KEYCLOAK_ADMIN=admin 
    -e KEYCLOAK_ADMIN_PASSWORD=admin 
    -p 8080:8080 quay.io/keycloak/keycloak:22.0.0 
    start-dev

Можно еще напрямую через JDK.

Упрощенный compose 

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.3.2
    container_name: keycloak
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: SecretPassword123
    ports:
      - '0.0.0.0:8180:8080'
    command: start-dev
    volumes:
      - ~/kk/data:/opt/keycloak/data

Для хранения данных либо встроенная база (H2), либо нужно отдельно поднять postgresql:

Обязательно изменить константу KC_HOSTNAME, происходит перенаправление

services:
  postgres:
    image: postgres:15
    container_name: keycloak_postgres
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    ports:
      - "5433:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak_net

  keycloak:
    image: quay.io/keycloak/keycloak:26.2
    container_name: keycloak
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL_HOST: postgres
      KC_DB_URL_DATABASE: keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_HOSTNAME: localhost
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - "9090:8080"
    depends_on:
      - postgres
    networks:
      - keycloak_net

networks:
  keycloak_net:

Dev / prod режимы

Параметр start-dev запускает в режиме dev, предназначен для локальной разработки и тестирования.

• Упрощенный запуск: автоматически применяются настройки, не требующие сложной конфигурации.
• Включён HTTP: можно запускать без HTTPS.
• Отключена проверка сертификатов: удобно для работы с самоподписанными сертификатами.
• Включены developer-friendly endpoints: например, доступ к /admin API может быть менее защищен.
• Более подробные логи: включая stack trace.
• Слабые требования к паролям и политике безопасности.
• Нет ограничений на CORS и Content-Security-Policy, если не заданы явно. 

prod - предназначен для развертывания в боевой среде.

• Требуется HTTPS: нельзя запустить без конфигурации TLS.
• Политики безопасности применяются строго (например, CSP, CORS, защита от CSRF).
• Проверка конфигурации при старте: ошибки в настройке вызовут отказ запуска.
• Пароли и другие секреты не должны быть слабыми.
• Отключены "удобные" фичи, потенциально опасные в проде (dev endpoints и т.д.).
• Подразумевается использование внешней базы данных (а не H2).
• Повышенные требования к производительности и отказоустойчивости.

Теория

По логике система управления доступом должна разрешить/запретить пользователю выполнить действие с данными. Т е

can_do_it = F(user, data, action)

Причем система может быть как размещена снаружи и возвращать да или нет, так быть встроенной в систему и непосредственно блокировать действия. В случае keycloak система размещена снаружи. Предположительная схема взаимодействия: 

Приложение перенаправляет пользователя в Keycloak. Тот запрашивает логин и пароль, возвращает обратно код. Приложение обменивает код на токен и начинает с ним работать. С этого момента пользователь считается авторизованным — можно проверять его права, роли и доступы.

https://www.youtube.com/watch?v=uq2I9z_ZB6Q

Прослойка, объединяющая технологии авторизации.

Функциональность:

• Single-sign on, Single-sign out для браузерных приложений
• Поддержка OpenID/OAuth 2.0/SAML
• Identity Brokering - аутентификация с помощью внешних провайдеров, Social login
• User federation - синхронизация с LDAP / Active directory / Kerberos
• Консоль администратора

Блоки keycloak

Realm

Деление на блоки через realm. Каждый realm изолирован, пользователь принадлежит только одному realm. Содержит конфигурацию, набор приложений и пользователей. Есть административный и остальные realm.

Есть консоль управления реалм и консоль управления аккаунтом.

Клиенты (clients)

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

Области видимости клиентов (client scopes)

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

Роли и группы

Роли - атомарное право или набор прав, который назначается пользователю. Группы - иерархическая структура. Отличия между ролями и группами:

Т е группы служат скорее для удобства управления пользователями в keycloak, фактическое разрешение действий происходит за счет ролей. 

Самое важное: keycloak просто отдает сопоставление пользователь - роль. Группа - дополнительное удобство.

Ограничения на стороне приложения.

Могут быть настроены на уровне realm и client. 

{
  "realm_access": {
    "roles": ["admin"]
  },
  "resource_access": {
    "my-client": {
      "roles": ["editor"]
    }
  }
}

Здесь admin - роль уровня realm, editor - роль уровня client. Роли используются для проверки доступа в коде. Но есть возможность перенести проверку разрешения выполнения endpoint на keycloak.

Консоль управления сервером

Доступ: ip_keycloak:8080/admin

Группы (организационная принадлежность) и роли (набор разрешений). Когда пользователь добавляется в группу, он наследует все роли. Единственная задача keycloak: Пользователь - Разрешение. Внутри роли сопоставляется разрешение. Группа упрощает управление пользователями.

Протоколы и технологии

LDAP

Lightweight Directory Access Protocol - протокол доступа к каталогу пользователей, используемый для хранения и получения информации о пользователях, группах, ролях и другой организационной информации.
Не занимается безопасной аутентификацией сам по себе - только хранит данные.

LDAP = база пользователей и их свойств

Kerberos 

Протокол аутентификации, основанный на криптографии и "билетах".
Позволяет пользователю один раз войти в систему (SSO) и получать доступ к другим сервисам без повторного ввода пароля.
Часто используется в доменных Windows-сетях. Основан на централизованном сервере (KDC - Key Distribution Center).
Kerberos = безопасный вход в систему + SSO

Сервер KDC:

• Центральный сервер в протоколе Kerberos, отвечает за аутентификацию пользователей и выдачу билетов (tickets) для доступа к другим сервисам. KDC состоит из двух основных компонентов:

• Authentication Server (AS) Проверяет логин и пароль пользователя и выдает TGT - ticket-granting ticket (билет доступа к другим билетам).

• Ticket Granting Server (TGS) Получает TGT от пользователя и выдает сервисные билеты (service tickets) - они используются для доступа к конкретным приложениям, например, файловому серверу или веб-приложению.

OAuth 2.0 и OpenID Connect (OIDC)

Открытые протоколы безопасной аутентификации и авторизации пользователей в приложениях и API.

Роли:

• Клиент: приложение, запрашивающее доступ.
• Ресурсный сервер: API с защищенными данными.
• Пользователь: владелец данных.
• Провайдер: сервер, выдающий токены и подтверждающий личность.

OAuth:

• Протокол авторизации. Не занимается аутентификацией пользователя напрямую.

• Главная цель: разрешить приложению доступ к ресурсам пользователя (например, к его файлам, фото) без передачи пароля.

• Работает через выдачу токенов доступа (Access Token).

• Пример: приложение запрашивает у пользователя разрешение читать его документы в Google Docs.

OpenID Connect (OIDC)

• Надстройка над OAuth 2.0, которая добавляет аутентификацию пользователя.

• OpenID Connect расширяет OAuth, чтобы приложение могло не только получить доступ к ресурсам, но и узнать, кто такой пользователь.

• Добавляет понятие ID Token - это отдельный токен (в формате JWT), который содержит информацию о пользователе (имя, email и т.д.).

Типы токенов

• Access Token - доступ к API 
  • Opaque. Непрозрачный токен (например, 8fa3b2e1-cb4e-4fd7-b517-84fc4c2f3a77), просто идентификатор. Для получения деталей ресурсный сервер обращеается к серверу авторизации. Плюсы: безопаснее (минимальные утечки данных через токен), легче отозвать токен централизованно. Минусы: нужен дополнительный сетевой вызов для валидации токена, больше нагрузка на сервер авторизации.
  • JWT самостоятельный токен, в себе несёт всю информацию (пользователь, права, срок жизни и т.д.). Токен подписан, ресурсный сервер проверяет токен без запроса к серверу авторизации. Плюсы: нет лишних сетевых вызовов на проверку и быстрее работает на стороне ресурсных серверов. Минусы: выданный токен нельзя "убить" мгновенно (если только через сложные механизмы типа revocation lists) и токен может содержать чувствительную информацию - важно правильно шифровать или минимизировать payload. Есть сайт jwt.io для просмотра данных из токена.
• Refresh Token - продление действия access token. Отправляется на сервер и сессия продлевается.
• ID Token - (только в OIDC) информация о пользователе

Grant types Технологии, посредством которых клиент получает токен.

Authorization code - получение кода и обмен его на токен доступа

Realms

Деление на блоки через realm. Каждый realm изолирован, пользователь принадлежит только одному realm.  Содержит конфигурацию, набор приложений и пользователей. Есть административный и остальные realm.

Master: административный realm, задачи:

• Управления другими realms (создание, удаление и настройка realms, управление пользователями-администраторами)
• Создание глобальных админов. Роли realm-admin, admin, create-realm и т. д. позволяют входить в Keycloak Admin Console (/admin) и управлять сервером.
• Использование Keycloak'ом для внутренних задач. Системные клиенты и сервисные аккаунты находятся в master realm.
  Примеры: admin-cli, account, broker.

Есть консоль управления реалм. 

Создание realm

Настройка realm в момент создания - только имя

 Имя не должно содержать пробелов и иных символов, плохо воспринимаемых в url адресе.

Настройка realm (realm settings)

В меню Manage realms выбирается реалм, который мы будем редактировать. Затем в левом меню, раздел Configure содержит 4 блока.

OpenID Endpoint configuration - здесь можно увидеть все endpoint настроенные для данного realm. 

Настройка процесса аутентификации. Раздел Authentication используется для настройки и управления потоками аутентификации, обязательными действиями, и политиками входа.
Authentication flow (поток аутентификации) - это набор шагов, через которые проходит пользователь или клиент при входе, регистрации, сбросе пароля и т.д. Каждый поток состоит из действий (executions): например, проверка пароля, OTP, условные переходы, выбор IdP и др. 

Потоки создаются и настраиваются. 

Grant Type - способ, получения Access Token от сервера авторизации в OAuth 2.0 / OpenID Connect. Тип разрешения (grant) определяет, как и при каких условиях клиент получает токены. Keycloak, как реализация Identity Provider и Authorization Server, поддерживает разные grant types (, ). 

Authentication

Настройка потоков аутентификации, обязательных действий и политик входа.
Authentication flow (поток аутентификации) - это набор шагов, через которые проходит пользователь или клиент при входе, регистрации, сбросе пароля и т.д.
Каждый поток состоит из действий (executions): например, проверка пароля, OTP, условные переходы, выбор IdP и др.

У каждого realm свой открытый ключ. С его помощью можно проверять подлинность полученных токенов. После авторизации под любым пользователем выполнить один раз 

KEYCLOAK_PUBLIC_KEY = f"""
-----BEGIN PUBLIC KEY-----
{keycloak_openid.public_key()}
-----END PUBLIC KEY-----
"""

User Federation

Подключение внешних источников пользователей (LDAP, Active Directory или Kerberos).

• пользователи остаются в LDAP/AD/Kerberos;
• Keycloak может их аутентифицировать;
• можно синхронизировать или кэшировать данные (имя, email, роли и т.д.);
• поддерживается одноразовый вход (SSO), если внешняя система это позволяет.
  

SAML

Security Assertion Markup Language - открытый стандарт SSO между разными доменами. Позволяет аутентифицироваться в одной системе и получить доступ к другой, предоставив подтверждение своей аутентификации. Используется с 2005 года и остаётся популярным для федерации идентичности в B2B и B2E-сценариях, особенно в государственном и корпоративном секторе. SAML оперирует:

• XML - для описания данных пользователя
• HTTP - как транспортный протокол
  

Clients

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

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

Раздел Clients

Client list

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

https://myapp.example.com/callback
https://myapp.example.com/oauth/callback
http://localhost:3000/callback  # для разработки
/*                             # любой путь в рамках корневого URL

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

Пример работы с 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 при аутентификации пользователя. Взаимосвязь между атрибутами и scopes: 

Маппер (Mapper) внутри Client Scope — это инструкция для Keycloak: «Возьми данные ОТСЮДА (атрибут, роль, контекст) и положи ИХ В ТОКЕН ПОД ТАКИМ ИМЕНЕМ».

Типы scope:

• Default: всегда включается в токен по умолчанию, даже если клиент не запрашивает его явно.
• Optional: будет включен в токен в случае явного запроса клиентом в параметре scope=... при авторизации.
• (Unassigned): не применяется клиенту вообще, пока его не назначат вручную или не укажут явно в токене.

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

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

Добавление маппера:

Типы мапперов:

{
  "allowed-web-origins": ["http://localhost:3000", "https://myapp.com"],
  ...
}

{
  "iss": "https://keycloak.local/realms/myrealm",
  "sub": "user-123",
  "aud": ["account", "https://api.mycompany.com/v1"],
  ...
}

{
  "iss": "https://keycloak.local/realms/myrealm",
  "sub": "user-123",
  "acr": "1",
  "auth_time": 1699123456,
  ...
}

https://keycloak.local/auth/realms/myrealm/protocol/openid-connect/auth?
    client_id=myapp&
    redirect_uri=https://myapp.com/callback&
    response_type=code&
    scope=openid&
    claims={"userinfo":{"given_name":{"essential":true},"email":null}}

{
  "groups": ["Engineering", "Managers"]
}

Users

Пользователи привязываются к определенной системе реалма.

Roles (роли)

Модели авторизации

Каждая роль может быть переключена в композитный режим (объединение других ролей). Но использовать аккуратно, можно запутаться.

Роли по умолчанию

Область видимости ролей

В текущей версии с настройками ролей есть неявная особенность. Один из вариантов добавления scope через dedicated scopes. Перейдем в Clients -> <client name> -> Client scopes

Scope clientforsimpletest-dedicated называется так, поскольку клиент называется clientforsimpletest. Перейдем в этот scope, вкладку Scope. 

И там есть переключатель Full scope allowed. Он по умолчанию включен, но если его отключить - появляется возможность настройки видимых ролей в рамках клиента. Это дополнительный фильтр. То есть, возможно одному клиенту отправить один набор ролей пользователя, другому клиенту - другой набор. Пример:

Это именно фильтр для конкретного клиента.

Группы (groups)

Настройка групп в реалме. 

Для каждой группы возможны следующие настройки: 

Практика

Общая задача

Задача: Необходимо организовать защиту приложения со следующими требованиями:

• Авторизация по логину и паролю
• Разделение пользователей на группы
  • Администратор (все права)
  • Руководитель (просмотр статистики по всем направлениям)
  • Руководитель направления (права в пределах направления, нет возможности просмотра других направлений)
  • Руководитель предприятия (права в пределах предприятия, нет возможности просмотра других объектов)
• Разделение пользователей по ролям в соответствии с группами
• На backend есть API endpoint и HTML endpoint
• Неавторизованный пользователь имеет доступ к некоторым страницам без авторизации

Реализуем это при помощи декораторов из отдельного модуля. Желательно не хардкодить роли, должно быть внешнее хранилище. 

Базовая авторизация

Реализуем следующий процесс авторизации:

Делаем страницу с проверкой, авторизован или нет пользователь. Если пользователь не авторизован, показываем кнопку Авторизация. Если авторизован - кнопку Выход. Кнопки отличаются ссылками и текстом.

Будем использовать модуль python-keycloak 

pip install python-keycloak

Адресация серверов

192.168.1.3 web server и ПК, с которого я тестирую работу

192.168.1.195 keycloak server

Настройка keycloak.

Создаем realm для данного эксперимента. Назовем его pythonsimpletest.

В разделе Manage realms - Create

Теперь создаем клиента. Назовем его clientforsimpletest. Clients - Create client

 Поскольку этот клиент доверенный и расположен на сервере, то Client authentication включаем, 

И тут проявилась первая ошибка. Localhost виден с моего ПК. Поэтому, когда я прописал на сервере keycloak  в разделе Root URL localhost - ничего не заработало. Похоже, что необходимо указывать имена/ip доступные с сервера keycloak а не только с браузера на ПК пользователя. Результирующие настройки клиента:

Создаем пользователя и задаем ему пароль.

Python клиент

from fastapi import FastAPI, Depends, Request
from fastapi.responses import HTMLResponse, RedirectResponse
from uvicorn import run
from typing import Optional

from keycloak import KeycloakOpenID

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

KEYCLOAK_URL = "http://192.168.1.195:9090/"
REALM_NAME = "pythonsimpletest"
CLIENT_ID = "clientforsimpletest"
CLIENT_SECRET = "Vix6txRyHwt81KyZIpl7O06CxpWMFtib"
REDIRECT_URI = "http://192.168.1.3:8100/auth/callback"

# Инициализация Keycloak клиента
keycloak_openid = KeycloakOpenID(
    server_url=KEYCLOAK_URL,
    client_id=CLIENT_ID,
    realm_name=REALM_NAME,
    client_secret_key=CLIENT_SECRET,
)

   
async def get_current_user_from_cookie(request: Request) -> Optional[dict]:
    """Извлечение и валидация пользователя из cookie"""
    
    # Получаем токен из cookies
    access_token = request.cookies.get("access_token")
    
    if not access_token:
        return None
    
    try:
        # Проверяем токен через Keycloak
        userinfo = keycloak_openid.userinfo(access_token)
        return userinfo
    except Exception as e:
        # Если токен просрочен или невалиден, удаляем его
        # Но здесь мы не можем удалить cookie, это нужно делать в ответе
        return None

def get_login_url():
    """Генерация URL для входа через Keycloak"""
    auth_url = keycloak_openid.auth_url(
        redirect_uri=REDIRECT_URI,
        scope="openid email profile",
        state="random_state_string"  # В реальном приложении используйте генерацию случайной строки
    )
    return auth_url

@app.get("/", response_class=HTMLResponse)
async def simpleauth(request: Request):
    user = await get_current_user_from_cookie(request)
    if not user:
        login_url = get_login_url()
        html_content = f'<!DOCTYPE html><html><body><a href="{login_url}"><button>Авторизация</button></a></body></html>'
    else:
        html_content = '<!DOCTYPE html><html><body><a href="/logout"><button>Выход</button></a></body></html>'
    return HTMLResponse(content=html_content, status_code=200)

@app.get("/auth/callback")
async def auth_callback(code: str):
    """Callback URL для обработки ответа от Keycloak после логина"""
    try:
        # Обмен кода на токены
        token_response = keycloak_openid.token(
            grant_type="authorization_code",
            code=code,
            redirect_uri=REDIRECT_URI
        )
        
        access_token = token_response.get('access_token')
        
        # Создаем редирект с токеном в заголовке (через установку cookie)
        response = RedirectResponse(url="/")
        
        # Устанавливаем токен в cookie (альтернатива Authorization header для браузера)
        response.set_cookie(
            key="access_token",
            value=access_token,
            httponly=True,  # Защита от XSS
            secure=False,   # True для HTTPS
            samesite="lax"
        )
        refresh_token = token_response.get('refresh_token')
        response.set_cookie(
            key="refresh_token",
            value=refresh_token,
            httponly=True,  # Защита от XSS
            secure=False,   # True для HTTPS
            samesite="lax"
        )
        return response
        
    except Exception as e:
        return HTMLResponse(content=f"<h1>Ошибка авторизации: {str(e)}</h1>", status_code=400)

@app.get("/logout")
async def logout(request: Request):
    """Выход из системы"""
    refresh_token = request.cookies.get("refresh_token")
    
    # Логаут через python-keycloak
    if refresh_token:
        try:
            keycloak_openid.logout(refresh_token)
        except Exception as e:
            print(f"Keycloak logout error: {e}")
    response = RedirectResponse(url="/")
    response.delete_cookie("access_token")
    response.delete_cookie("refresh_token")
    return response

if __name__ == '__main__':
    run(app="simple:app", host='0.0.0.0', port=8100, workers=4, log_level='warning')

Добавление ролей

Теперь добавим scopes в токен. Даже просто добавление списка ролей оказалось той еще задачей. Во многих инструкциях будет сказано, что настройка маппера в Keycloak Admin Console -> ваш realm → Clients → ваш клиент -> Вкладка Mappers. Но это не так. Пример настройки для получения ролей:

• Перейди в Client Scopes: Твой realm → Clients → выбери своего клиента → вкладка Client scopes → кликни на дедикейтед скоп *-dedicated (например, my-client-dedicated).
• Открой вкладку Mappers.
• Нажми Configure a new mapper и выбери By configuration.
• Выбери тип маппера: В выпадающем списке выбери User Realm Role.
•     Вот это ключевой момент: использование предустановленного типа, а не создание своего, гарантирует корректную внутреннюю структуру.
• Проверь настройки (они должны заполниться автоматически):
•     Name: Оставь realm roles (или любое другое).
•     Token Claim Name: Убедись, что здесь realm_access . Это единственное правильное имя поля.
•     Add to userinfo: Убедись, что переключатель установлен в ON.
•     Add to access token / Add to ID token: Можно оставить OFF, если роли не нужны в самих JWT токенах.
• Сохрани маппер (кнопка Save).

async def get_current_user_roles(request: Request) -> Optional[dict]:
    """Извлечение ролей"""
    access_token = request.cookies.get("access_token")
    if not access_token:
        return []
    try:
        claims = jwt.get_unverified_claims(access_token)
        roles = claims.get("realm_access", {}).get("roles", [])
        return roles
    except Exception:
        return []
...
@app.get("/", response_class=HTMLResponse)
async def simpleauth(request: Request):
    user = await get_current_user_from_cookie(request)
    if not user:
        login_url = get_login_url()
        html_content = f'<!DOCTYPE html><html><body><a href="{login_url}"><button>Авторизация</button></a></body></html>'
    else:
        roles = await get_current_user_roles(request)
        html_content = f'''<!DOCTYPE html><html><body><a href="/logout"><button>Выход</button></a>
        <p>Доступные ключи: {user.keys()}</p>
        <p>Доступные роли: {roles}</p>
        </body></html>'''
    return HTMLResponse(content=html_content, status_code=200)

Добавление декораторов

Почему-то для fastapi предпочтительнее использовать механизм Depends. Однако мне проще декораторы. 

from functools import wraps

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse, RedirectResponse
from fastapi.concurrency import run_in_threadpool
from uvicorn import run
from typing import Optional

from keycloak import KeycloakOpenID
from jose import jwt
from jose.exceptions import JWTError, ExpiredSignatureError

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

KEYCLOAK_URL = "http://192.168.1.195:9090/"
REALM_NAME = "pythonsimpletest"
CLIENT_ID = "clientforsimpletest"
CLIENT_SECRET = "Vix6txRyHwt81KyZIpl7O06CxpWMFtib"
REDIRECT_URI = "http://192.168.1.3:8100/auth/callback"

KEYCLOAK_PUBLIC_KEY = """-----BEGIN PUBLIC KEY----- 
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAtrnsNk3z21imvfNFDT8teaekNgFhnOSuKcZiPc1Iv+qknDg8X1zF7KJLtZMrCZSLRJM6T754F8KtNUSj0Ioa3ehYSPEdF4SX7tBdacpeDz0GlKWYFa845/e6H2349I+7EuO1bkHfWz/v6n2mm+jeZKU0ujqr2boBoPWwkMoKwXNMl/Sac0YMlv1fVHiISyREDG+FordAwYlbLVYCD36ckk0UnAKBc59Q36DMiKSx7JpdvR0vHIeWb4mQFlRbLdmWkK4ebUe+B/k1/cdd3LHdQ6vc1i45bMcJlrFYocDOGK99Mf8pT8OMPQvTJ8cTe9xSkCAx0l7YiSv+5hfK1C6DswIDAQAB 
-----END PUBLIC KEY-----"""
ALGORITHMS = ["RS256"]

# Инициализация Keycloak клиента
keycloak_openid = KeycloakOpenID(
    server_url=KEYCLOAK_URL,
    client_id=CLIENT_ID,
    realm_name=REALM_NAME,
    client_secret_key=CLIENT_SECRET,
)

# ==============================Декораторы авторизации=========================
def verify_token(token: str):
    return jwt.decode(
        token,
        KEYCLOAK_PUBLIC_KEY,
        algorithms=ALGORITHMS,
        audience="account",
        options={
            "verify_signature": True,
            "verify_aud": False,
            "verify_exp": True,
        }
    )

def get_login_url():
    """Генерация URL для входа через Keycloak"""
    auth_url = keycloak_openid.auth_url(
        redirect_uri=REDIRECT_URI,
        scope="openid email profile",
        state="random_state_string"  # В реальном приложении используйте генерацию случайной строки
    )
    return auth_url

def session_required(func):
    @wraps(func)
    async def wrapper(*args, **kwargs):
        request: Request = kwargs.get("request")
        if request is None:
            for arg in args:
                if isinstance(arg, Request):
                    request = arg
                    break
        if request is None:
            raise RuntimeError("Request object not found")

        token = request.cookies.get("access_token")

        if not token:
            return RedirectResponse(get_login_url())

        try:
            claims = verify_token(token)
            request.state.user = claims
        except ExpiredSignatureError:
            response = RedirectResponse(get_login_url())
            response.delete_cookie("access_token")
            response.delete_cookie("refresh_token")
            return response
        except JWTError:
            response = RedirectResponse(get_login_url())
            response.delete_cookie("access_token")
            response.delete_cookie("refresh_token")
            return response
        return await func(*args, **kwargs)
    return wrapper

def html_norole():
    html_content = f'''<!DOCTYPE html><html><body><a href="/"><button>На главную</button></a>
    <p><a href="/logout"><button>Выход</button></a></p>
    <p>У вас нет доступа к этой странице</p>
    </body></html>'''
    return HTMLResponse(content=html_content, status_code=200)

def role_secondrole_required(func):
    @wraps(func)
    async def wrapper(*args, **kwargs):
        request: Request = kwargs.get("request")
        if request is None:
            for arg in args:
                if isinstance(arg, Request):
                    request = arg
                    break
        if request is None:
            raise RuntimeError("Request object not found")
        userinfo = request.state.user
        roles = userinfo.get("realm_access", {}).get("roles", [])
        if 'secondrole' not in roles:
            return html_norole()
        return await func(*args, **kwargs)
    return wrapper
# =============================================================================

@app.get("/", response_class=HTMLResponse)
@session_required
async def simpleauth(request: Request):
    userinfo = request.state.user #await get_current_user_from_cookie(request)
    roles = userinfo.get("realm_access", {}).get("roles", [])
    
    html_content = f'''<!DOCTYPE html><html><body><a href="/logout"><button>Выход</button></a>
    <p>Доступные ключи: {userinfo}</p>
    <p>Доступные роли: {roles}</p>
    <p><a href="/secret"><button>Доступ к секрету</button></a></p>
    </body></html>'''
    return HTMLResponse(content=html_content, status_code=200)

@app.get("/secret", response_class=HTMLResponse)
@session_required
@role_secondrole_required
async def roleneeded(request: Request):
    html_content = f'''<!DOCTYPE html><html><body><a href="/logout"><button>Выход</button></a>
    <p><a href="/"><button>На домашнюю страницу</button></a></p>
    </body></html>'''
    return HTMLResponse(content=html_content, status_code=200)

@app.get("/auth/callback")
async def auth_callback(code: str):
    """Callback URL для обработки ответа от Keycloak после логина"""
    def append_cookie(response, key, value):
        response.set_cookie(
            key=key,
            value=value,
            httponly=True,  # Защита от XSS
            secure=False,   # True для HTTPS
            samesite="lax"
        )
        return response
    try:
        # Обмен кода на токены
        token_response = keycloak_openid.token(
            grant_type="authorization_code",
            code=code,
            redirect_uri=REDIRECT_URI
        )
        # Создаем редирект с токеном в заголовке (через установку cookie)
        response = RedirectResponse(url="/")
        access_token = token_response.get('access_token')
        # Устанавливаем токен в cookie (альтернатива Authorization header для браузера)
        response = append_cookie(response, "access_token", access_token)
        refresh_token = token_response.get('refresh_token')
        response = append_cookie(response, "refresh_token", refresh_token)
        return response
        
    except Exception as e:
        return HTMLResponse(content=f"<h1>Ошибка авторизации: {str(e)}</h1>", status_code=400)

@app.get("/logout")
async def logout(request: Request):
    """Выход из системы"""
    refresh_token = request.cookies.get("refresh_token")
    if refresh_token:
        try:
            keycloak_openid.logout(refresh_token)
        except Exception as e:
            print(f"Keycloak logout error: {e}")
    response = RedirectResponse(url="/")
    response.delete_cookie("access_token")
    response.delete_cookie("refresh_token")
    return response

if __name__ == '__main__':
    run(app="02_withroles:app", host='0.0.0.0', port=8100, workers=4, log_level='warning')