Аутентификация и авторизация в протоколе данных Google

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

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

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

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

Службы аутентификации и авторизации часто вместе называются auth .

Аутентификация и авторизация для 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 .

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

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, могут использовать реализацию Google OAuth API. Полную информацию о реализации OAuth для веб-приложений, включая примеры, см. в руководстве по OAuth для веб-приложений или в обзоре в этом документе.

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

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

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

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

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

Процесс авторизации 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, чтобы определить, работает ли этот API только с зарегистрированными приложениями.

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

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

Дополнительные сведения о процессе регистрации см. в разделе Регистрация для веб-приложений .

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

Каждая служба Google устанавливает ограничения на доступ, который она разрешает через API данных Google. Этот доступ выражается как значение области. Некоторые службы предоставляют различные значения области действия, чтобы позволить пользователю выбирать, какие приложения должны иметь доступ к тем или иным данным. Информацию о доступных значениях области для службы 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-адреса обратного вызова

Вы можете указать значение для oauth_callback в запросе OAuthGetRequestToken , чтобы определить, куда 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 отображает строку «анонимно».

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

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

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

Если ваше приложение предназначено для пользователей в размещенном домене учетных записей Google, рассмотрите возможность использования параметра 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. Этот доступ выражается как значение области. Некоторые службы предоставляют различные значения области действия, чтобы позволить пользователю выбирать, какие приложения должны иметь доступ к тем или иным данным. Информацию о доступных значениях области для службы 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 отображает строку «анонимно».

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

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

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

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

Режим автоопределения

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Вернуться к вершине

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

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

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

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

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

  1. Когда веб-приложению необходимо получить доступ к службе Google пользователя, оно выполняет вызов AuthSub к службе прокси-сервера авторизации Google.
  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 не настроены для управления большим количеством токенов и фактически не позволяют одновременно использовать более десяти действительных токенов (на пользователя, на одно веб-приложение). Это ограничение позволяет веб-приложению получать несколько токенов для покрытия различных служб, если это необходимо; он не поддерживает получение нового токена каждый раз, когда веб-приложению требуется доступ к службе Google. Если вы решите хранить токены сеанса, с ними следует обращаться так же безопасно, как и с любой другой конфиденциальной информацией, хранящейся на сервере.

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

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

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

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

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

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

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

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

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

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

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

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

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

    Authorization: AuthSub token="token"

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

    В приведенном ниже примере показан заголовок запроса для вызова службы каналов Календаря Google. Этот запрос содержит незащищенный токен:

    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

Дополнительная информация об 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:

Back to top

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

Back to top

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 .

Authentication flow

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:

Back to top