Эта страница переведена с помощью Cloud Translation API.

OAuth для API агента тарифного плана данных

Связанные документы

OAuth 2.0 стандартизирован в RFC 6749. Подробный документ доступен по адресу https://oauth.net/2. Базовая HTTP-аутентификация определена в разделе 2 RFC 2617 .

Обзор

Обычно для предоставления сторонним приложениям доступа к закрытым ресурсам, таким как данные тарифного плана и кошелька, конечному пользователю (владельцу ресурса) необходимо предоставить свои учётные данные третьей стороне. Это создаёт ряд проблем и ограничений, таких как хранение учётных данных, аутентификация по паролю, широкий доступ к ресурсам конечного пользователя, утечка паролей и т. д. Протокол OAuth2.0 решает эти проблемы, внедряя уровень авторизации и тем самым защищая и ограничивая доступ к защищённым ресурсам конечного пользователя.

Вместо использования учётных данных конечного пользователя для доступа к защищённым ресурсам, таким как информация о тарифном плане, GTAF получает токен доступа. Токены доступа выдаются GTAF от имени учётных данных GTAF. Затем GTAF использует этот токен доступа для доступа к информации о тарифном плане, хранящейся в DPA.

На следующем рисунке представлен высокоуровневый поток информации:

Рисунок 1. Абстрактный поток OAuth.

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

Токены доступа — это учётные данные, используемые GTAF для доступа к информации о тарифном плане через DPA оператора. Токен доступа — это строка, представляющая собой разрешение, выданное GTAF. Эта строка обычно непрозрачна для GTAF. Токены представляют собой определённые области и продолжительность доступа, предоставляемые конечным пользователем оператору и контролируемые DPA и сервером OAuth оператора.

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

Токены доступа могут иметь различные форматы, структуры и методы использования (например, криптографические свойства) в зависимости от требований безопасности оператора. GTAF поддерживает только токены доступа типа Bearer, определённые в [ RFC6750 ].

Аутентификация клиента

GTAF работает как «конфиденциальный клиент» и обеспечивает безопасность паролей. В настоящее время GTAF поддерживает только базовую HTTP-аутентификацию для аутентификации в DPA. Идентификатор клиента кодируется с помощью алгоритма «application/x-www-form-urlencoded», а закодированное значение используется в качестве имени пользователя; пароль кодируется с помощью того же алгоритма и используется в качестве пароля.

Конфиденциальные клиенты, такие как GTAF, которым выдаются клиентские учетные данные, проходят аутентификацию на сервере OAuth оператора при отправке запросов к конечной точке токена. Аутентификация клиента используется для:

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

GTAF использует параметр запроса «client_id» для своей идентификации при отправке запросов на конечную точку токена.

Особое значение имеет возможность ротации клиентских учётных данных. OAuth-сервер должен поддерживать одновременно две пары учётных данных во время ротации и иметь возможность отключать некоторые учётные данные. Типичная ротация учётных данных:

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

Сервер OAuth должен поддерживать описанный выше процесс ротации.

Конечная точка токена

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

Ниже приведены некоторые моменты, которые следует учитывать при настройке конечной точки токена:

Местоположение конечной точки токена должно быть указано в документации по сервису.
URI конечной точки может включать компонент запроса в формате «application/x-www-form-urlencoded», который необходимо сохранить при добавлении дополнительных параметров запроса. URI конечной точки не должен включать компонент фрагмента.
Поскольку запросы к конечной точке токена приводят к передаче учетных данных в виде открытого текста (в HTTP-запросе и ответе), сервер OAuth оператора связи должен использовать TLS для отправки запросов к конечной точке токена.
GTAF использует HTTP-метод «POST» при запросе токена доступа.
Параметры, отправленные без значения, должны рассматриваться как пропущенные в запросе. Сервер OAuth должен игнорировать нераспознанные параметры запроса. Параметры запроса и ответа не должны быть включены более одного раза.
GTAF поддерживает только токены доступа типа bearer.

Область действия токена доступа

Конечные точки авторизации и токена позволяют клиенту указать область действия запроса доступа с помощью параметра запроса «scope». В свою очередь, сервер авторизации использует параметр ответа «scope», чтобы сообщить клиенту область действия выданного токена доступа.

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF не требует реализации области действия, но поддерживает эту функцию. Подробнее см. в разделе 3.3 RFC 6749 .

Выдача токена доступа

Если запрос токена доступа, отправленный GTAF, действителен и авторизован, сервер OAuth выдаёт токен доступа и, возможно, токен обновления. Если запрос не проходит аутентификацию клиента или недействителен, сервер OAuth возвращает ответ об ошибке, как описано в следующем разделе.

Успешный ответ

Когда GTAF отправляет запрос, сервер OAuth выдает токен доступа и необязательный токен обновления, а также формирует ответ, добавляя следующие параметры в тело сущности HTTP-ответа с кодом состояния 200 (OK): \

access_token: ОБЯЗАТЕЛЬНО. Токен доступа, выданный сервером OAuth. GTAF ожидает, что конечная точка токена вернет токен носителя.
expires_in: ОБЯЗАТЕЛЬНО. Срок действия токена доступа в секундах. Например, значение «3600» означает, что срок действия токена доступа истечёт через один час с момента генерации ответа. Если этот параметр не указан, сервер OAuth должен предоставить срок действия другими способами или задокументировать значение по умолчанию.
token_type: ОБЯЗАТЕЛЬНО. Тип выданного токена. Подробнее о различных типах токенов см. в разделе 7.1 RFC 6749. Значение не учитывает регистр. На момент написания этой статьи GTAF поддерживает только токены на предъявителя.
refresh_token: НЕОБЯЗАТЕЛЬНО. Токен обновления, который можно использовать для получения новых токенов доступа с использованием того же гранта авторизации.
область применения: ДОПОЛНИТЕЛЬНО, если реализовано и идентично области применения, запрошенной GTAF; в противном случае обязательно.

Параметры включаются в тело HTTP-ответа с помощью "application/json". Параметры сериализуются в структуру JavaScript Object Notation (JSON) путём добавления каждого параметра на самом высоком уровне структуры. Имена параметров и строковые значения включаются в виде строк JSON. Числовые значения включаются в виде чисел JSON. Порядок параметров не имеет значения и может меняться.

Сервер авторизации ДОЛЖЕН включать поле заголовка ответа HTTP «Cache-Control» со значением «no-store» в любой ответ, содержащий токены, учетные данные или другую конфиденциальную информацию, а также поле заголовка ответа «Pragma» со значением «no-cache».

Например:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Ниже приведены некоторые важные моменты, которые следует учитывать:

GTAF игнорирует нераспознанные имена значений в ответе.
Размеры токенов и других значений, полученных от сервера OAuth, остаются неопределенными.
GTAF следует избегать предположений о размерах значений. OAuth-сервер должен документировать размер любого выдаваемого им значения.

Ошибка ответа

Если запрос на авторизацию не удается выполнить по какой-либо причине, например из-за отсутствующего, недействительного или несовпадающего URI перенаправления, или если идентификатор клиента отсутствует или недействителен, сервер OAuth должен ответить кодом состояния HTTP 400 (неверный запрос) (если не указано иное) и должен включить по крайней мере один из параметров, перечисленных в разделе «Ответ и коды ошибок».

Грант на авторизацию в GTAF

Разрешение на авторизацию — это учетные данные, представляющие собой разрешение конечного пользователя (на доступ к его защищенным ресурсам, таким как информация о балансе данных), используемое GTAF для получения токена доступа.

GTAF использует тип гранта client_credentials . В этом типе гранта GTAF запрашивает токен, используя HTTP-запрос POST и базовую HTTP-аутентификацию. Все запросы отправляются по протоколу TLS (то есть HTTPS), и GTAF не может интегрироваться с сервером OAuth без действительного сертификата TLS. GTAF может передавать настраиваемую область действия токена и будет передавать пустую область действия, если она не настроена.

GTAF ожидает возврат токена доступа вместе со значением «expires_in» (срок действия). Значение expires_in должно быть не менее 900 секунд и не более нескольких часов. Запрос нового токена не должен приводить к преждевременному истечении срока действия существующих токенов.

Более подробную информацию о различных типах грантов см. в разделе 1.3 RFC 6749 .

Пример запроса и ответа

Предположим, что GTAF имеет следующую конфигурацию для сервера OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

Примечание: секрет клиента для настоящего DPA должен быть гораздо более безопасным, чем показанный в примере.

Для создания строки авторизации идентификатор клиента, «:» и пароль объединяются и кодируются в формате base64. Это можно воспроизвести в интерфейсе командной строки следующим образом:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

Затем GTAF отправляет HTTPS-запрос POST к серверу OAuth, используя эти учётные данные, тип гранта client_credentials и настроенную область действия. Например, запрос GTAF выглядит аналогично запросу, сгенерированному:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

Заголовки, используемые GTAF, не будут соответствовать заголовкам, отправленным curl, хотя заголовок авторизации будет идентичным.

GTAF ожидает ответ в форме:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

Ниже приведен пример правильного ответа:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

Примечание: ответ должен быть в формате JSON.

Ответ на ошибку и коды

Если запрос на авторизацию от GTAF не выполняется по любой из причин, указанных в разделе «Ответ об ошибке», сервер OAuth должен ответить кодом состояния HTTP 400 (неверный запрос) (если не указано иное) и включить в ответ один из следующих параметров:

Например: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF ожидает, что сервер OAuth будет поддерживать следующие ответы на ошибки:

Код ошибки	Ответ	Причина
HTTP 400	недействительный_запрос	В запросе отсутствует обязательный параметр, включено неподдерживаемое значение параметра (отличное от типа предоставления), параметр повторяется, включено несколько учетных данных, используется более одного механизма аутентификации в GTAF или он иным образом неверен.
HTTP 401	недействительный_клиент	Аутентификация клиента не удалась (например, неизвестный клиент, не включена аутентификация клиента или неподдерживаемый метод аутентификации). Сервер OAuth может вернуть код статуса HTTP 401 (Неавторизованный), указывающий на поддерживаемые схемы аутентификации HTTP. Если клиент попытался пройти аутентификацию через поле заголовка запроса «Authorization», сервер OAuth должен ответить кодом статуса HTTP 401 (Неавторизованный) и включить поле заголовка ответа «WWW-Authenticate», соответствующее схеме аутентификации, используемой клиентом.
HTTP 500	Ошибка сервера OAuth

Подробную информацию о других ответах, которые можно использовать для отладки, см. в разделе 5.2 RFC 6749 .

OAuth для API агента тарифного плана данных Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.