Токени користувацької площини

Обміняйте логін-сесію на короткоживучий токен під цей сервіс — і як мапляться ролі.

Користувацька площина приймає рівно один вид токена: короткоживучий exchange-токен, викарбуваний identity provider-ом (auth.console) з audience provider-credentials-service. Логін/менеджмент-токен — навіть валідний — відхиляється: дисципліна audience — це один JWT, один цільовий сервіс.

Флоу

1. Залогіньтеся в identity provider: POST /v1/auth/login. Акаунти, що належать кільком організаціям, отримують status: org_selection_required і завершують через POST /v1/auth/select-org — обрана організація стає org_id токена.
2. Обміняйте сесію на токен, скоуплений під сервіс: POST /v1/auth/token/exchange з {"audience": "provider-credentials-service"}. Результат — access-only JWT (ES256, живе хвилини, без refresh), що несе sub (UUID користувача), org_id і сирі організаційні roles.
3. Викликайте цей сервіс із Authorization: Bearer <token>. Коли токен спливе — обміняйте знову: ваш якір оновлення — логін-сесія, а не цей сервіс.

import httpx

auth = httpx.post(f"{AUTH_BASE}/v1/auth/login", json={"email": EMAIL, "password": PASSWORD}).json()
# ... handle org selection / MFA states per the auth service's own docs ...
exchange = httpx.post(
    f"{AUTH_BASE}/v1/auth/token/exchange",
    headers={"Authorization": f"Bearer {auth['access_token']}"},
    json={"audience": "provider-credentials-service"},
).json()
TOKEN = exchange["access_token"]

Identity provider публікує власну wiki для розробників із повною state-машиною логіну; ця сторінка покриває лише те, що цьому сервісу від нього потрібно.

Що мусить нести токен

• iss/aud — сконфігурований issuer і provider-credentials-service; будь-що інше — 401.
• sub — користувач, канонічний UUID (неканонічні форми відхиляються).
• org_id — опційний; якщо присутній — канонічний UUID. Відсутній означає: без контексту організації — Organization Credentials відповідає 403, а Credential Status звітує null для рівня org.
• roles — сирі ролі організації (owner, admin, member, viewer).

Як мапляться ролі

Два незалежні мапінги читають той самий клейм roles:

1. Сервісні ролі (JWT_ROLE_MAP, за замовчуванням owner→user, admin→user, member→user): дає роль §5.1, що ґейтить ендпоїнти. viewer не мапиться ні в що — такі токени отримують 401. Підвищені ролі (provider_admin, auditor) за замовчуванням ніколи не виводяться з org-ролей; надати їх — свідоме рішення деплойменту.
2. Менеджери організації (JWT_ORG_MANAGER_ROLES, за замовчуванням owner,admin): перевіряються проти сирих ролей і ґейтять Organization Credentials — навмисно переживаючи сплющення з пункту вище.

Тож деплоймент за замовчуванням читається так: кожен учасник організації — це user; лише owner-и та admin-и керують credentials організації.