KeycloakTokenProvider

@mineflow/auth-web

---

@mineflow/auth-web / KeycloakTokenProvider

Class: KeycloakTokenProvider

Defined in: auth-web/src/keycloak-token-provider.ts:66

Web-реализация порта TokenProvider (@mineflow/client-core) поверх keycloak-js. Слой L3 client-SDK по ADR-0042: единственная задача — дать остальным слоям SDK два метода — «откуда взять свежий access-token» (KeycloakTokenProvider.getToken) и «какие у пользователя роли» (KeycloakTokenProvider.getRoles). Транспорт SDK сам дёргает getToken перед каждым запросом и подставляет заголовок Authorization: Bearer <token>.

Web-only: keycloak-js завязан на браузер (PKCE-redirect, silent-SSO через iframe). Для React Native используется @mineflow/auth-native на react-native-app-auth, реализующий тот же интерфейс TokenProvider.

Логин/логаут провайдер намеренно не оборачивает — управляйте ими через keycloak-js напрямую (keycloak.login() / keycloak.logout()).

Example

import Keycloak from 'keycloak-js';
import { KeycloakTokenProvider } from '@mineflow/auth-web';

const keycloak = new Keycloak({ url, realm: 'mineflow', clientId: 'mineflow-web' });
await keycloak.init({ onLoad: 'check-sso', pkceMethod: 'S256' });

const tokenProvider = new KeycloakTokenProvider({ keycloak });
// отдаётся в MineflowProvider из @mineflow/client-react:
// <MineflowProvider tokenProvider={tokenProvider} roles={tokenProvider.getRoles()} ... />

Implements

• TokenProvider

Constructors

Constructor

new KeycloakTokenProvider(opts: KeycloakTokenProviderOptions): KeycloakTokenProvider;

Defined in: auth-web/src/keycloak-token-provider.ts:75

Parameters

Parameter	Type	Description
opts	KeycloakTokenProviderOptions	Опции провайдера — инициализированный keycloak и необязательный порог авто-refresh KeycloakTokenProviderOptions.minValiditySeconds (по умолчанию 30 секунд).

Returns

KeycloakTokenProvider

Methods

getRoles()

getRoles(): readonly SystemRole[];

Defined in: auth-web/src/keycloak-token-provider.ts:123

Канонические роли текущего пользователя в PascalCase.

Берёт realm-роли из токена (keycloak.realmAccess?.roles) и пропускает их через mapKeycloakRoles: lowercase-алиасы Keycloak → SystemRole, с дедупом и отбрасыванием неизвестных/инфраструктурных ролей (offline_access, uma_authorization и т.п.). Если realm-ролей нет — вернёт пустой массив. Результат обычно отдаётся в MineflowProvider для RBAC-гейтинга UI.

Returns

readonly SystemRole[]

Неизменяемый массив канонических SystemRole.

Implementation of

TokenProvider.getRoles

---

getToken()

getToken(opts?: GetTokenOptions): Promise<string | null>;

Defined in: auth-web/src/keycloak-token-provider.ts:99

Отдаёт текущий access-token, при необходимости упреждающе обновив его.

Вызывает keycloak.updateToken: при opts.forceRefresh — с порогом -1, что форсит refresh независимо от остаточной валидности (используется реактивно транспортом при ответе 401); иначе — с обычным порогом minValiditySeconds, при котором токен рефрешится только если до его истечения осталось меньше порога.

Никогда не бросает при провале refresh: сетевой сбой или протухший refresh-token проглатываются, и возвращается текущий (возможно протухший) токен — мягкая деградация by design. Расчёт на то, что следующий запрос получит 401, транспорт сделает один retry с forceRefresh: true, и если и он не пройдёт — UI инициирует повторный login.

Parameters

Parameter	Type	Description
opts?	GetTokenOptions	Опции запроса токена; forceRefresh: true форсит обновление.

Returns

Promise<string | null>

Access-token строкой либо null, если токена нет (неаутентифицированный пользователь).

Implementation of

TokenProvider.getToken