Регистрация первого клиента

Клиент — это приложение, которое запрашивает у этого сервера токены. Клиенты живут внутри проектов, проекты принадлежат группам, а проект указывает на бакет пользователей, из которого его клиенты впускают пользователей. Это четыре понятия, но они вложены друг в друга, поэтому консоль проводит по ним по порядку.

Группы, проекты, бакеты

• Группа чем-то владеет. У каждого проекта и каждого бакета пользователей есть группа-владелец, и именно членство в этой группе даёт к нему доступ. Отдельного списка назначенных управляющих нет. У каждого администратора уже есть группа Personal, и для первого клиента её обычно вполне достаточно; группа типа regular — это компания или команда, общая с коллегами.
• Проект — это набор клиентов, относящихся к одному приложению или одному продукту, плюс бакет, из которого приходят его пользователи.
• Бакет пользователей — это совокупность конечных пользователей: их учётные записи и политика того, как они регистрируются и подтверждают себя. Созданный вами бакет — это ещё и тенант со своим собственным издателем (issuer): он обслуживается по адресу <ISSUER>/<slug> или по собственному имени хоста и выпускает токены с этим issuer, поэтому клиент в проекте, привязанном к такому бакету, интегрируется с этим адресом, а не с корневым. Исключение — бакет по умолчанию redfox: он сохраняет корневой issuer, и именно это позволяет существующему развёртыванию остаться как есть.

1. Выберите группу. Диалоги создания проекта и бакета спрашивают, в какую группу его поместить, и начинают с группы, выбранной вверху консоли. Для первого клиента подойдёт ваша группа Personal, но в ней ровно один член, поэтому общую работу стоит вести в обычной группе: создайте её в разделе Groups или перенесите работу туда позже.

2. Создайте бакет в разделе Buckets, если не хотите использовать бакет по умолчанию redfox. Для него нужны имя и адрес: путь, который становится последней частью issuer в его токенах, или собственное имя хоста. Выбирайте адрес обдуманно: идентификатор issuer — это обещание, данное каждому клиенту, настроенному на него, поэтому смена адреса позже сначала показывает, что затронет, и требует подтверждения — она касается каждого приложения, которое пользуется бакетом. Новый бакет закрыт для регистрации, если не выбрать Anyone who can reach the sign-in page; изменить это можно позже на его вкладке Sign-in.

   В таблице Buckets адрес каждого бакета показан в столбце Address. У зарезервированных бакетов там вместо пути написано served at the root, поскольку они сохраняют корневой issuer.

3. Создайте проект в разделе Projects. Для него нужны имя, slug (строчные буквы, цифры и дефисы) и Bucket — один из бакетов его группы; выберите бакет из предыдущего шага. Оставить поле пустым — это и есть способ использовать бакет по умолчанию redfox, который показан как Default bucket: он не принадлежит ни одной группе, поэтому в списке его никогда нет. Изменить выбор можно позже кнопкой Change bucket… или на вкладке Settings проекта. Если через приложения проекта уже входили люди, консоль сначала покажет последствия и попросит подтвердить: этим людям придётся войти заново.

4. Создайте клиента в разделе Clients проекта. Выберите тип приложения и метод аутентификации на эндпоинте токенов, затем введите redirect URI. Этому выбору посвящён следующий раздел.

Клиенты проекта: сгенерированный client id, тип приложения и метод аутентификации на эндпоинте токенов, от которого зависит, есть ли у клиента секрет.

Публичный или конфиденциальный

Выбор сводится к методу аутентификации на эндпоинте токенов (token endpoint auth method), и он следует из того, может ли ваше приложение хранить секрет:

Метод	Для чего	Учётные данные
none (публичный / PKCE)	SPA в браузере, мобильные и десктопные приложения, CLI: всё, что поставляется пользователю	Нет. Доказательством служит PKCE.
client_secret_basic	Серверные веб-приложения и бэкенд-сервисы	Секрет, передаваемый в заголовке Authorization
client_secret_post	То же самое, когда клиентская библиотека может передать учётные данные только в теле формы	Секрет, передаваемый в поле формы

PKCE здесь не опционален ни для одного из видов. Любой запрос авторизации с response_type=code без code_challenge отклоняется, а единственный принимаемый метод — S256. Запрос с plain отклоняется, и discovery объявляет только S256. Поэтому публичный клиент без секрета — вовсе не более слабый клиент: полученный им код бесполезен для любого, кто не генерировал verifier.

Секрет показывается один раз

Когда создаётся конфиденциальный клиент или когда вы выполняете ротацию его секрета из таблицы клиентов, значение появляется в диалоге с текстом «Copy this secret now — it will not be shown again.» Восстановить его потом нельзя. Единственный путь назад — ротация, которая делает старый секрет недействительным.

Redirect URI сравниваются точно

Redirect URI должен быть зарегистрирован, а redirect_uri из запроса сравнивается с зарегистрированным набором как написано: схема, хост, порт, путь и query должны совпадать. https://app.example.com/cb и https://app.example.com/cb/ — два разных URI.

Есть ровно одно послабление — то, которого требует RFC 8252 §7.3: клиент с типом приложения native, перенаправляющий на http: на loopback-хосте, может использовать любой порт. Всё остальное по-прежнему должно совпадать точно. Послабление намеренно узкое:

• только для native-клиентов; redirect веб-клиента — это реальный хост под его контролем, так что ничего эфемерного в нём нет;
• только http: на loopback-хосте; redirect на закреплённый за приложением (claimed) https-адрес или на приватную схему по-прежнему сравнивается точно;
• localhost и 127.0.0.1 не считаются взаимозаменяемыми. Зарегистрируйте обе формы, если ваш клиент может использовать любую из них.

Открытой остаётся гонка за локальный порт: другой процесс на машине пользователя может занять порт и получить код. Её закрывает PKCE — именно поэтому он обязателен.

Каких пользователей впускает клиент

Маршрутизация входа определяется проектом, которому принадлежит клиент, и никогда — самим клиентом:

1. зарезервированный клиент консоли всегда направляется в бакет администраторов;
2. клиент, назначенный проекту, направляется в бакет этого проекта;
3. клиент, динамически зарегистрированный по адресу бакета (его /reg), принадлежит этому бакету;
4. всё остальное (клиент без проекта или зарегистрированный в корне) направляется в бакет по умолчанию redfox.

Таким образом, клиент без проекта впускает пользователей из бакета по умолчанию, а это редко то, что вам нужно. Задайте бакет проекта.

Бакет — это ещё и место, где живёт политика онбординга: открыта ли регистрация (registrationOpen), должна ли новая учётная запись подтвердить e-mail (emailVerificationRequired), происходит ли это по ссылке или по шестизначному коду (verificationMethod), предлагается ли вообще вход по паролю (passwordLogin) и обязательно ли приложение-аутентификатор (totpRequired). Ничего из этого не задаётся на клиенте. Два клиента в одном проекте разделяют всё это, потому что разделяют учётные записи.

Заметка

Согласие включено по умолчанию (consent.require для нового клиента по умолчанию равно true), поэтому первый запрос авторизации покажет экран согласия. Исключение — зарезервированный клиент консоли: это собственный (first-party) клиент, и он этот экран пропускает.

Далее: получите первый токен.