Регистрация и настройка OAuth-клиента

OAuth-клиент — это запись, которая представляет ваше приложение перед SSO-сервером: по ней проверяется, кто запрашивает вход, куда можно редиректить пользователя и какие данные о нём отдавать. Один клиент обычно соответствует одному приложению или одному направлению интеграции (веб-версия и CLI одного продукта могут быть как одним клиентом, так и двумя — в зависимости от того, нужны ли им разные redirect URI и разный набор scope).

Создание клиента

GET  /admin/clients/new
POST /admin/clients/new

Доступно org-admin (клиент создаётся сразу в вашей организации, поле organizationId подставляется автоматически и недоступно для редактирования) и глобальному администратору.

Поля формы

Поле	Обязательно	Описание
`name`	✓	Название приложения — показывается пользователю на экране согласия и на странице входа
`description`	—	Внутреннее описание, не показывается пользователю
`website`	—	Ссылка на сайт приложения
`redirectUris`	✓	Список разрешённых redirect URI, по одному на строку. Точное совпадение — без него `/authorize` отклонит запрос
`allowedScopes`	—	Список scope через пробел, которые клиент вправе запрашивать. Пусто — разрешены все. Применяется и к Authorization Code, и к Client Credentials. Какие scope есть и когда какой запрашивать — reference/appendix-scopes.md
`requirePkce`	—	По умолчанию включено — `/authorize` и `/par` отклоняют запрос без `code_challenge`. Отключайте только для confidential-клиентов, чьи встроенные OIDC-библиотеки не отправляют PKCE (например, LiteLLM) — см. 03-web-app.md
`status`	✓	`active` или `suspended`. У приостановленного клиента `/authorize` и `/token` отвечают ошибкой — используйте для временного отключения интеграции без удаления клиента

client_id генерируется автоматически и не редактируется. client_secret — тоже автоматически, показывается один раз на странице клиента после создания (см. ниже).

Логаут-эндпоинты (опционально)

Заполняются, если ваше приложение должно узнавать о выходе пользователя со стороны SSO — подробный протокол в 03-web-app.md.

Поле	Описание
`backchannelLogoutUri`	URL, на который SSO пришлёт server-to-server уведомление о выходе
`frontchannelLogoutUri`	URL, который SSO подгрузит скрытым iframe на странице выхода
`postLogoutRedirectUris`	Список URI, куда можно вернуть пользователя после выхода (по одному на строку). Redirect за пределы этого списка игнорируется — защита от open redirect

Брендирование страницы входа

Применяется только к страницам OAuth-потока (/login, /consent) — не к личному кабинету (/account).

Поле	Описание
`logoUrl`	URL логотипа
`brandName`	Название, если должно отличаться от `name`
`primaryColor`	Hex-цвет кнопок и акцентов, например `#667eea`

Получение `client_id` и `client_secret`

После создания клиента откройте его страницу /admin/clients/:id — там указан client_id (тот же, что в списке /admin/clients) и client_secret в открытом виде. Секрет нигде больше не показывается в незашифрованном виде — сохраните его сразу в свой секрет-менеджер. Что делать, если секрет утёк или потерян, — 06-operations.md.

Issuer сервера и полный список эндпоинтов — в discovery-документе:

bash

curl http://localhost:3002/.well-known/openid-configuration

Сверьте authorization_endpoint, token_endpoint, jwks_uri и end_session_endpoint с тем, что собираетесь использовать в интеграции — это тот же issuer, что и в iss claim ваших токенов.

GET /jwks

Публичные ключи для проверки подписи JWT (access token, ID token, logout_token) — тот же URL, что указан в discovery-документе как jwks_uri. Не требует авторизации.

bash

curl http://localhost:3002/jwks

json

{
  "keys": [
    {
      "kty": "RSA",
      "n": "<base64url-модуль ключа>",
      "e": "AQAB",
      "kid": "<key ID>",
      "use": "sig",
      "alg": "RS256"
    }
  ]
}

Стандартный формат JWK (RFC 7517) — используйте готовую библиотеку проверки JWT для вашего языка (jsonwebtoken + jwks-rsa для Node.js, python-jose, jose и т.п.), а не самописный парсинг. Библиотека сама сматчит kid из заголовка токена с нужным ключом в этом ответе. Ротация ключа подписи (несколько активных ключей одновременно, старый ещё принимается) сейчас не поддерживается — в ответе всегда ровно один ключ; смена ключа подписи на стороне сервера сделает недействительными все токены, подписанные предыдущим.

Редактирование позже

GET  /admin/clients/:id
POST /admin/clients/:id

Та же форма, что при создании, — с уже заполненными значениями. client_id показан, но не редактируется. Организация клиента, если она была задана при создании, тоже зафиксирована и не меняется через эту форму.

org-admin не видит и не может открыть клиентов из чужой организации — /admin/clients/:id вернёт 403.

RBAC-клеймы в токене

Если приложению нужно знать роли и группы пользователя внутри SSO (например, чтобы отобразить разный интерфейс для разных ролей), запросите scope roles:

scope=openid profile roles

В access token, ID token и ответе /userinfo появятся:

json

{
	"roles": ["admin", "pam_approver"],
	"groups": ["engineering"]
}

Если клиент привязан к организации — токен дополнительно содержит org_id (см. 01-organization-and-access.md).

roles/groups относятся к самому SSO — это роли уровня Identity Provider, а не роли внутри вашего приложения. Используйте этот клейм как источник данных для собственной модели прав, а не как готовую замену ей.

Регистрация и настройка OAuth-клиента ​

Создание клиента ​

Поля формы ​

Логаут-эндпоинты (опционально) ​

Брендирование страницы входа ​

Получение client_id и client_secret ​

GET /jwks ​

Редактирование позже ​

RBAC-клеймы в токене ​