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

Введение

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

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

Аудитория

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

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

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

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

1. «Танец OAuth»

   Мой неофициальный термин для описания полного процесса аутентификации/авторизации OAuth.

2. (OAuth) Запрос токена

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

3. (OAuth) Токен доступа

   Последний шаг — обмен авторизованного токена запроса на токен доступа. Как только ваше приложение получит этот токен, пользователю больше не придётся проходить процедуру OAuth, если только токен не будет отозван.

   Сходство с AuthSub:
   Токен доступа OAuth — это то же самое, что и защищенный токен сеанса AuthSub.

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

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

   Получите токен запроса:	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 .

5. Поставщик услуг (OAuth)

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

6. (OAuth) Потребитель

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

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

Начиная

Регистрация

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

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

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

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

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

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-адрес в кодировке 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:

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

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 Data.

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

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

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

Шаг 1: Выберите области применения Сначала определите, какие API вы хотите использовать, выбрав одну или несколько областей действия . В этой демонстрации я запрашиваю токен, который будет работать с Blogger и Google Contacts. Сходство с AuthSub: AuthSub также требует параметр scope для управления диапазоном данных, к которым токен может получить доступ. Google реализовала этот параметр в соответствии со спецификацией OAuth .
Шаг 2: Измените параметры и настройки OAuth Пока не изменяйте настройки в поле «Изменить параметры OAuth». Позже вы сможете протестировать работу с собственным закрытым ключом, изменив oauth_consumer_key на свой зарегистрированный домен и введя свой закрытый ключ, нажав «Использовать свой закрытый ключ». Используйте только ТЕСТОВЫЙ закрытый ключ. Примечание : здесь можно редактировать только поля 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 были заполнены соответствующим значением, возвращаемым в теле ответа. На игровой площадке также отображается тип текущего oauth_token . В данный момент это токен запроса.
Далее нажмите кнопку «Авторизовать» в поле «Получить токен». На этой странице авторизации нажмите кнопку «Предоставить доступ», чтобы авторизовать токен запроса и вернуться обратно в OAuth Playground. Сходство с AuthSub: Эта страница авторизации такая же, как и для AuthSub. Отличие от AuthSub: Параметр URL- next 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

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

Пример: Как обновить публикацию

1. Найдите элемент <link> с атрибутом rel="edit" в записи, которую хотите обновить. Он должен выглядеть примерно так:

   <link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>

   Вставьте URL-адрес href в поле «Введите канал данных Google».

2. Скопируйте XML существующей записи, нажав «Просмотреть в обычном виде» в верхней части подсвеченной панели синтаксиса. Скопируйте только тело ответа, без заголовков.
3. Измените раскрывающийся список методов HTTP на PUT .
4. Нажмите «Ввести данные записи» под раскрывающимся списком и вставьте XML-код <entry> во всплывающее окно.
5. Нажмите кнопку «выполнить».

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

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

Заключение

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

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

Ресурсы

• Аутентификация OAuth для веб-приложений
• Список API данных Google
• Форум для обсуждения API Google Accounts
• Спецификация ядра OAuth 1.0