Claims

Claim — поле внутри токена, описывающее пользователя, провайдера или условия действия токена.

Стандарт

Часто используемые claims:

• sub — субъект токена;
• iss — issuer;
• aud — получатель токена;
• exp — срок действия;
• iat — время выпуска.

Claims нельзя считать достоверными до проверки подписи токена и его обязательных полей.

Практика

Храните sub как стабильный идентификатор локальной учётной записи. Не используйте email как первичный ключ: он может измениться или отсутствовать.

Claims из ID Token и Access Token

ID Token предназначен для OIDC-клиента, поэтому его claims описывают результат входа и субъекта. Access Token предназначен для API, поэтому кроме субъекта может содержать сведения о сроке, issuer и назначении доступа. Нельзя строить одну универсальную функцию, которая принимает любой JWT и доверяет ему одинаково.

sub в Authoriza

В SDK поле:

auth.user?.id

происходит из claim sub. В приложении его удобно использовать как внешний идентификатор локальной учётной записи. Email и имя являются необязательными:

const user = await auth.getUser();

if (user) {
  const localUser = await findOrCreateUser({
    externalId: user.id,
    email: user.email,
    name: user.name,
  });
}

Стабильность sub нужно рассматривать в контексте проекта и client configuration. Не объединяйте пользователей между независимыми проектами только по совпадению email.

Проверка claims

До чтения claims проверяют подпись JWT и контекст токена. После этого проверяют iss, aud, exp и nonce для ID Token, если flow использует nonce. Значения из неподписанного payload нельзя использовать для создания сессии.

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

• использовать email как первичный ключ;
• считать sub глобальным ID пользователя во всех проектах;
• доверять name или email без проверки подписи;
• принимать Access Token за доказательство всех бизнес-прав;
• считать наличие claim гарантированным при любом наборе scopes.

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

• локальная запись пользователя связана с sub;
• отсутствие email не ломает вход;
• ID Token проверяется до чтения claims;
• токен с неправильным issuer или audience отклоняется;
• права на ресурсы проверяются отдельной бизнес-логикой.

Claims как контракт, а не произвольный JSON

Нельзя объявить поле role или permissions доступным только потому, что оно есть в примере другого провайдера. Состав claims зависит от issuer, scopes и конкретной версии контракта. Документируйте только подтверждённые поля и обрабатывайте неизвестные поля без падения приложения.

Время и даты

exp и iat являются Unix time в секундах, тогда как JavaScript timestamp обычно выражается в миллисекундах. При ручной обработке не смешивайте единицы. Надёжнее передать проверку срока действия OIDC-библиотеке.

Claims и пользовательские изменения

Email или имя могут измениться. Если приложение показывает их в локальном профиле, продумайте синхронизацию, но не меняйте внешний идентификатор при каждом новом значении email. sub связывает сессии и локальную запись, а профильные claims являются атрибутами.

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

SDK строит пользователя из claims ID Token. Поле user.id берётся из sub, а email и name добавляются только при наличии соответствующих claims. В модели Authoriza sub идентифицирует профиль пользователя в контексте проекта, а не глобального пользователя.

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

Если вам нужен OIDC-клиент, который преобразует проверенные claims в объект пользователя, SDK Authoriza предоставляет такую модель. Свяжите sub с локальной записью после первого входа.