Пример авторизации в API

Для авторизации используется аналогичный JWT формат.

Авторизационный токен состоит из трех частей:

  1. Header -
    Json
    . Содерджит информацию о том, как должна вычисляться JWT подпись.
  2. Payload -
    Json
    . Содержит полезную информацию о токене.
  3. Signature -
    HS256 подпись

Пример авторизации на Python

https://github.com/TinkoffCreditSystems/tinkoff-speech-api-examples/blob/master/python/auth.py

Алгоритм создания авторизационного токена:

  1. Получаем API_KEY и SECRET_KEY оставив заявку на (https://voicekit.tinkoff.ru)
  2. Создаем объект Header. В поле kid указываем API_KEY.Остальные поля заполняем, как в примере ниже.
    1
    2
    3
    4
    5
    {
    "alg": "HS256"
    "typ": "JWT"
    "kid": "API_KEY"
    }
  3. Создаем объект Payload.

    • iss - Строка, идентифицирующая систему, выпустившую токен
    • sub - Строка идентифицирующая конечного пользователя
    • aud - Сервис или набор сервисов, для которых предназначается токен
    • exp - Время, после которого токен будет недействительным (Unix time)
    • iat - Время, когда токен был выпущен (Unix time)
    • nbf - Время начала действия токена (Unix time)
    • jit - Уникальный идентификатор токена
    • sid - ID сессии пользователя, для которого был выпущен токен
    • x-content-sha256 - SHA256 хеш запроса (либо первого сообщения запроса, в случае стриминга), в формате base16

     

    Пример объекта payload:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
       {
         "iss": "tinkoff_mobile_bank_api",
         "sub": "user12345",
         "aud": "tinkoff.cloud.stt",
         "exp": 1609459199,
         "iat": 1542362238,
         "nbf": 1542362238,
         "jti": "123e4567-e89b-12d3-a456-426655440000",
         "sid": "123e4567-e89b-12d3-a456-426655440000",
         "x-content-sha256": "fd648811be25e25107eda859fe96083daa800af7e855096381ccfb1fde14352a"
       }
  4. Пример вычисления signature

    1
    2
    3
     var SECRET_KEY = 'Y1v7D9ic34GedKJV9Sb/i9O23U/Aq644TWeCA4nuYBs='
     var unsignedToken = base64urlEncode(header) + '.' + base64urlEncode(payload)
     var signature = HMAC-SHA256(unsignedToken, SECRET_KEY)
  5. Получаем Token совмещая все компоненты:

    1
    var token = encodeBase64Url(header) + '.' + encodeBase64Url(payload) + '.' + encodeBase64Url(signature)
  6. Валидируем полученный токен на (http://jwt.io)
  7. Валидный токен передаем при кадждом запросе в поле Authorization
    1
    2
    3
    4
     GET /v1/stt:recognize HTTP/1.1  
     Host: stt.tinkoff.ru  
     Content-Type: application/json  
     Authorization: Bearer <TOKEN>  
  8. PROFIT!

Хранение API_KEY и SECRET_KEY

Для предотвращения утечки токена рекоммендуется хранить API_KEY и SECREY_KEY в отдельном сервисе.
Клиенты должны обращаться к этому сервису для получения и обновления токена.
 

SECRET_KEY должен быть известен только одному сервису.

Пример:

  1. Есть мобильное приложение(клиент) и BackEnd(сервер)
  2. Сервер отвечает за хранение API_KEY, SECRET_KEY и генерацию токена
  3. Клиент получает от Сервера Токен и при необходимости обновляет его отправляя соответствующий запрос на сервер.
  4. Клиент использует Токен для авторизации в сервисах VoiceKit и не обладает знаниями о SECRET_KEY

Дополнительная информация

Для дополнительной информации о JWT, рекомендуем использовать: (https://jwt.io/introduction/)