Scopes

Scope — строковое разрешение, которое клиент запрашивает во время авторизации. Scope определяет, какие возможности и данные нужны приложению.

Стандарт

Клиент должен запрашивать только необходимые scopes. Scope openid включает OIDC и получение ID Token. Остальные scopes зависят от возможностей провайдера.

Практика

Если приложение не использует email или длительную сессию, не запрашивайте email или offline_access без необходимости. Доступность claim зависит от scope и данных пользователя.

Чем Authoriza может быть полезна

Authoriza позволяет явно настроить scopes в SDK и согласовать их с задачей приложения. Проверьте scopes вместе с параметрами подключения в настройках OIDC.

Как выбрать scopes

Начните с минимального набора и добавляйте scope только под конкретный результат:

openid

достаточен для базового OIDC-входа. Если интерфейсу нужно имя пользователя, добавьте profile. Если нужно показать email, добавьте email. Если сессия должна переживать истечение Access Token без повторного ввода данных, добавьте offline_access и отдельно оцените риск хранения Refresh Token.

Scope не является ролью пользователя. profile не означает право менять профиль, а email не даёт доступ к API. Scope описывает запрошенный набор данных или возможность протокола; бизнес-права проверяются приложением.

Scopes в SDK

Если scope не задан, SDK использует:

openid profile email offline_access

Если приложение задаёт собственный массив, SDK добавляет обязательный openid, удаляет дубликаты и использует полученный набор. Это означает, что явная настройка scope должна быть осознанной: не исключайте openid, если ожидаете OIDC ID Token.

Пример:

const auth = createAuthoriza({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://example.com/auth/callback',
  scope: ['profile'],
});

В результате SDK запросит openid profile.

Consent и отсутствие данных

Пользователь может увидеть запрошенные разрешения на экране согласия. Запрошенный scope не гарантирует, что claim заполнен: у пользователя может не быть email или имени. Приложение должно обрабатывать отсутствие необязательного поля.

Типичные ошибки

• ожидать ID Token без openid;
• запрашивать все scopes «на будущее»;
• считать scope email подтверждением права пользователя;
• считать отсутствие email ошибкой протокола;
• запрашивать offline_access в браузере, не продумав хранение Refresh Token.

Как проверить результат

• в authorization request присутствует ожидаемый scope;
• openid добавляется для OIDC;
• claims появляются только там, где есть соответствующий scope и данные;
• API не использует scope как замену бизнес-авторизации;
• Refresh Token появляется только в сценарии с offline_access.

Scopes и consent

Scope — это часть контракта между клиентом и authorization server. Пользователь может увидеть запрошенные scopes и отказаться от продолжения. Поэтому набор scopes влияет не только на payload токена, но и на доверие пользователя к приложению.

Запрашивайте scope в момент, когда он нужен архитектуре, а не добавляйте его для устранения неизвестной ошибки. Если claim отсутствует, сначала проверьте scope, данные пользователя и фактический ответ провайдера.

Scopes и API audience

Scope не всегда описывает конкретный endpoint вашего API. Его наличие не заменяет проверку aud и не доказывает, что токен выпущен именно для принимающего сервиса. Если API требует собственную модель scopes, она должна быть подтверждена его контрактом и настройками provider.

Практический выбор

Для страницы профиля обычно достаточно openid profile. Для отображения контактного адреса нужен email. Для фонового продолжения сессии — offline_access, но только после оценки хранения Refresh Token. Если приложение не использует один из результатов, не запрашивайте соответствующий scope.

Как это реализовано в Authoriza SDK

Подтверждённые scopes Authoriza:

SDK всегда добавляет обязательный openid. При отсутствии явной настройки он использует openid profile email offline_access.

Чем Authoriza может быть полезна

Если вам нужен OIDC-клиент с явной настройкой scopes, SDK Authoriza позволяет задать их в конфигурации и сохранить обязательный openid. После выбора набора проверьте его в настройках подключения.