Keycloak — IO7 Framework

Внимание

Данная статья документации написана нейросетью. Возможны некоторые расхождения и неточность информации!

Обзор

IO\Auth\KeycloakManager — класс интеграции с Keycloak для enterprise SSO. Поддерживает OpenID Connect: authorization code flow, обновление токенов, интроспекцию, получение информации о пользователе. Реализован как singleton.

Инициализация

$keycloak = \IO\Auth\KeycloakManager::init([
    'base_url' => 'https://auth.example.com',
    'realm' => 'my-realm',
    'client_id' => 'my-client',
    'client_secret' => 'my-secret',
]);

Конфигурация

ПараметрТипЗначение по умолчаниюОбязателенОписание
base_urlstring—ДаБазовый URL Keycloak (обязательный)
realmstring—ДаИмя.realm (обязательный)
client_idstring—ДаИдентификатор клиента (обязательный)
client_secretstring—ДаСекрет клиента (обязательный)

Методы

init(array $config): self

Инициализация KeycloakManager.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$configarray{base_url: string, realm: string, client_id: string, client_secret: string}—ДаКонфигурация
ВозвратselfЭкземпляр KeycloakManager

getInstance(): self

Получить singleton-инстанс.

ПараметрТипЗначение по умолчаниюОбязателенОписание
ВозвратselfЭкземпляр KeycloakManager
ИсключениеRuntimeExceptionЕсли инстанс не инициализирован
$keycloak = KeycloakManager::getInstance();

connect(string $baseUrl, string $realm, string $clientId, string $clientSecret): self

Подключение к Keycloak.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$baseUrlstring—ДаБазовый URL Keycloak
$realmstring—ДаИмя.realm
$clientIdstring—ДаИдентификатор клиента
$clientSecretstring—ДаСекрет клиента
ВозвратselfЭкземпляр KeycloakManager
$keycloak->connect('https://auth.example.com', 'my-realm', 'client', 'secret');

getAuthorizationUrl(string $redirectUri, array $scopes = []): string

Получить URL для авторизации.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$redirectUristring—ДаURI для回调а
$scopesarray<string>['openid']НетЗапрашиваемые скоупы (по умолчанию ['openid'])
ВозвратstringURL для авторизации
$url = $keycloak->getAuthorizationUrl('https://example.com/callback', ['openid', 'email']);
header('Location: ' . $url);

handleCallback(string $code, string $redirectUri): array

Обработать callback — обменять код на токены и получить данные пользователя.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$codestring—ДаAuthorization code
$redirectUristring—ДаURI для callbackа
Возвратarray{access_token: string, refresh_token: string, user: array}Токены и данные пользователя
ИсключениеRuntimeExceptionПри ошибке обмена кода на токен
$data = $keycloak->handleCallback($code, 'https://example.com/callback');
$accessToken = $data['access_token'];
$refreshToken = $data['refresh_token'];
$userInfo = $data['user'];

refreshToken(string $refreshToken): array

Обновить токен.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$refreshTokenstring—ДаRefresh token
Возвратarray{access_token: string, refresh_token: string}Новые токены
ИсключениеRuntimeExceptionПри ошибке обновления
$tokens = $keycloak->refreshToken($oldRefreshToken);
$newAccessToken = $tokens['access_token'];

getUserInfo(string $accessToken): ?array

Получить информацию о пользователе по access token.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$accessTokenstring—ДаAccess token
Возвратarray|nullИнформация о пользователе
$userInfo = $keycloak->getUserInfo($accessToken);

revokeToken(string $token): bool

Отзыв токена.

ПараметрТипЗначение по умолчаниюОбязателенОписание
$tokenstring—ДаТокен для отзыва
ВозвратboolУспешность отзыва
$keycloak->revokeToken($accessToken);

introspectToken(string $token): ?array

Интроспекция токена (проверка активности и метаданных).

ПараметрТипЗначение по умолчаниюОбязателенОписание
$tokenstring—ДаТокен для интроспекции
Возвратarray|nullМетаданные токена
$tokenInfo = $keycloak->introspectToken($accessToken);
if ($tokenInfo !== null && $tokenInfo['active']) {
    echo 'Токен активен';
}

getWellKnownConfig(): ?array

Получить конфигурацию Keycloak (.well-known/openid-configuration).

ПараметрТипЗначение по умолчаниюОбязателенОписание
Возвратarray|nullКонфигурация OpenID Connect
$config = $keycloak->getWellKnownConfig();

Пример: Полный цикл авторизации

// 1. Инициализация
$keycloak = \IO\Auth\KeycloakManager::init([
    'base_url' => getenv('KEYCLOAK_BASE_URL'),
    'realm' => getenv('KEYCLOAK_REALM'),
    'client_id' => getenv('KEYCLOAK_CLIENT_ID'),
    'client_secret' => getenv('KEYCLOAK_CLIENT_SECRET'),
]);

// 2. Редирект на авторизацию
$authUrl = $keycloak->getAuthorizationUrl(
    'https://myapp.example.com/auth/callback',
    ['openid', 'profile', 'email']
);
header('Location: ' . $authUrl);

// 3. Обработка callback
$code = $_GET['code'];
$data = $keycloak->handleCallback($code, 'https://myapp.example.com/auth/callback');

// 4. Сохранение токенов
$session = \IO\Session::create();
$session->setOAuth2Token($data['access_token'], $data['refresh_token']);

// 5. Получение информации о пользователе
$userInfo = $data['user'];
echo 'Привет, ' . $userInfo['name'];

Пример: Обновление токена

$keycloak = KeycloakManager::getInstance();
$refreshToken = $session->getOAuth2RefreshToken();

if ($refreshToken !== null) {
    try {
        $tokens = $keycloak->refreshToken($refreshToken);
        $session->setOAuth2Token($tokens['access_token'], $tokens['refresh_token']);
    } catch (\RuntimeException $e) {
        header('Location: /auth/login');
    }
}

Конфигурация .env

KEYCLOAK_BASE_URL=https://auth.example.com
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=my-client
KEYCLOAK_CLIENT_SECRET=my-secret