SDK для фронтенда

SDK Авторизы — JavaScript / TypeScript-библиотека для быстрой интеграции авторизации в веб-приложения.

SDK реализует OAuth 2.0 / OpenID Connect с Authorization Code Flow + PKCE и берет на себя работу с authorization flow, токенами и сессией.

SDK не зависит от React, Vue, Angular или другого фреймворка.

SDK не обязателен.

Авториза работает со стандартным OAuth 2.0 / OpenID Connect, поэтому вы можете использовать любую подходящую библиотеку вашего языка или фреймворка.

Если вы не хотите разбираться в деталях OIDC и хотите добавить авторизацию с минимальным количеством кода, рекомендуем SDK.

Если вы хотите интегрировать Авторизу напрямую через OIDC-библиотеку, смотрите Библиотеки OIDC.

Установка

Установите пакет @authoriza/sdk:

npm install @authoriza/sdk

SDK распространяется как ESM-пакет и не имеет runtime-зависимостей.

Быстрый старт

Создайте экземпляр SDK:

import { createAuthoriza } from '@authoriza/sdk';

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

Запустите вход:

await auth.login();

После успешной авторизации пользователь вернется в ваше приложение.

Чтобы указать страницу, на которую пользователь должен попасть после входа:

await auth.login({
  redirectAfterLoginTo: '/dashboard',
});

После авторизации можно получить access token:

const token = await auth.getAccessToken();

И использовать его для запросов к вашему API:

const response = await fetch('/api/profile', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Настройка

Для создания SDK используются параметры:

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

clientId

Идентификатор подключения вашего веб-приложения в Авторизе.

Получить его можно в настройках проекта в личном кабинете Авторизы.

redirectUri

URL, на который Авториза вернет браузер после авторизации.

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

redirectUri — это технический callback URL OIDC. Он не определяет страницу, на которую пользователь попадет после входа. Функция данной страницы - обработать Authorization Code и state, возвращенные Авторизой для получения токенов.

Например:

redirectUri: 'https://example.com/auth/callback'

issuer

URL OIDC-сервера Авторизы.

Для production используется значение по умолчанию:

https://oidc.authoriza.ru/oidc

Обычно указывать issuer вручную не требуется.

const auth = createAuthoriza({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://example.com/auth/callback',
  issuer: 'https://oidc.authoriza.ru/oidc',
});

scope

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

Чтобы приложение сразу получило полноценную сессию пользователя, по умолчанию SDK использует:

['openid', 'profile', 'email', 'offline_access']

Если приложение должно автоматически обновлять access token и поддерживать сессию без повторного входа пользователя, нужен offline_access.

openid добавляется SDK автоматически, даже если он не указан явно.

Запрашивайте только те scopes, которые действительно нужны приложению. Чем меньше данных запрашивает приложение, тем меньше информации о пользователе ему требуется.

При необходимости scopes можно изменить:

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

Вход

Для запуска авторизации используйте login():

await auth.login();

Метод перенаправит браузер на Авторизу.

Перенаправление после входа

Если после успешного входа нужно открыть определенную страницу приложения, передайте redirectAfterLoginTo:

await auth.login({
  redirectAfterLoginTo: '/dashboard',
});

Можно передавать query-параметры и hash:

await auth.login({
  redirectAfterLoginTo: '/dashboard?tab=profile#settings',
});

Используйте относительные адреса вашего приложения. Внешние URL не поддерживаются.

Не путайте redirectAfterLoginTo с redirectUri.

redirectUri — OIDC callback URL, который регистрируется в Авторизе.

redirectAfterLoginTo — страница вашего приложения, на которую пользователь попадет после завершения авторизации.

Если параметр не передан, SDK завершит авторизацию без дополнительного перенаправления на указанную страницу.

Проверка состояния авторизации

Текущее состояние можно получить через getAuthState():

const state = auth.getAuthState();

console.log(state);
// {
//   isAuthenticated: boolean,
//   isLoading: boolean,
//   user: User | null
// }

Также доступны свойства:

auth.isAuthenticated;
auth.isLoading;
auth.user;

Например:

if (auth.isAuthenticated) {
  console.log('Пользователь авторизован');
}

Восстановление сессии

При создании экземпляра SDK автоматически проверяет сохраненную сессию.

Поэтому после перезагрузки страницы не нужно повторно выполнять login().

Пока SDK восстанавливает состояние, isLoading имеет значение true:

if (auth.isLoading) {
  // показать состояние загрузки
}

if (auth.isAuthenticated) {
  // пользователь авторизован
}

Получение пользователя

Используйте getUser():

const user = await auth.getUser();

Если пользователь авторизован, метод возвращает его данные:

{
  id: string;
  email?: string;
  name?: string;
}

Если активной сессии нет, возвращается null.

Текущего пользователя также можно получить через:

auth.user;

Получение access token

Для запросов к API используйте:

const token = await auth.getAccessToken();

SDK автоматически проверяет срок действия access token.

Если access token истек, SDK попытается получить новый с помощью refresh token.

Это позволяет приложению не заниматься обновлением токенов самостоятельно.

Например:

const token = await auth.getAccessToken();

const response = await fetch('/api/data', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Если пользователь не авторизован, метод выбросит AuthorizaError с кодом USER_NOT_AUTHENTICATED.

Выход

Для завершения локальной сессии используйте:

await auth.logout();

Метод удаляет сохраненную сессию.

SDK не перенаправляет пользователя на страницу выхода Авторизы.

Отслеживание изменений авторизации

Чтобы реагировать на вход, выход или восстановление сессии, можно подписаться на изменения состояния:

const unsubscribe = auth.onAuthStateChanged((state) => {
  console.log(state.isAuthenticated);
  console.log(state.user);
});

Когда подписка больше не нужна, вызовите функцию отписки:

unsubscribe();

Также доступен альтернативный API:

const unsubscribe = auth.on('authStateChanged', (state) => {
  // ...
});

Обработка callback

Отдельно обрабатывать OIDC callback не требуется.

Создайте экземпляр SDK на странице, указанной в redirectUri:

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

SDK автоматически определит, что текущий URL является callback URL, и обработает authorization code.

Отдельный вызов handleCallback() не нужен.

SDK можно создавать на любой странице приложения. Если текущий URL является callback URL, обработка authorization code выполняется автоматически.

Обработка ошибок

Ошибки SDK представлены классом AuthorizaError.

При использовании методов, возвращающих Promise, ошибки можно обрабатывать через try / catch:

try {
  const token = await auth.getAccessToken();
} catch (error) {
  console.error(error);
}

Для проверки ошибки используйте isAuthorizaError():

import {
  createAuthoriza,
  isAuthorizaError,
} from '@authoriza/sdk';

try {
  const token = await auth.getAccessToken();
} catch (error) {
  if (isAuthorizaError(error)) {
    console.error(error.code);
  }
}

Для асинхронных ошибок, возникающих во время authentication flow, можно использовать onError:

const auth = createAuthoriza({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://example.com/auth/callback',

  onError(error) {
    console.error(error.code, error.message);
  },
});

Основные коды ошибок:

Пользовательское хранилище

По умолчанию SDK использует localStorage для хранения сессии.

При необходимости можно передать собственную реализацию хранилища:

import {
  createAuthoriza,
  type SessionStorage,
} from '@authoriza/sdk';

const storage: SessionStorage = {
  async get() {
    // вернуть Session | null
  },

  async set(session) {
    // сохранить сессию
  },

  async clear() {
    // удалить сессию
  },
};

const auth = createAuthoriza({
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://example.com/auth/callback',
  sessionStorage: storage,
});

Это позволяет использовать собственный механизм хранения сессии, если стандартный localStorage не подходит вашему приложению.

SSR и фреймворки

SDK не привязан к конкретному фреймворку и может использоваться с:

• React
• Vue
• Angular
• Svelte
• Next.js
• Nuxt
• другими JavaScript / TypeScript веб-приложениями

SDK поддерживает SSR-safe импорт и создание экземпляра: импорт библиотеки и вызов createAuthoriza() не требуют наличия browser globals.

При этом непосредственно авторизация выполняется в браузере.

Что SDK делает за вас

SDK берет на себя основные технические детали OAuth 2.0 / OpenID Connect:

• Authorization Code Flow с PKCE;
• обработку authorization callback;
• проверку состояния authentication flow;
• хранение сессии;
• восстановление сессии после перезагрузки;
• обновление access token;
• защиту от параллельных refresh-запросов;
• синхронизацию состояния между вкладками;
• работу с OIDC Discovery;
• проверку ID Token.

Это позволяет приложению работать с простой моделью:

login()
    ↓
пользователь авторизуется
    ↓
auth.isAuthenticated
    ↓
auth.user
    ↓
auth.getAccessToken()

Вам не нужно самостоятельно реализовывать эти части OIDC-протокола.

Пример готового приложения

Полный пример React SPA с использованием SDK:

authoriza-spa-sdk-demo

Если вы хотите посмотреть, как выглядит такая же интеграция без SDK, используйте отдельный пример:

authoriza-demo-react-spa

Он показывает прямую интеграцию с Авторизой через OIDC без использования SDK.

API и исходный код

Исходный код SDK и полный список API доступны на GitHub:

github.com/authoriza-core/sdk

SDK распространяется под лицензией MIT.