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

Использование OAuth с API данных Google

Эрик Бидельман, команда Google Data API
сентябрь 2008 г.

Введение

Это захватывающее время для разработчиков. Мы начинаем видеть, как в Интернете принимается ряд открытых стандартов, и, как вы знаете, Google всегда был большим поклонником стандартов и поддерживал сообщество открытого исходного кода.

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

Аудитория

В этой статье предполагается, что вы знакомы с одним или несколькими API данных Google , но не обязательно с концепциями, лежащими в основе OAuth. Если вы только начинаете или вам просто интересно узнать об OAuth, не смотрите дальше. Эта статья даст вам базовую основу концепций. Я также расскажу о деталях реализации Google OAuth.

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

Немного терминологии

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

"OAuth танец"
Мой неофициальный термин для описания полного процесса аутентификации/авторизации OAuth.
(OAuth) Токен запроса
Начальный токен, который сообщает Google, что ваше приложение запрашивает доступ к одному из API данных Google. На втором этапе танца OAuth пользователь вручную предоставляет доступ к своим данным. Если этот шаг выполнен успешно, токен запроса становится авторизованным.
(OAuth) Маркер доступа
Последним шагом танца является обмен токена авторизованного запроса на токен доступа. Как только ваше приложение получит этот токен, пользователю не нужно будет снова проходить танец OAuth, если только токен не будет отозван.
Сходство с AuthSub:
Токен доступа OAuth — это то же самое, что и безопасный токен сеанса AuthSub.

(OAuth) Конечные точки

Это URI, необходимые для аутентификации приложения и получения токена доступа. Всего их три — по одному на каждый шаг процесса OAuth. Конечные точки Google OAuth:

Получите токен запроса:	`https://www.google.com/accounts/OAuthGetRequestToken`
Авторизуйте токен запроса:	`https://www.google.com/accounts/OAuthAuthorizeToken`
Обновление до токена доступа:	`https://www.google.com/accounts/OAuthGetAccessToken`

Сходство с AuthSub:
Обмен авторизованного токена запроса на токен доступа аналогичен обновлению одноразового токена AuthSub до долгоживущего токена сеанса на https://www.google.com/accounts/AuthSubRequestToken и https://www.google.com/accounts/AuthSubSessionToken соответственно. Разница в том, что AuthSub не имеет концепции токена начального запроса. Вместо этого пользователь запускает процесс токена со страницы авторизации AuthSubRequestToken .

(OAuth) Поставщик услуг
В случае API данных Google этим поставщиком является Google. Как правило, поставщик услуг используется для описания веб-сайта или веб-службы, предоставляющей конечные точки OAuth. Еще одним примером поставщика услуг OAuth является MySpace.
(OAuth) Потребитель
Программа, запрашивающая разрешение на доступ к данным пользователя (т.е. вашему приложению). Протокол OAuth является гибким, поскольку позволяет использовать самые разные типы клиентов (веб-клиенты, установленные, настольные, мобильные).

Примечание . Хотя протокол OAuth поддерживает сценарий использования рабочего стола или установленного приложения, Google поддерживает OAuth только для веб-приложений.

Начиная

Постановка на учет

Прежде чем вы сможете начать использовать OAuth с API данных Google, необходимо выполнить небольшую настройку. Поскольку все запросы OAuth должны быть подписаны цифровой подписью, вам сначала необходимо зарегистрировать свой домен и загрузить общедоступный сертификат в Google. Дополнительные сведения о том, как это сделать, см. в разделах Регистрация для веб-приложений и Генерация ключей и сертификатов для использования в зарегистрированном режиме .

Подписание запросов

Как только ваш домен зарегистрирован, вы готовы начать подписывать запросы. Одной из самых сложных концепций OAuth является правильное построение oauth_signature и понятие базовой строки подписи. Базовая строка — это данные, которые вы подписываете своим закрытым ключом (используя RSA_SHA1 ). Результатом является значение, которое вы установили для oauth_signature .

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

GET список календарей Google пользователя по адресу http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime .

Базовый формат строки	`base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters`
Пример базовой строки	`GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime`
Пример HTTP-запроса	GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0"

Примечание . Это означает только представление. Ваша oauth_signature будет намного длиннее.

Примечания к базовой строке:

Параметр запроса orderby=starttime сортируется вместе с остальными параметрами oauth_* в лексикографическом порядке значений байтов.
Эта строка также не содержит '?' характер.
Часть base-http-request-url содержит только базовый URL-адрес в кодировке: http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull .
oauth_token имеет двойное кодирование URL.

Примечания к заголовку Authorization :

Порядок параметров oauth_* не имеет значения в заголовке Authorization .
Заголовок не включает orderby=starttime как базовая строка. Этот параметр запроса сохраняется как часть URL-адреса запроса.

Дополнительные сведения о подписании запросов с помощью OAuth см. в разделе Подписание запросов OAuth .

Отличие от AuthSub:
Для сравнения, вот тот же пример с безопасным AuthSub:

Базовый формат строки base_string = http-method http-request-URL timestamp nonce

Пример базовой строки

Базовый формат строки	`base_string = http-method http-request-URL timestamp nonce`
Пример базовой строки	GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d
Пример HTTP-запроса	GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d

Пример HTTP-запроса

GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1"

Дополнительные сведения о подписании запросов с помощью AuthSub см. в разделе Подписание запросов AuthSub .

Инструмент OAuth Playground

Попробуйте!

Цель

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

OAuth Playground — это инструмент, который я создал, чтобы помочь разработчикам избавиться от проблем с OAuth. Вы можете использовать Playground для отладки проблем, проверки собственной реализации или экспериментов с API данных Google.

Что оно делает?

Иллюстрирует процесс аутентификации OAuth: получение токена запроса, авторизация токена и его обновление до токена доступа.
Отображает правильную базовую строку подписи для каждого запроса.
Отображает правильный заголовок Authorization для каждого запроса.
Демонстрирует, как использовать oauth_token для взаимодействия с фидом данных Google, прошедшим проверку подлинности. Вы можете GET / POST / PUT / DELETE данные.
Просматривайте аутентифицированный канал прямо в браузере.
Позволяет протестировать собственный oauth_consumer_key (ваш зарегистрированный домен) и закрытый ключ.
Узнайте, какие сервисы подачи данных Google доступны для вашего oauth_token .

Демонстрационный запуск

Шаг 1. Выберите области действия. Сначала решите, какие API вы хотите использовать, выбрав одну или несколько областей действия . В этой демонстрации я запрашиваю токен, который будет работать с Blogger и контактами Google. Сходство с AuthSub: AuthSub также требует, чтобы параметр `scope` управлял диапазоном данных, к которым может получить доступ токен. Google реализовал этот параметр, как это предлагается в спецификации OAuth .
Шаг 2. Измените параметры и настройки OAuth Пока не изменяйте никакие настройки в поле «Изменить параметры OAuth». Позже вы можете протестировать свой собственный закрытый ключ, изменив `oauth_consumer_key` на свой зарегистрированный домен и введя свой закрытый ключ, нажав «использовать свой собственный закрытый ключ». Пожалуйста, используйте только закрытый ключ TEST . Примечание . `oauth_signature_method` и `oauth_consumer_key` — это единственные поля, которые здесь доступны для редактирования. `oauth_timestamp` , `oauth_nonce` и `oauth_token` будут сгенерированы автоматически. В дополнение к `RSA-SHA1` вы можете использовать `HMAC-SHA1` для `oauth_signature_method` . В этом случае на игровой площадке появятся дополнительные поля, в которых вам нужно будет ввести свой собственный `oauth_consumer_key` и секрет потребителя. Эти значения можно найти на странице https://www.google.com/accounts/ManageDomains для зарегистрированного домена. Отличие от AuthSub: В безопасном AuthSub нет параметра для явного задания доменного имени. Домен включен как часть `next` параметра URL. В OAuth есть такой параметр: `oauth_consumer_key` . Установите его на свой зарегистрированный домен.
Шаг 3-5: Получите токен доступа Чтобы получить токен доступа OAuth, нужно выполнить три шага. Первым шагом является получение токена запроса. Это позволяет Google узнать, что ваше приложение запускает танец OAuth. Сначала нажмите кнопку «Запросить токен» в поле «Получить токен». Некоторые поля будут заполнены данными. «Базовая строка подписи» отображает правильную форму базовой строки, используемой для создания параметра `oauth_signature` . «Заголовок авторизации» отображает соответствующий заголовок `Authorization` для запроса. Поле «Изменить параметры OAuth» заполнено значениями `oauth_nonce` и `oauth_timestamp` , отправленными в запросе. Вход `oauth_token` был заполнен соответствующим значением, возвращенным в тексте ответа. Playground также отображает, какой тип `oauth_token` у нас есть в настоящее время. На данный момент это токен запроса.
Далее нажмите кнопку «Авторизоваться» в поле «Получить токен». На этой странице авторизации нажмите кнопку «Предоставить доступ», чтобы авторизовать токен запроса и перенаправить обратно на игровую площадку OAuth. Сходство с AuthSub: Эта страница авторизации одинакова для AuthSub. Отличие от AuthSub: `next` параметр URL-адреса AuthSub аналогичен параметру `oauth_callback` . Разница в том, что в OAuth `oauth_callback` является необязательным. После того, как пользователь нажмет кнопку «Предоставить доступ», токен запроса будет авторизован, и обновление токена до `https://www.google.com/accounts/OAuthGetAccessToken` может быть выполнено асинхронно. Совет . Указание URL-адреса `oauth_callback` предпочтительнее, если вы пишете веб-приложение, поскольку оно обеспечивает лучший пользовательский интерфейс.
Наконец, нажмите кнопку «Токен доступа» в поле «Получить токен». Это действие обновляет маркер авторизованного запроса (обозначенный красной меткой «маркер доступа»). Если вы хотите получить новый токен, нажмите «Начать сначала», чтобы повторно инициировать танец OAuth. Теперь мы можем сделать что-то интересное!

Использование токена доступа

Теперь вы готовы запрашивать фиды, вставлять, обновлять или удалять данные. Пожалуйста, будьте осторожны при выполнении этих трех последних HTTP-методов, поскольку вы работаете с реальными данными!

Совет . Чтобы найти фиды, доступные для вашего токена доступа, нажмите кнопку «Доступные фиды».

Вот пример запроса: GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3

Этот пример возвращает не более трех сообщений в определенном блоге. Вы также можете просмотреть возвращенный фид/запись непосредственно в браузере, щелкнув ссылку «Просмотреть в браузере» под выделенной областью синтаксиса.

Пример: Как обновить сообщение

Найдите элемент <link> с rel="edit" в сообщении, которое вы хотите обновить. Это должно выглядеть примерно так:
```
<link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>
```
Вставьте URL-адрес href в поле ввода «Введите фид данных Google».
Скопируйте XML существующей записи, щелкнув «просмотреть обычный» в верхней части панели с выделенным синтаксисом. Скопируйте только тело ответа, а не заголовки.
Измените раскрывающийся список методов HTTP на PUT .
Нажмите «ввести данные поста» под этим раскрывающимся списком и вставьте <entry> XML во всплывающее окно.
Нажмите кнопку «выполнить».

Сервер ответит 200 OK .

Совет . Вместо того, чтобы вручную копировать ссылку edit , снимите флажок «Подсветка синтаксиса?». флажок. После запроса вы сможете щелкнуть ссылки в теле ответа XML.

Заключение

Такие технологии, как AtomPub/Atom Publishing Protocol (протокол, лежащий в основе API данных Google ) и OAuth , помогают продвигать Интернет вперед. Поскольку все больше и больше сайтов начинают использовать эти стандарты, мы, разработчики, становимся победителями. Создание приложения-убийцы внезапно становится менее пугающим.

Если у вас есть какие-либо вопросы или комментарии об OAuth Playground или использовании OAuth с API Google, посетите наш форум поддержки API G Suite и API Marketplace .