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

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

Обновлено 9 июля 2024

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

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

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

Подробнее о ключе SDK

Ключ SDK — закодированный в Base64 объект JSON, который состоит из идентификатора проекта и JWK.

Пример структуры ключа:

{
    "projectId": "f98d99c6-072e-4687-867b-a74dc6a22ef8",
    "key": {
        "kty": "EC",
        "d": "mQGSp33ATOo4wPLzzqFm1qKm8OJ5sHD-n3i7r1_NMWQ8UpgC42cscfi5fM4TbKxt",
        "use": "enc",
        "crv": "P-384",
        "kid": "dde4b3b1-2441-4630-b186-9d0faef24891",
        "x": "ykJ5V-8YgmaYHzV165B73EhPatGoxYJ0zP4bmof3hH6qHg1p-UY4q1FZqJHbbF_x",
        "y": "06HfHcopKbJNNEFcKYUiQgXJN239f-0zOgzd0Okx-aL9kxMR2DvFJqfn9fz-3OH-"
    }
}

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

iat
required
integer

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

exp
required
integer

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

jti
required
string <uuid4> (([0-9a-fA-F-])36)

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

sub
required
string <uuid4> (([0-9a-fA-F-])36)

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

sdkProjectId
required
string <uuid4> (([0-9a-fA-F-])36)

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

  • В адресной строке браузера, после переходта к проекту SaluteJazz 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. Выпустите ключ SaluteJazz SDK.
  2. Добавьте логику, с помощью которой приложение будет генерировать транспортный токен в соответствии с форматом JWT.
  3. Зашифруйте данные по алгоритму AES256 и подпишите их с помощью ключа SaluteJazz SDK по алгоритму ECDSA.

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

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

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

  1. Выпустите ключ SaluteJazz 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);

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

Примеры кода для создания токена на разных языках

import base64
import datetime
import json
import uuid

import jwt
from jwt import PyJWK

# Разбор ключа SDK
# Ключ содержит идентификатор проекта и JWK, который используется для подписи JWT
sdk_key_encoded = '{значение ключа SDK}'
sdk_key = json.loads(base64.b64decode(sdk_key_encoded))

# В заголовке JWT нужно указать идентификатор ключа и алгоритм подписи  
# Алгоритм можно определить по полю kty и другим параметрам ключа sdk_key['key']  
# Например, для kty=EC и crv=P-384 следует указывать алгоритм ES384  
# Описание алгоритмов и их кодов можно изучить по ссылке https://datatracker.ietf.org/doc/html/rfc7518#section-3.1
jwt_header = {
    'typ': 'JWT',
    "alg": 'ES384',
    'kid': sdk_key['key']['kid'],
}

# Тело JWT
iat = datetime.datetime.utcnow()
exp = iat + datetime.timedelta(hours=1)
jti = str(uuid.uuid4())
jwt_payload = {
    "iat": iat,
    "exp": exp,
    "jti": jti,
    "sdkProjectId": sdk_key['projectId'],
    "sub": 'user_backend_id',
    #'userName': 'User Name',
    #'userEmail': 'user@email',
}

# Подпись JWT
jwk = PyJWK.from_dict(sdk_key['key'], algorithm='ES384')
jws = jwt.encode(headers=jwt_header, payload=jwt_payload, key=jwk.key, algorithm='ES384')
print(jws)  # Вывод строки с транспортным токеном

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

С помощью формы вы можете создать тестовый транспортный токен. Токен действует в течение 30 минут. Для создания тестового токена потребуется ключ SaluteJazz SDK.

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

Генерация токена SaluteJazz API
для тестирования запросов
В целях безопасности не используйте тестовый токен для эксплуатационной среды
Укажите ключ SaluteJazz SDK из Studio

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

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

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

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

Адрес API изменился на https://api.salutejazz.ru/v1.

Подробнее об изменении домена.

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

token
string

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

{
  • "token": "string"
}

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

Используйте токен доступа для авторизации запросов к SaluteJazz API, например, для создания комнаты (запрос POST /room/create):

curl -L -X POST 'https://api.salutejazz.ru/v1/room/create' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <токен_доступа>' \
--data-raw '{
  "roomTitle": "Мастер-класс"
}'

Адрес API изменился на https://api.salutejazz.ru/v1.

Подробнее об изменении домена.

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