Аутентификация OAuth2

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

Создание учетных данных OAuth2

Чтобы создать учетные данные OAuth2, выполните перечисленные ниже действия.

1. Определение типа приложения

Во-первых, нужно определить тип приложения, которое вы хотите создать. В AdWords API существует два типа приложений:

  • устанавливаемое приложение (рекомендуется);
  • веб-приложение.

С помощью приведенной ниже таблицы определите нужный тип приложения.

Что нужно выбрать Ситуация
Устанавливаемое приложение (рекомендуется)
  • Вы управляете всеми аккаунтами AdWords с помощью одного управляющего аккаунта верхнего уровня.
  • Вы только начинаете работу или хотите быстро приступить к работе.
  • Ваше приложение будет работать с одним набором аккаунтов AdWords с несколькими пользователями.
Веб-приложение
  • Вы хотите осуществлять аутентификацию, чтобы предоставлять разным пользователям разные права доступа к данным аккаунта AdWords.
  • Вам требуется создавать несколько наборов учетных данных, например для управления сторонними аккаунтами.
  • Вашему приложению требуются URL обратного вызова, не поддерживаемые в устанавливаемых приложениях.

Подробнее читайте в документации по устанавливаемым и веб-приложениям.

2. Создание идентификатора и секретного кода клиента

Определив тип приложения, нажмите на соответствующую вкладку ниже и следуйте инструкциям по созданию идентификатора и секретного кода клиента.

Устанавливаемое приложение
  1. Откройте страницу Учетные данные в Google Developers Console.
  2. В раскрывающемся меню проектов выберите Создать проект, затем укажите название проекта и при необходимости измените идентификатор проекта, после чего нажмите кнопку Создать.
  3. На странице "Учетные данные" выберите Создать учетные данные, а затем – Идентификатор клиента OAuth.
  4. Вам может быть предложено указать название продукта. В этом случае нажмите Настроить окно запроса доступа, укажите запрашиваемую информацию и нажмите Сохранить, чтобы вернуться к экрану "Учетные данные".
  5. В разделе Тип приложения выберите Другие типы и укажите необходимую информацию.
  6. Нажмите кнопку Создать.
  7. На появившейся странице скопируйте идентификатор и секретный ключ клиента – они понадобятся вам при настройке клиентской библиотеки.
Идентификатор и секретный ключ клиента
Веб-приложение
  1. Откройте страницу Учетные данные в Google Developers Console.
  2. В раскрывающемся меню проектов выберите Создать проект, затем укажите название проекта и при необходимости измените идентификатор проекта, после чего нажмите кнопку Создать.
  3. На странице "Учетные данные" выберите Создать учетные данные, а затем – Идентификатор клиента OAuth.
  4. Вам может быть предложено указать название продукта. В этом случае нажмите Настроить окно запроса доступа, укажите запрашиваемую информацию и нажмите Сохранить, чтобы вернуться к экрану "Учетные данные".
  5. В разделе Тип приложения выберите Веб-приложение. Следуя инструкциям, укажите источники JavaScript и/или URI перенаправления.
  6. Нажмите кнопку Создать.
  7. На появившейся странице скопируйте идентификатор и секретный ключ клиента – они понадобятся вам при настройке клиентской библиотеки.
Идентификатор и секретный ключ клиента

3. Настройка клиентской библиотеки

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

OAuth2 Playground

Альтернативный вариант создания учетных данных OAuth2 состоит в использовании OAuth2 Playground. В сочетании с Google Developers Console эта система позволяет самостоятельно создавать токены OAuth2.

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

Настройка

Как получить идентификатор и секретный ключ клиента

  1. Откройте страницу Учетные данные в Google Developers Console.
  2. В раскрывающемся меню выберите существующий проект или создайте новый.
  3. На странице "Учетные данные" выберите Создать учетные данные, а затем – Идентификатор клиента OAuth.
  4. В разделе Тип приложения выберите Веб-приложение.
  5. В разделе Разрешенные URI перенаправления добавьте следующую строку: https://developers.google.com/oauthplayground
  6. Нажмите кнопку Создать.
  7. Запишите идентификатор и секретный ключ клиента, указанные на появившейся странице. Они понадобятся вам на следующем шаге.

Как создать токены

  1. Перейдите в OAuth2 Playground по этой ссылке. При этом некоторые основные значения будут внесены автоматически.
  2. Нажмите на значок настроек в верхнем правом углу и установите флажок Use your own OAuth credentials (Использовать собственные учетные данные OAuth).
  3. Убедитесь в следующем:
    • В раскрывающемся списке OAuth flow (Процесс OAuth) выбрано Server-side (На стороне сервера).
    • В раскрывающемся списке Тип доступа выбрано Offline (Офлайн). Это обеспечивает получение токена обновления и токена доступа, а не только лишь токена доступа.
  4. Укажите ранее полученные идентификатор и секретный ключ клиента OAuth2. Настройки Oath2 Playground
  5. Укажите в нижней части раздела Step 1. Select & authorize APIs (Шаг 1. Выбор и авторизация API) приведенный ниже URL, после чего нажмите Authorize APIs (Авторизовать API).

    https://www.googleapis.com/auth/adwords

    Авторизация API

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

  7. Появится сообщение, о том, что вашему приложению нужен доступ к управлению кампаниями AdWords. Нажмите Accept (Принять), чтобы продолжить.

  8. На вкладке Step 2. Exchange authorization code for tokens (Шаг 2. Обмен кода авторизации на токены) должно появиться значение в поле Authorization code (Код авторизации). Нажмите кнопку Exchange authorization code for tokens (Обменять код авторизации на токены). Обмен кода авторизации на токены
  9. После этого должны появиться значения в полях Refresh token (Токен обновления) и Access token (Токен доступа). Возможно, вам потребуется повторно открыть раздел Step 2. Exchange authorization code for tokens (Шаг 2. Обмен кода авторизации на токены), чтобы увидеть эти значения. Токен обновления Oath2 Playground
  10. Скопируйте токен обновления в файл конфигурации для требуемой клиентской библиотеки. В нем также необходимо указать идентификатор и секретный ключ клиента. Чтобы задать параметры конфигурации для требуемой клиентской библиотеки, следуйте приведенным выше инструкциям.

Как убрать OAuth2 Playground из идентификатора клиента

Поскольку у вас уже есть токен обновления, вам больше не нужно использовать OAuth2 Playground в качестве разрешенного URI перенаправления. Чтобы удалить эту систему из списка, выполните следующие действия:

  1. Перейдите на страницу Учетные данные в Google Developers Console.
  2. В раскрывающемся меню выберите свой проект.
  3. На странице "Учетные данные" выберите название идентификатора клиента.
  4. Удалите https://developers.google.com/oauthplayground в поле Разрешенные URI перенаправления. Обратите внимание, что необходимо оставить хотя бы один URI перенаправления.
  5. Нажмите Сохранить.

Итак, у вас есть учетные данные OAuth. Теперь можно осуществлять запросы AdWords API и использовать примеры кода для требуемой клиентской библиотеки.

Сервисные аккаунты OAuth2

В этом разделе описывается порядок доступа к AdWords API с использованием сервисных аккаунтов.

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

AdWords API разрешает доступ сервисного аккаунта через домены Google Apps.

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

Применение сервисных аккаунтов дает два существенных преимущества:

  • Авторизация доступа приложения к API Google осуществляется на этапе настройки. Это позволяет избежать трудностей, связанных с необходимостью вмешательства пользователя или кеширования токенов в других потоках OAuth2.
  • Олицетворение других пользователей в приложении при необходимости осуществляется в рамках процесса утверждения OAuth2.

Альтернатива сервисным аккаунтам

Сервисные аккаунты широко применяются для обеспечения программного доступа к API по протоколу OAuth2 без вмешательства пользователя.

Однако настроить такие аккаунты для работы с AdWords API непросто. Более простой альтернативой является процесс устанавливаемого приложения OAuth2 с сохраняемым токеном обновления. Такой подход позволяет приложению в любой момент запрашивать новые токены доступа.

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

Требования

Настройка доступа для клиентского аккаунта

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

  1. Войдите в аккаунт Google Apps for Work и откройте Google Developers Console.
  2. В раскрывающемся меню проектов выберите Создать проект, затем укажите требуемую информацию и нажмите кнопку Создать. Новый проект появится в списке активных.
  3. В меню в левом верхнем углу выберите IAM и администрирование, а затем – Сервисные аккаунты в меню слева.
  4. Нажмите Создать сервисный аккаунт вверху страницы.
  5. Укажите название сервисного аккаунта.
  6. Установите флажок Создать новый закрытый ключ и выберите тип ключа: JSON или P12. В настоящее время ключи JSON поддерживаются клиентскими библиотеками Java, .NET, Ruby и PHP. В остальных клиентских библиотеках следует использовать ключи P12.
  7. Установите флажок Включить делегирование доступа к данным в домене Google Apps и укажите название продукта для окна запроса доступа.
  8. Нажмите кнопку Создать. Если выбран формат закрытого ключа P12, запустится скачивание файла ключа и появится окно с паролем для закрытого ключа. Сразу же сохраните этот пароль, поскольку он больше не будет показываться. Вам потребуется указать этот пароль для использования закрытого ключа P12.

    Если выбран формат закрытого ключа JSON, запустится скачивание файла ключа JSON.

    Сохраните файл ключа P12 или JSON в надежном месте, куда только у вас есть доступ.

  9. На странице Сервисные аккаунты появится новый сервисный аккаунт.

Проблемы безопасности

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

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

Как предоставить возможности олицетворения

Чтобы предоставить сервисному аккаунту возможности олицетворения, выполните следующие действия:

  1. Добавьте в домен Google Apps новый авторизованный клиент API. Для этого перейдите по следующей ссылке: https://admin.google.com/YOUR_DOMAIN/ManageOauthClients
  2. Добавьте новый авторизованный клиент API, указав в качестве его названия идентификатор из файла P12 или JSON, который был создан ранее, когда вы включили сервисный аккаунт для делегирования доступа к данным.
  3. Укажите следующую область действия API:

    https://www.googleapis.com/auth/adwords

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

Теперь вы можете осуществлять доступ к аккаунту AdWords с использованием сервисного аккаунта в рамках процесса утверждения OAuth2.

Настройка клиентской библиотеки

Выберите язык, чтобы просмотреть инструкции по настройке клиентской библиотеки.

Java

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

.NET

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

Python

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

PHP

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

Perl

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

Ruby

Ознакомьтесь с инструкциями по настройке клиентской библиотеки на портале GitHub.

Оптимизация запросов OAuth2

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

В этом разделе описывается, как оптимизировать управление учетными данными OAuth2, чтобы приложение более эффективно взаимодействовало с AdWords API.

Стратегии распределения учетных данных

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

Стратегия распределения учетных данных зависит от структуры приложения.

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

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

В приложении, которое одновременно является многопроцессным/распределенным и многопоточным, в каждом процессе необходимо совмещать обе стратегии.

Ниже описаны стратегии для аутентификации одного аккаунта AdWords, например управляющего аккаунта верхнего уровня в иерархии.

Затем описывается, как адаптировать эти стратегии для аутентификации нескольких аккаунтов AdWords.

Многопоточные приложения

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

Время выполнения

На этой схеме показаны потоки, передающие запросы в AdWords API во время выполнения. Применяется общий пул сеансов (пользователей). Обратите внимание, что каждый сеанс должен использовать один и тот же объект учетных данных. В ответ на каждый запрос API поток получает соответствующий сеанс (пользователя). Если требуется обновить токен доступа, это нужно делать синхронно, чтобы исключить состояние гонки. Другими словами, объект учетных данных должен быть потокобезопасным.

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

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

Многопроцессные и распределенные приложения

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

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

Обновление

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

Задача обновления

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

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

Хранилище данных

Хранилище данных используется для предоставления учетных данных разным процессам и серверам.

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

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

Помните, что учетные данные нужно хранить в защищенном виде.

При сохранении учетных данных необходимо сохранять свойство expiry_time (текущее время + expires_in) и refresh_token вместе со свойством access_token. Свойство expiry_time (окончание действия токена) рассчитывается по такой формуле: время запроса на обновление access_token + время expires_in (срок действия токена).

Пул серверов

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

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

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

Аутентификация нескольких аккаунтов

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

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

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

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

Принцип работы OAuth2

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

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

Область действия

Токен доступа может предоставлять разную степень доступа к данным. Изменяемый параметр scope (область действия) определяет набор ресурсов и операций, к которым токен предоставляет доступ. Во время запроса токена доступа ваше приложение отправляет в параметр scope одно или несколько значений.

Ниже представлены текущая и устаревшая область действия для AdWords API.

Область действия Назначение
https://www.googleapis.com/auth/adwords Доступ к AdWords API с правом на чтение и запись.
https://adwords.google.com/api/adwords/ Эта область действия устарела и в дальнейшем не должна использоваться для авторизации. Ранее авторизованные токены будут продолжать работать.

Автономный доступ

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

Перед запросом автономного доступа для веб-приложения убедитесь, что для параметра access_type выбрано значение offline. Более подробные сведения представлены в руководстве по Google OAuth2.

Устанавливаемые приложения используют автономный доступ по умолчанию.

Заголовок запроса HTTP

Заголовок HTTP в каждом запросе к серверу AdWords API должен включать токен доступа в такой форме:

Authorization: Bearer THE_ACCESS_TOKEN

Пример:

POST … HTTP/1.1
Host: …
Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
Content-Type: text/xml;charset=UTF-8
Content-Length: …

<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2001/12/soap-envelope">
  …
</soap:Envelope>

Токены доступа и обновления

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

Когда истекает срок действия токена доступа

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

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.