ym88659208ym87991671
Авторизация запросов | Документация для разработчиков

Авторизация запросов

Обновлено 15 февраля 2024

При работе со SberJazz API вам понадобятся токены двух видов: транспортный токен и токен доступа.

Создание транспортного токена

Транспортный токен — это JSON Web Token (JWT), зашифрованный по алгоритму AES256 и подписанный с помощью ключа SDK по алгоритму ECDSA. Транспортный токен генерирует приложение в соответствии с собственной логикой.

Полезная нагрузка транспортного токена включает обязательные поля:

iat
required
integer

Время создания токена доступа.

exp
required
integer

Время исчтечения срока действия токена доступа.

jti
required
string <uuid4>

Произвольный уникальный идентификатор токена доступа в формате uuid4. Используется для отслеживания токена в логах.

sub
required
string <uuid4>

Идентификатор пользователя в бэкенде приложения.

sdkProjectId
required
string <uuid4>

Идентификатор проекта SberJazz SDK в Studio. Вы можете найти идентификатор следующими способами:

  • В адресной строке браузера, после переходта к проекту SberJazz SDK: https://developers.sber.ru/studio/workspaces/<идентификатор_пространтсва>/jazz/projects/<идентификатор_проекта>;
  • В поле projectId, если декодируете ключ SDK. Ключ закодирован в Base64.
{
  • "iat": 1516239022,
  • "exp": 1816239022,
  • "jti": "d3dea006-e200-442f-8f94-977d7bb27b3e",
  • "sub": "2b6574af-323e-4842-a8a5-943e99fb97de",
  • "sdkProjectId": "e26afe22-117a-4f59-9176-b5d6a04a7e2d"
}

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

С помощью одного транспортного токена вы можете выпустить неограниченного количество токенов доступа с различными параметрами (сроком действия, идентификатором, данными пользователя и другими).

Для создания транспортного токена:

  1. Выпустите ключ SberJazz SDK.
  2. Добавьте логику, с помощью которой приложение будет генерировать транспортный токен в соответствии с форматом JWT.
  3. Зашифруйте данные по алгоритму AES256 и подпишите их с помощью ключа SberJazz SDK по алгоритму ECDSA.

Пример создания транспортного токена в SberJazz SDK для Web

Вы можете создать транспортный токен с помощью утилиты SberJazz SDK для Web.

Для создания транспортного токена:

  1. Выпустите ключ SberJazz SDK.

  2. Декодируйте ключ из base64 в object.

    export function parseSecret(key: Base64String): SecretResult {
    let result: SecretResult;
    try {
    result = JSON.parse(decoder.decode(decodeSafeUrl(key)));
    } catch (error) {
    throw createError('ER_INVALID_KEY', 'Invalid Key');
    }

    if (!isMatching(SECRET_RESULT_PATTERN, result)) {
    throw createError('ER_INVALID_KEY', 'Invalid Key');
    }

    return result;
    }
  3. Получите детали алгоритма создания приватного ключа.

    const algorithm = recognizeAlgorithm(secret);
  4. Сформируйте полезную нагрузку JWT.

    const payload: JWTPayload = {
    iat,
    exp: iat + expireIn,
    jti: requestId,
    sdkProjectId: algorithm.projectId,
    iss, // Для логов. Не больше 100 символов.
    sub, // Идентификатор пользователя в бэкенде приложения
    userName: userName, // Необязательно. Используется для отображения в комнате
    userEmail: userEmail, // Необязательно
    };
  5. Сформируйте заголовок JWT.

    const header: JWTHeader = {
    alg: algorithm.alg,
    kid: algorithm.kid,
    typ: 'JWT',
    };
  6. Сформируйте первую часть JWT из заголовка и полезной нагрузки.

    const textToSign = headerBase64 + '.' + payloadBase64;
  7. Выпустите приватный ключ с помощью алгоритма криптографии ECDSA.

    const privateKey = await importECDSAPrivateKey(algorithm.jwk);
  8. Подпишите первую часть JWT с помощью приватного ключа.

    const { signature } = await algorithm.sign(textToSign, privateKey);
  9. Сформируйте итоговый транспортный токен.

    const signedJwt = createSignedJWT(textToSign, signature);

Используйте транспортный токен для получения токена доступа.

Получение токена доступа

Токен доступа нужен для авторизации запросов к SberJazz API.

Для получения токена доступа передайте POST-запрос по адресу /v1/auth/login и авторизуйте его с помощью транспортного токена:

curl -L -X POST 'https://api.jazz.sber.ru/v1/auth/login' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <транспортный_токен>'

В ответ вы получите строку с токеном доступа:

token
string

Токен доступа для авторизации запросов к SberJazz API

{
  • "token": "string"
}
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.