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

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

Соответствующие документы

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

Обзор

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

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

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

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

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

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

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

Маркеры доступа могут иметь различные форматы, структуры и методы использования (например, криптографические свойства) в зависимости от требований безопасности оператора связи. GTAF поддерживает только токены доступа типа носителя, определенные в [ 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 поддерживает только токены доступа на предъявителя.

Доступ к области токена

Конечные точки авторизации и токена позволяют клиенту указать область запроса на доступ с помощью параметра запроса «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 (ОК): \

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

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

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

Например:

     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 . В типе гранта 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 поддерживаются. Если клиент попытался пройти аутентификацию через поле заголовка запроса «Авторизация», сервер OAuth должен ответить кодом состояния HTTP 401 (Unauthorized) и включить поле заголовка ответа «WWW-Authenticate», соответствующее схеме аутентификации, используемой клиентом.
HTTP 500	Сбой сервера OAuth

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