Auth API

Статус документа

Оглавление

Цель и смысл

Данный документ описывает реализацию аутентификации пользователей и авторизации приложений. Auth API реализует протокол авторизации в соответствии с OAuth 2.0 Framework.

Варианты использования, приводящие к данному API, описаны на странице вариантов использования истории просмотра.

Термины и определения

В этом документе используются термины и определения, описанные в документах «О программных интерфейсах сервисов Инетры» и «Термины и определения».

Предметная область

Пользователь

Пользователи разделены на две группы:

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

Токен доступа

Токены доступа могут быть двух видов:

• анонимный (принадлежащий анонимному пользователю);
• персональный (принадлежащий не анонимному пользователю).

После получения токен доступа действует ограниченное время, указанное в ответе. На стороне клиента необходимо реализовывать обработку ошибки просроченного токена и получать новый токен доступа. Токен доступа также характеризуется типом, указывающим на схему авторизации, которую должен использовать клиент.

PIN-код

Отдельно реализован запрос цифрового PIN–кода переменной длины, от 6 до 15 знаков (рекомендуемая длина 9[1] знаков), который живет короткое время (рекомендуемое время жизни 15 минут). Аутентифицированный пользователь (в том числе, анонимный) с помощью такого временного токена доступа имеет возможность аутентификации на другом устройстве без необходимости ввода дополнительной информации.

Регистрация приложения

Каждое авторизующееся приложение должно иметь свой идентификатор и секретный ключ, которые в дальнейшем используются в методах данного API в параметрах client_id и client_secret, соответственно. Для получения значений необходимо зарегистрировать приложение.

На данный момент получение данных значений возможно с помощью службы технической поддержки компании Инетра (support@inetra.ru) с предоставлением дополнительных данных:

• аккаунт разработчика приложения на сайте CN.ru или Peers.TV
• название приложения
• логотип приложения

Аутентификация при помощи токена доступа

Клиент должен выполнять аутентификацию в соответствии с типом выданного токена доступа. Для аутентификации по типу токена «Bearer» предусмотрено 2 способа:

• HTTP заголовок Authorization (рекомендуемый способ);
• GET параметр запроса access_token

Пример задания HTTP заголовка Authorization для схемы авторизации «Bearer»:

Authorization: Bearer 18dasd81230dah12032

Способы авторизации

Auth API предусматривает различные способы авторизации приложения:

• для анонимной учетной записи;
• для персональной учетной записи по коду авторизации;
• по коду устройства.

Авторизация для анонимной учетной записи не предусматривает выполнения каких-либо действий со стороны пользователя. Для получения токена доступа клиент может воспользоваться методом token.

Авторизация для персональной учетной записи требует от пользователя выполнения дополнительных действий. Пользователь должен ввести логин/пароль и авторизовать приложение в веб–форме, открытой клиентом (см. метод authorize).

Авторизация по PIN–коду и коду устройства требует наличие двух устройств: авторизованное и авторизующееся — описание механизма приведено в разделе «Авторизация по PIN–коду и коду устройства».

Авторизация по PIN–коду и коду устройства

Приложение может осуществить авторизацию при помощи другого авторизованного приложения. Для этого авторизующееся приложение должно получить код устройства и PIN–код (см. метод device_code). Авторизующееся приложение должно отобразить полученный PIN–код в графическом интерфейсе и предложить пользователю ввести PIN–код в другом авторизованном приложении.

После ввода PIN–кода пользователем авторизованное приложение должно подтвердить авторизацию (см. метод authorize), в это время авторизующееся приложение должно периодически проверять завершение процесса авторизации (см. метод token).

Слияние учетных записей

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

Перед вызовом алгоритма слияния необходимо понять, в чью пользу принимать решения при конфликтах.

function merge_users(dst, src, resolve_hint) {
  if (resolve_hint === 'auto') {
    if (is_anonymous(src)) {
      if (is_anonymous(dst)) {
        resolve_hint = 'mine';
      } else {
        resolve_hint = 'their';
      }
    } else { // src not anonymous
      if (is_anonymous(dst)) {
        resolve_hint = 'mine';
      } else {
        return false;
      }
    }
  }
  merge_elements(dst.root, src.root, resolve_hint === 'mine');
  return true;
}

Механизм слияния пользовательских данных описан в разделе «Слияние элементов» в User Data API

Взаимодействие с API

Сервис API должен присутствовать в Регистратуре в списке сервисов. Рекомендуется выполнять запросы к API по защищенному соединению (протокол HTTPS).

Параметры методов API передаются в параметрах запроса для GET метода или в теле сообщения для POST метода. Обращение к методам API строится по схеме (на примере GET метода):

https://api.peers.tv/auth/2/<method>?[<parameters>]

Где:

• <method> — имя метода (например, token)
• <parameters> — параметры метода

Формат ответов всегда JSON.

Значения всех параметров перед передачей серверу необходимо кодировать для предотвращения неоднозначной интерпретации так, как это рекомендуется в RFC3986.

Стандартные коды ответов

Для каждого метода API предусмотрены стандартные коды ответов (RFC2616). Ниже описана интерпретация некоторых кодов:

• 200 — запрос успешно обработан
• 400 — некорректно составлен запрос:
  • отсутствуют обязательные параметры запроса;
  • некорректные значения параметров запроса.
• 401 — требуется аутентификация:
  • необходимо передать данные аутентификации;
  • данные аутентификации некорректны;
  • данные аутентификации корректны, но переданный токен доступа был отозван или истек срок его действия.
• 403 — доступ запрещен:
  • переданы данные аутентификации, которые не позволяют выполнить запрос в силу отсутствия необходимых разрешений;
  • аутентификация невозможна, например, закрыт доступ по IP адресу.

Для HTTP кодов ответа 401, 403 должен быть передан HTTP заголовок WWW-Authenticate с указанием ожидаемой схемы аутентификации и дополнительнной информации (если применимо). Например, для схемы «Bearer» может быть указан дополнительный атрибут error со значением:

• invalid_token — передан некорректный, просроченный или отозванный токен доступа (код 401);
• insufficient_scope — запрос требует более высоких привилегий, чем те, которыми обладает токен доступа (код 403).

Методы

authorize — получение авторизации от пользователя

Клиент должен открыть сформированный запрос в веб–браузере, указав необходимые параметры:

Возможные значения параметра response_type:

• code — авторизация по коду. Полученный код авторизации клиент должен использовать для получения токена доступа (см. метод token);
• pin_code — авторизация по PIN–коду устройства (см. сценарий использования)

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

Замечание:

• при авторизации по PIN-коду клиент может передать сессию авторизации по персональной учетной записи, используя схему авторизации Bearer (как часть query или через заголовок), чтобы пропустить шаг регистрации/авторизации.

Возвращаемые значения

После завершения операции клиент будет перенаправлен на адрес перенаправления (параметр запроса redirect_uri, либо указанный при регистрации приложения), в который сервер добавит дополнительные параметры, соотвествующие типу возвращаемого ответа (параметр запроса response_type).

Возвращаемые значения:

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

При возникновении ошибки в адресе перенаправления будет указан код ошибки (параметр error).

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

Параметры метода должны передаваться методом POST в формате application/x-www-form-urlencoded.

Основные параметры для аутентификации:

Формат ответа: TokenReply

Возможные значения для параметра grant_type:

• authorization_code — аутентификация по коду авторизации;
• refresh_token — возобновление токена доступа;
• inetra:anonymous — анонимная аутентификация, дополнительные параметры не требуются;
• inetra:device_code — аутентификация по коду устройства при помощи другого авторизованного приложения (после получения авторизации по PIN-коду).

При успешном выполнении операции будет передан токен доступа с указанием схемы аутентификации. Срок действия токена ограничен. При восстановлении токена доступа будет выдан новый токен доступа, токен для возобновления доступа может быть обновлен.

Для отображения информации об аккаунте клиент может воспользоваться методом account.

Замечания по mac: Параметр является необязательным и передаётся в нижнем регистре. Если активно несколько интерфейсов, тогда следует передавать все доступные значения в одном параметре, а в качестве разделителя между разными мак адресами использовать символ запятой. Параметр передаётся как при регистрации анонимного пользователя, так и при любом другом запросе к auth. В качестве разделителя в мак адресе используется символ двоеточия.

ВАЖНО: для обеспечения возможности плавной миграции с первой версии будут действовать следующие правила:

• если клиент не выполнял ранее процедуру возобновления токена доступа (владеет бессрочным токеном, не владеет токеном возобновления), то допускается передать бессрочный токен доступа в качестве токена возобновления доступа в параметре refresh_token при возобновлении токена доступа. При этом бессрочный токен доступа конвертируется в токен возобновления, и не может быть использован в качестве токена доступа. Токены доступа со сроком действия не могут быть использованы в качестве токенов возобновления (код ответа — 401).

Возможные ошибки

Замечания:

• Возникновение ошибки unsupported_grant_type при авторизации может означать, что авторизация по данному типу запрещена для клиента и клиент должен воспользоваться другим типов авторизации, например, по логину/паролю. Такая ситуация может возникать у операторов связи, когда пользователь может быть аутентифицирован только по логину/паролю.
• Возникновение ошибки invalid_grant при возобновлении токена доступа может означать, что токен доступа был отозван и клиент должен повторно выполнить авторизацию, а в случае персонального токена доступа — повторно запросить у пользователя логин/пароль. Такая ситуация может возникать при смене пароля пользователем или отзыве авторизации у приложения.
• Возникновение ошибки invalid_grant при выполнении слияния с анонимной учетной записью может означать, что был передан токен доступа, который относится к персональной учетной записи, что является ошибкой кодирования.

Пример успешного взаимодействия

Запрос

POST /auth/2/token HTTP/1.1
Host: api.peers.tv
Content-Type: application/x-www-form-urlencoded

grant_type=inetra%3Aanonymous&client_id=91801674-777e-4edd-aacc-1911c7262115&client_secret=3WzahKEFZqhm3GpowLAsS4

Ответ

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"bearer",
  "refresh_token":"18da91mb0FOA7eZ3n4Ad8A",
  "expires_in":3600  
}

device_code — получение кода устройства для авторизации через другое приложение

Параметры метода должны передаваться методом POST в формате application/x-www-form-urlencoded.

Дополнительные параметры запроса:

Формат ответа: DeviceCode

При возникновении ошибок сервер возвратит соотвествующий HTTP код ответа (cм. Стандартные коды ошибок).

Пример успешного взаимодействия

Запрос

POST /auth/2/device_code HTTP/1.1
Host: api.peers.tv

client_id=91801674-777e-4edd-aacc-1911c7262115

Ответ

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "pin":"8Df-2a1",
  "device_code":"j8a-1daj27fal1sueq39178s",
  "expires_in":1800,
  "interval":10
}

account — информация об учетной записи

Формат ответа: AccountInfo

Замечание: метод требует аутентификации пользователя

Пример успешного взаимодействия

Запрос

GET /auth/2/account HTTP/1.1
Host: api.peers.tv
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Ответ

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "username":"v_ivanov@peers.tv",
  "account_id":"398E944A-5475-4FAB-95BA-FCB9A86DD3FA"
}

Запрос

GET /auth/2/account?access_token=5f1080e637a545eeb68e99fbdfffdce4 HTTP/1.1
Host: api.peers.tv

Ответ

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "account_id": 379907910,
  "cid": 104
}

Спецификация API для Protocol Buffers

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

message TokenReply {
  optional string access_token = 1;
  optional string token_type = 2;
  optional int32 expires_in = 3;
  optional string refresh_token = 4;

  optional string error = 5;
  optional string error_description = 6;
}

Замечания:

• access_token — токен доступа
• token_type — тип токена, который задает схему аутентификации, возможные типы:
  • bearer — тип токена «Bearer».
• refresh_token — токен возобновления доступа, необходимый для получения нового токена доступа. Срок жизни не ограничен, но может быть обновлен при получении нового токена доступа;
• expires_in — время жизни полученного токена доступа, в секундах относительно времени запроса
• error — строковая константа, описывающая случившуюся ошибку (см. «Возможные ошибки»)
• error_description — строка с сообщением, которое можно показать пользователю (если есть)

В случае успешной аутентификации должны быть возвращены атрибуты access_token, refresh_token, token_type и expires_in. В случае ошибки — в теле ответа содержится атрибут error и error_description.

DeviceCode — получение кода устройства

message DeviceCode {
  optional string pin = 1;
  optional string device_code = 2;
  optional int32 expires_in = 3;
  optional int32 interval = 4;
}

Замечания:

• pin — PIN код, отображаемый в графическом интерфейсе, для ввода пользователем в другом приложении;
• device_code — код устройства для получения токена доступа после завершения авторизации в другом авторизованном приложении;
• expires_in — срок жизни выданных кодов (в секундах);
• interval — интервал для проверки авторизации по коду устройства.

AccountInfo — информация об учетной записи

message AccountInfo {
  optional string username = 1;
  optional uint64 account_id = 2;
  optional uint64 сid = 3;
}

Замечания:

• username — уникальный идентификатор учетной записи, введенный пользователем, например, e-mail;
• account_id — уникальный числовой идентификатор учетной записи (в пространстве идентификаторов оператора).

Изменения по версиям

Изменения в версии 1.1.0

• Начальная редакция документа.

Изменения в версии 1.1.1

• Исправлена ошибка в пояснении к кодам ошибок авторизации.

Изменения в версии 1.2.0

• Описан выдаваемый тип токена «Bearer».

Изменения в версии 1.3.0 (TVREC–245, TVREC–246)

• Удален параметр uid для аутентификации анонимного пользователя;
• В сообщение TokenReply добавлен атрибут renew_token;
• Описан набор параметров метода UserCredentials для возобновления доступа.

Изменения в версии 1.3.1

• Описано особое поведение на период перехода на схему с возобновлением токена доступа.

Изменения в версии 1.3.2

• Добавлены уточнения касательно случаев, когда выдается бессрочный токен доступа.

Изменения в версии 1.4.0

• Описан параметр purpose для метода PinCode;
• Реогранизована структура документа;
• Обобщены и описаны стандартные коды ошибок.

Изменения в версии 1.4.1

• Добавлены уточнения об условиях возобновления токена доступа.

Изменения в версии 1.4.2

• Унифицирована структура документа по аналогии с другими документами.

Изменения в версии 1.5.0

• Отменены изменения из версии 1.3.0–1.3.2:
  • возвращен параметр uid для анонимной аутентификации;
  • удалено описание метода возобновлении токена доступа и описание соответствующих атрибутов.

Изменения в версии 2.0.0 (TVREC–727, TVREC–720)

• Описана схема авторизации через авторизованное приложение;
  • описан метод device_code для получения кода устройства и PIN–кода для получения авторизации;
• Внесены уточнения по интерпретации ошибок в раздел «Возможные ошибки»;
• Методы [UserCredentials][m-user-credentials], [PinCode][m-pin-code] исключены;
• Описан метод token для получения токена доступа;
• Описан метод authorize для получения авторизации у пользователя;
  • описан способ получения кода авторизации;
  • описан способ получения авторизации на основе владения анонимной учетной записью;
  • описан способ подтверждения авторизации для введенного PIN-кода.
• Описан алгоритм слияния данных двух учетных записей;
• Описан метод account для получения информации об учетной записи пользователя;
• Добавлен раздел Термины и определения.

Изменения в версии 2.0.1

• Уточнен параметр device_code, используемый в методе token для авторизации по коду устройства.

Изменения в версии 2.0.2

• Исправлен пример для метода token для анонимной аутентификации.

Изменения в версии 2.0.3

• Описан опциональный параметр signature в методе token для передачи информации о цифровой подписи приложения

Изменения в версии 2.1.0

• Изменен тип атрибута account_id из сообщения AccountInfo

Изменения в версии 2.1.1 (WEBDEV–11274)

• Внесены уточнения о миграции с первой версии протокола на вторую: удалены регламенты по сроками миграции, внесены уточнения о процедуре миграции.

Изменения в версии 2.2.0 (WEBDEV–11388)

• В методе authorize описана возможность передачи сессии авторизации по персональной учетной записи при авторизации по PIN коду.

Изменения в версии 2.2.1

• Добавлен атрибут cid в сообщение AccountInfo