Аутентификация и авторизация в протоколе Google Data Protocol

Внимание : Эта страница посвящена старым API Google, Google Data API; она актуальна только для API, перечисленных в каталоге Google Data APIs, многие из которых были заменены более новыми API. Информацию о конкретном новом API см. в документации к нему. Информацию об авторизации запросов с использованием более нового API см. в разделе «Аутентификация и авторизация учетных записей Google» .

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

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

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

Службы аутентификации и авторизации часто объединяют под общим названием «аутентификация» .

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

  • Google Sign-In предоставляет простой способ авторизации пользователей на вашем сайте с помощью их учетных данных Google. Он включает в себя набор инструментов, которые легко интегрируются на различных устройствах.
  • OAuth 2.0 — это протокол авторизации для всех API Google. OAuth 2.0 использует SSL для обеспечения безопасности, вместо того чтобы требовать от вашего приложения прямой криптографической подписи. Этот протокол позволяет вашему приложению запрашивать доступ к данным, связанным с учетной записью Google пользователя.
  • Вход через OAuth 2.0 ( OpenID Connect ) аутентифицирует пользователей, заставляя их входить в систему с помощью своих учетных записей Google. Это замена OpenID , и пользователям OpenID следует планировать переход на вход через OAuth 2.0.

Если ваше приложение представляет собой гаджет (для использования в iGoogle или других контейнерах OpenSocial), см. раздел «Аутентификация для гаджетов» .

Примечание : Данный документ предназначен для предоставления общего обзора каждого метода аутентификации. Для получения подробной информации о каждом методе см. полную документацию по API аутентификации учетных записей Google .

См. также группу Google Accounts API для обсуждения использования API Google Accounts.

OAuth — авторизация для веб-приложений и установленных приложений.

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

Google поддерживает две версии OAuth для авторизованного доступа к данным пользователя Google: OAuth 1.0 и OAuth 2.0, обе обеспечивают доступ как к веб-приложениям, так и к установленным приложениям.

OAuth 2.0 для веб-приложений и стационарных приложений

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

OAuth 1.0 для веб-приложений

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

OAuth 1.0 для установленных приложений

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

Использование OAuth в веб-приложениях

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

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

Процесс авторизации OAuth

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

На базовом уровне процесс выглядит следующим образом:

  1. Ваше приложение запрашивает доступ и получает от сервера авторизации Google токен несанкционированного запроса.
  2. Google запрашивает у пользователя разрешение на предоставление доступа к необходимым данным.
  3. Ваше приложение получает авторизованный токен запроса от сервера авторизации.
  4. Вы обмениваете авторизованный токен запроса на токен доступа.
  5. Вы используете токен доступа для запроса данных с серверов доступа к сервисам Google.

Когда ваше приложение впервые запрашивает доступ к данным пользователя, Google отправляет вашему приложению токен несанкционированного запроса.

Если пользователь еще не авторизован, Google предложит ему войти в систему. Затем Google отобразит страницу авторизации, которая позволит пользователю увидеть, к каким данным сервисов Google запрашивает доступ ваше приложение.

Если пользователь одобряет запрос на доступ к вашему приложению, Google выдает авторизованный токен запроса. Каждый токен запроса действителен только в течение одного часа. Обменять авторизованный токен запроса на токен доступа можно только один раз, и этот обмен возможен только один раз для каждого авторизованного токена запроса.

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

Подготовка к OAuth

Прежде чем настраивать приложение для использования службы авторизации Google с OAuth, необходимо выполнить следующие задачи.

Решение о регистрации вашего веб-приложения

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

Ваше приложение должно подписывать каждый отправляемый запрос OAuth. Если вы решите использовать подпись RSA-SHA1 для подписи запросов, вам необходимо загрузить сертификат безопасности в рамках процесса регистрации.

В качестве альтернативы вы можете использовать подпись HMAC-SHA1 для подписания ваших запросов. Для подписей HMAC-SHA1 сертификат не требуется. Вместо этого Google генерирует consumer secret OAuth, которое отображается на странице регистрации вашего домена после регистрации.

Для получения более подробной информации о процессе регистрации см. раздел «Регистрация веб-приложений» .

Определение объема данных, к которым будет иметь доступ ваше приложение.

Каждый сервис Google устанавливает ограничения на доступ, предоставляемый через API данных Google. Этот доступ выражается в виде значения параметра scope. Некоторые сервисы предоставляют несколько значений scope, позволяя пользователю выбирать, какие приложения должны иметь доступ к каким данным. Информацию о доступных значениях scope для сервиса Google, к которому вы хотите получить доступ, см. в документации к этому сервису.

Как правило, следует запрашивать токен для самой узкой области действия, включающей необходимые данные. Например, если вашему приложению требуется доступ к ленте «Все календари» пользователя, следует запросить токен для области действия http://www.google.com/calendar/feeds/default/allcalendars/full .

Создание механизма для управления токенами OAuth.

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

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

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

Настройка механизма запроса доступа к сервису Google.

Каждый запрос к сервису Google должен быть подписан и содержать действительный токен доступа OAuth. Как правило, каждый запрос выполняется в виде HTTP GET-запроса, при этом токен доступа и подпись включаются в заголовок. Запросы, записывающие новые данные, должны использовать HTTP POST.

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

Внедрение OpenID (необязательно)

Если вы используете OpenID для аутентификации пользователей, рассмотрите возможность применения гибридного протокола для объединения двух процессов. В случае OpenID+OAuth задачи получения токена запроса и его авторизации обрабатываются в рамках запроса OpenID с помощью расширений OAuth. Как и в случае с OAuthGetRequestToken , эти расширения используются для идентификации сервисов Google, к которым будет осуществляться доступ. Успешный ответ на запрос OpenID содержит авторизованный токен запроса. После получения этого токена используйте OAuthGetAccessToken для обмена его на токен доступа.

Работа с токенами OAuth

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

  1. Получение токена несанкционированного запроса ( OAuthGetRequestToken )
  2. Авторизуйте токен запроса ( OAuthAuthorizeToken )
  3. Обменяйте авторизованный токен запроса на токен доступа ( OAuthGetAccessToken ).

Все запросы OAuth должны быть подписаны, независимо от того, зарегистрировано ваше приложение или нет. Для получения дополнительной информации см. раздел «Подписание запросов OAuth» .

Вы можете поэкспериментировать с запросом и получением токенов авторизации в OAuth Playground .

Подробную документацию см. в справочнике по API OAuth .

Установка URL-адреса обратного вызова

В запросе OAuthGetRequestToken можно указать значение параметра oauth_callback , чтобы определить, куда Google перенаправит пользователя после авторизации запроса на доступ. URL-адрес обратного вызова может включать параметры запроса. Перенаправление будет включать те же параметры запроса, а также авторизованный токен запроса, который ваше приложение должно уметь анализировать.

Например, при поддержке нескольких языков можно добавить параметр запроса, указывающий версию приложения, которую просматривает пользователь. Значение oauth_callback "http://www.yoursite.com/Retrievetoken?Lang=de" приведет к перенаправлению "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Анализ токена и параметра языка гарантирует, что пользователь будет перенаправлен на правильную версию сайта.

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

Идентификация вашего приложения для пользователей

Обычно Google отображает название приложения при запросе согласия пользователя на доступ ( см. пример ).

Если ваше приложение не зарегистрировано, используйте параметр xoauth_displayname в запросе OAuthGetRequestToken , чтобы указать имя вашего приложения. Если этот параметр не указан, Google отобразит доменное имя URL-адреса, указанного в параметре oauth_callback . Если URL-адрес обратного вызова не указан, Google отобразит строку "anonymous".

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

Примечание: Чтобы установить параметр xoauth_displayname в OAuth Playground , установите флажок "Дополнительно" перед получением токена запроса.

Работа с доменами Google Apps

Если ваше приложение предназначено для пользователей, использующих размещенный домен Google Accounts, рассмотрите возможность использования параметра hd при авторизации токена. Дополнительную информацию о параметре hd см. в разделе « Обработка пользователей с несколькими учетными записями» .

Дополнительная информация об OAuth

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

Вернуться наверх

Использование OAuth с установленными приложениями

Все API данных Google поддерживают OAuth — открытый стандарт для авторизации использования данных в приложениях. Установленные приложения не обязательно должны быть зарегистрированы в Google для использования OAuth.

Процесс авторизации OAuth

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

На базовом уровне процесс выглядит следующим образом:

  1. Ваше приложение запрашивает доступ и получает от сервера авторизации Google токен несанкционированного запроса.
  2. Google запрашивает у пользователя разрешение на предоставление доступа к необходимым данным.
  3. Ваше приложение получает авторизованный токен запроса от сервера авторизации.
  4. Вы обмениваете авторизованный токен запроса на токен доступа.
  5. Вы используете токен доступа для запроса данных с серверов доступа к сервисам Google.

Когда ваше приложение впервые запрашивает доступ к данным пользователя, Google отправляет вашему приложению токен несанкционированного запроса.

Если пользователь еще не авторизован, Google предложит ему войти в систему. Затем Google отобразит страницу авторизации, которая позволит пользователю увидеть, к каким данным сервисов Google запрашивает доступ ваше приложение.

Если пользователь одобряет запрос на доступ к вашему приложению, Google выдает авторизованный токен запроса. Каждый токен запроса действителен только в течение одного часа. Обменять авторизованный токен запроса на токен доступа можно только один раз, и этот обмен возможен только один раз для каждого авторизованного токена запроса.

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

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

Подготовка к OAuth

Прежде чем настраивать приложение для использования службы авторизации Google с OAuth, необходимо выполнить следующие задачи.

Определение объема данных, к которым будет иметь доступ ваше приложение.

Каждый сервис Google устанавливает ограничения на доступ, предоставляемый через API данных Google. Этот доступ выражается в виде значения параметра scope. Некоторые сервисы предоставляют несколько значений scope, позволяя пользователю выбирать, какие приложения должны иметь доступ к каким данным. Информацию о доступных значениях scope для сервиса Google, к которому вы хотите получить доступ, см. в документации к этому сервису.

Как правило, следует запрашивать токен для самой узкой области действия, включающей необходимые данные. Например, если вашему приложению требуется доступ к ленте «Все календари» пользователя, следует запросить токен для области действия http://www.google.com/calendar/feeds/default/allcalendars/full .

Создание механизма для управления токенами OAuth.

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

Ваше приложение должно обеспечивать безопасное хранение токенов, включая отслеживание того, для какого сервиса Google действителен каждый токен.

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

Настройка механизма запроса доступа к сервису Google.

Каждый запрос к сервису Google должен быть подписан и содержать действительный токен доступа OAuth. Как правило, каждый запрос выполняется в виде HTTP GET-запроса, при этом токен доступа и подпись включаются в заголовок. Запросы, записывающие новые данные, должны использовать HTTP POST.

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

Работа с токенами OAuth

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

  1. Получение токена несанкционированного запроса ( OAuthGetRequestToken )
  2. Авторизуйте токен запроса ( OAuthAuthorizeToken )
  3. Обменяйте авторизованный токен запроса на токен доступа ( OAuthGetAccessToken ).

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

Вы можете поэкспериментировать с запросом и получением токенов авторизации в OAuth Playground .

Подробную документацию см. в справочнике по API OAuth .

Идентификация вашего приложения для пользователей

Обычно Google отображает название приложения при запросе согласия пользователя на доступ ( см. пример ).

Используйте параметр xoauth_displayname в запросе OAuthGetRequestToken , чтобы указать имя вашего приложения. Если этот параметр не указан, Google отобразит доменное имя URL-адреса, указанного в параметре oauth_callback . Если URL-адрес обратного вызова не указан, Google отобразит строку "anonymous".

Примечание: Чтобы установить параметр xoauth_displayname в OAuth Playground , установите флажок "Дополнительно" перед получением токена запроса.

Запуск веб-браузера

В рамках процесса авторизации OAuth ваше приложение должно отправить запрос OAuthAuthorizeToken . Затем пользователь должен войти на веб-страницу Google и авторизовать запрос на доступ вашего приложения.

  • В большинстве случаев следует использовать режим автоматического определения.
  • Режим устройства следует использовать для приложений, которые не могут запустить полноценный веб-браузер.
  • Режим разработки следует использовать только на ранних этапах разработки.

Режим автоматического определения

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

В этом режиме необходимо указать URL-адрес обратного вызова, на который пользователь будет перенаправлен после подтверждения запроса на доступ. Этот URL-адрес должен быть указан в качестве параметра oauth_callback запроса OAuthGetRequestToken и в качестве параметра verifier запроса OAuthGetAccessToken .

Для улучшения пользовательского опыта ваше приложение должно пытаться автоматически определять, когда пользователь перенаправляется на этот URL-адрес, и немедленно переводить себя в активный режим, выполняя запрос OAuthGetAccessToken для завершения процесса аутентификации OAuth.

Для получения дополнительной информации и рекомендаций по передовым методам см. раздел «Автоматическое определение одобрения» .

Если ваше приложение не может автоматически определить, когда пользователь перенаправляется на URL-адрес обратного вызова, или не может перевести себя на передний план, на URL-адресе обратного вызова должна отображаться страница с объяснением того, как перевести ваше приложение на передний план и как инициировать запрос OAuthGetAccessToken из вашего приложения.

Режим устройства

Если ваше приложение не может запустить полноценный веб-браузер, то для устройств с расширенными возможностями авторизация может осуществляться и без веб-браузера .

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

Режим разработки

Этот режим рекомендуется использовать только на ранних этапах разработки приложения.

Как и в режиме автоматического определения, ваше приложение должно запустить браузер, и пользователь должен авторизовать ваш запрос. Однако вместо создания веб-страницы для URL-адреса обратного вызова вы можете установить значение параметра oauth_callback равным "oob" (out of band).

В этом случае после подтверждения пользователем вашего запроса Google перенаправит его на страницу учетных записей Google, где отобразится проверочный номер (см. пример ).

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

Дополнительная информация об OAuth

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

Вернуться наверх

Использование AuthSub для авторизации.

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

Процесс авторизации AuthSub

Авторизация с помощью AuthSub включает в себя последовательность взаимодействий между тремя сущностями: веб-приложением, сервисами Google и пользователем. На этой диаграмме показана эта последовательность:

Процесс авторизации

  1. Когда веб-приложению необходимо получить доступ к сервису Google пользователя, оно выполняет вызов AuthSub к сервису авторизации Google Authorization Proxy.
  2. Служба авторизации отвечает, отображая страницу запроса доступа. На этой странице, управляемой Google, пользователю предлагается предоставить/отказать в доступе к своему сервису Google. Пользователю может быть предложено сначала войти в свою учетную запись.
  3. Пользователь решает, разрешить или запретить доступ к веб-приложению. Если пользователь запрещает доступ, он перенаправляется на страницу Google, а не обратно в веб-приложение.
  4. Если пользователь предоставляет доступ, служба авторизации перенаправляет его обратно в веб-приложение. Перенаправление содержит токен авторизации, действительный для однократного использования; его можно обменять на долгосрочный токен.
  5. Веб-приложение отправляет запрос в сервис Google, используя токен авторизации в качестве агента пользователя.
  6. Если сервис Google распознает токен, он предоставит запрошенные данные.

Работа с AuthSub

Для интеграции AuthSub в ваше веб-приложение необходимо выполнить следующие задачи:

  1. Решите, стоит ли регистрировать ваше веб-приложение.

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

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

  2. Определите, какие типы токенов использовать и как ими управлять.

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

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

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

  3. Определите область действия, необходимую для доступа к сервису Google.

    Каждый сервис Google определяет объем и тип разрешенного доступа. Этот доступ выражается значением области действия (scope). Область действия сервиса может представлять собой простой URL-адрес, идентифицирующий весь сервис, или же указывать на более ограниченный доступ. Некоторые сервисы существенно ограничивают доступ, например, разрешая доступ только для чтения к ограниченной информации. Чтобы узнать разрешенные области действия для сервиса Google, к которому вы хотите получить доступ, обратитесь к документации этого сервиса. Вам следует запрашивать токен с максимально узкой областью действия. Например, если вы пытаетесь получить доступ к функции Atom-ленты Gmail, используйте область действия "http://www.google.com/calendar/feeds/", а не "http://www.google.com/calendar/". Сервисы Google гораздо более строги к запросам с большой областью действия.

  4. Создайте механизм для запроса и получения авторизационного токена.

    Механизм должен генерировать корректный вызов AuthSubRequest , включая указание соответствующих значений URL-адресов next и scope (определяемых на шаге 3). Если вы используете защищенные токены и/или управляете токенами сессии, запрос также должен включать значения для этих переменных.

    В URL-адресе next можно указать параметры запроса. Например, при поддержке нескольких языков следует добавить параметр запроса, указывающий версию веб-приложения, которое просматривает пользователь. Значение next , равное http://www.yoursite.com/Retrievetoken?Lang=de , приведет к перенаправлению на http://www.yoursite.com/Retrievetoken?Lang=de&token=DQAADKEDE . Анализ токена и параметра Lang гарантирует, что пользователь будет перенаправлен на правильную версию сайта.

    В некоторых случаях использование параметра hd может упростить взаимодействие пользователей с сайтом Google Accounts при запросе на предоставление доступа. В большинстве случаев процесс сводится к простому входу в учетную запись и выбору, предоставлять доступ или нет. Однако пользователям, имеющим более одной учетной записи Google (обычную учетную запись Gmail и/или одну или несколько учетных записей Google Apps), может потребоваться дополнительная процедура «универсального входа», чтобы указать, к какой учетной записи они хотят получить доступ. Если ваше приложение разработано для одного конкретного управляемого домена, вы можете исключить эти дополнительные шаги, используя этот параметр для идентификации этого домена. Вы также можете использовать параметр hd , если ваше приложение обращается к сервисам, недоступным в учетных записях — установка значения «default» ограничит авторизацию только обычными учетными записями. При установке значения hd Google автоматически выберет правильную учетную запись для авторизации.

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

  5. Настройте механизмы для запроса токенов сессии, а также для их хранения или отзыва, если это необходимо.

    В зависимости от решений по управлению токенами, принятых на шаге 2, вам может потребоваться создать механизмы для получения и отзыва токенов сессии ( AuthSubSessionToken и AuthSubRevokeToken ). Для тестирования механизмов сессии и отзыва используйте AuthSubTokenInfo , который указывает, действителен ли данный токен или нет. При хранении токенов приложение должно отслеживать как идентификатор пользователя, так и услугу (область действия), охватываемую токеном.

  6. Настройте механизм для запроса доступа к сервису Google.

    Для получения информации о правильном формате запроса обратитесь к документации сервиса Google. Все запросы к сервису Google должны содержать действительный токен авторизации. Как правило, запрос к сервису Google имеет вид HTTP GET (или POST, если записываются новые данные), при этом токен указывается в заголовке запроса.

    Заголовок запроса должен иметь следующий вид:

    Authorization: AuthSub token="token"

    где token — это токен авторизации, одноразовый или сессионный, полученный от Google в ответ на запрос AuthSub. Если токен является защищенным, он должен сопровождаться цифровой подписью. См. раздел « Подписание запросов » для получения инструкций и примеров.

    The example below illustrates a request header for a call to the Google Calendar feed service. This request contains a non-secure token:

    GET /calendar/feeds/default/private/full HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="GD32CMCL25aZ-v____8B"
User-Agent: Java/1.5.0_06
Host: www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive

More information about AuthSub

For information on AuthSub, including registering your application with Google and a detailed explanation of exchanging a one-time token for a session token, see these additional resources:

Вернуться наверх

Using ClientLogin for authorization

ClientLogin is a Google proprietary authorization API, available as an alternative to OAuth for most Google APIs. You should avoid using ClientLogin if possible. If you already have applications that use ClientLogin, you should migrate to OAuth or the hybrid protocol.

Authentication for Installed Applications: ClientLogin

ClientLogin allows your users to log into their Google account from inside your application. The application then contacts Google with the login data and requests access to a specified Google Data API. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account, such as to get or post data. The token remains valid for a set length of time, defined by whichever Google service you're working with.

Note : The Google Data APIs Client Libraries provide methods to help you use ClientLogin in your installed applications. Specifically, there are methods for acquiring an authentication token, handling CAPTCHA challenges, recalling the auth token for later use, and sending the correct Authorization header with every request. If you are working with one of the libraries, see Using ClientLogin with the Google Data APIs Client Libraries .

The ClientLogin authorization process

Authorization with ClientLogin involves a sequence of interactions between three entities: the installed application, Google services, and the user. This diagram illustrates the sequence:

Authorization process

  1. When the third-party application needs to access a user's Google service, it retrieves the user's login name and password.
  2. The third-party application then makes a ClientLogin call to Google's Authorization service.
  3. If the Google Authorization service decides additional vetting is necessary, it returns failure response with a CAPTCHA token and challenge, in the form of a URL for a CAPTCHA image.
  4. If a CAPTCHA challenge is received, the third-party application displays the CAPTCHA image for the user and solicits an answer from the user.
  5. If requested, the user submits an answer to the CAPTCHA challenge.
  6. The third-party application makes a new ClientLogin call, this time including the CAPTCHA answer and token (received with the failure response).
  7. On a successful login attempt (with or without CAPTCHA challenge), the Google Authorization service returns a token to the application.
  8. The application contacts the Google service with a request for data access, referencing the token received from the Google Authorization service.
  9. If the Google service recognizes the token, it supplies the requested data access.

Using ClientLogin

Use this interface in your installed application to programmatically access a user's Google account. After collecting login information from the user, call ClientLogin to request access to the user's account. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account. The token remains valid for a set length of time, which is defined by whichever Google service you're working with.

Incorporating ClientLogin into your application requires these tasks:

  1. Create a UI element to capture login data from the user.

    The UI needs to solicit a user name (email address including domain) and password. The UI should also be capable of displaying a CAPTCHA image using the URL received from Google, if one is required, and soliciting a correct answer from the user. Ideally, your UI will include a link to Google Accounts login page ("https://www.google.com/accounts/Login") in the event that the user needs to sign up for a new account or do other account maintenance.

  2. Write code to generate a well-formed HTTPS POST ClientLogin request and transmit it.

    This code needs to contain logic to handle a CAPTCHA challenge and include both the logintoken and logincaptcha parameters. The application should also be able to detect when the user omits required information--or repeats incorrect data after a login failure--and display an error without sending a superfluous request.

  3. Handle responses from Google.

    There are four possible responses to a login request:

    • success (an HTTP 200)
    • failure (an HTTP 403) with an explanatory error code
    • invalid request, generally resulting from a malformed request
    • failure with a CAPTCHA challenge

    A success response contains an authorization token labeled "Auth". This token must be included in all subsequent requests to the Google service for this account. Authorization tokens should be closely guarded and should not be given to any other application, as they represent access to the user's account. The time limit on the token varies depending on which service issued it.

    A failure response includes one or more error codes and a URL with the error message that can be displayed for the user. Please note that ClientLogin does not differentiate between a failure due to an incorrect password or one due to an unrecognized user name (for example, if the user has not yet signed up for an account). Your application needs to handle all possible error messages as appropriate.

    A failure response with a CAPTCHA challenge means that Google has decided, for whatever reason, that additional security measures should be taken. This response is accompanied by a CAPTCHA image URL and a token representing the specific CAPTCHA challenge.

  4. Handle a CAPTCHA challenge from Google.

    To handle the challenge, the application must display the CAPTCHA image and solicit an answer from the user. To display the CAPTCHA image, use the value of CaptchaUrl returned with the failure response, prefixing it with the Google Accounts URL: "http://www.google.com/accounts/". Once the user provides an answer, the application should resend the login request, this time including the CAPTCHA token ( logintoken ) and the user's answer ( logincaptcha ). Google validates the user's answer before authorizing access to the account.

    There is an alternative for developers who do not want to manage the process's of getting and transmitting a user CAPTCHA response. In response to a CAPTCHA challenge, the application can direct the user to the Google hosted page: "https://www.google.com/accounts/DisplayUnlockCaptcha". Once the user has successfully responded to the challenge, the Google server trusts the computer in use. The application can then resend the original login request to obtain the authorization token.

    5. Note: Google does not validate the login attempt prior to issuing a CAPTCHA challenge. This means a login attempt could fail even after a CAPTCHA challenge.

* CAPTCHA is a trademark of Carnegie Mellon University

Вернуться наверх

Authentication for Gadgets

OAuth Proxy

If you're building a gadget using the standard Gadgets API , you can leverage a feature of the gadget platform called the OAuth Proxy to access the Google Data APIs. OAuth ( described above ) is an authentication standard that allows users to access their private data in a gadget hosting service such as iGoogle, MySpace, or Orkut, or share their data with another website or gadget. The OAuth Proxy is designed to make development easier for gadget developers by hiding many of OAuth's authentication details. The Proxy is based on an open-source project called Shindig , which is an implementation of the gadget specification.

Note : The OAuth Proxy is only supported for gadgets that use the gadgets.* API and run in OpenSocial containers. It is not supported for the legacy gadgets API .

Процесс аутентификации

Your gadget must obtain an OAuth token before it can access a user's data. The OAuth Proxy manages the authentication flow for you. The first time a user installs your gadget, the following process takes place:

  1. Your gadget loads for the first time and attempts to access the user's data using one of the Google Data APIs.
  2. The request fails because the user hasn't granted access. The response object contains a URL (in response.oauthApprovalUrl ) for the OAuth approval page. Your gadget should provide a method to launch a new window with that URL.
  3. On the approval page, the user chooses to grant or deny access to your gadget. If successful, the user is taken to the oauth_callback page you specify. For the best user experience, use http://oauth.gmodules.com/gadgets/oauthcallback .
  4. Next, the user closes the popup window. To notify your gadget that the user has approved, you can use a popup handler to detect the approval window closing. Alternatively, your gadget can display a link (eg " I've approved access ") for the user to click after this window closes.
  5. Your gadget attempts to access the Google Data API a second time by re-requesting the user's data. This attempt is successful.
  6. Your gadget is authenticated and can begin operating normally.

Gadget setup

To access one or more of the Google Data APIs, you first need to tell your gadget to use OAuth as the authentication method. Add an <OAuth> element in the <ModulePrefs> section of your gadget's XML:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
  </Service>
</OAuth>
...
</ModulePrefs>

In this section, only change the following query parameters:

scope
A required parameter in the Request URL. Your gadget can access data from the scope (s) used in this parameter. In this example, the gadget can access Blogger and Calendar data. A gadget can request data for a single scope or multiple scopes, as this example does.
oauth_callback
An optional parameter in the Authorization URL. The OAuth approval page redirects to this URL after the user has approved access to data. You should set this parameter to http://oauth.gmodules.com/gadgets/oauthcallback to provide the best user experience when users install your gadget. That page provides a snippet of JavaScript that automatically closes the popup window. Alternatively, you can set this parameter to point to your own "approved" page, or you can simply leave the parameter blank.

Accessing an authenticated Google Data API feed

Once your gadget has authenticated the user, accessing a Google Data API is straightforward with the Google Data APIs JavaScript client library. For information on how to use the library in the OAuth Proxy, see Using the JavaScript Client Library .

More information about Gadgets

For complete information on creating Google Data API Gadgets, including details on the OAuth Proxy, an article on how to get started, and the gadgets.* spec, see these additional resources:

Вернуться наверх