Авторизация

Приложения авторизуют вызовы customer API автоматической настройки с помощью OAuth. В этом документе объясняется, как работает авторизация API для поставщиков услуг по управлению мобильной инфраструктурой предприятия (EMM) и разработчиков корпоративных ИТ-решений. Прочитав этот документ, вы узнаете, как авторизовать запросы к API в своем приложении и объяснить пользователям требования к аккаунту.

Краткое руководство по авторизации

• Чтобы настроить проект Google Cloud Platform с помощью API автоматической настройки и секретных кодов клиента OAuth, запустите этот мастер.
• Создайте образец кода для быстрого запуска на Java, .NET или Python. Чтобы использовать другие языки, воспользуйтесь клиентскими библиотеками API Google.

Обзор

1. Один или несколько системных администраторов являются пользователями в аккаунте клиента с автоматической настройкой.
2. Для аутентификации администраторы используют аккаунт Google.
3. Запросы к API передают токен OAuth2 для авторизации запросов к API от имени системного администратора.

Аккаунты клиентов

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

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

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

Java

AndroidProvisioningPartner.Customers.List accountRequest = service.customers().list();
accountRequest.setPageSize(100);
CustomerListCustomersResponse accountResponse = accountRequest.execute();

List<Company> customers = accountResponse.getCustomers();
if (customers == null || customers.isEmpty()) {
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    System.out.println("No zero-touch enrollment account found.");
} else {
    // Print the customers in this page.
    for (Company customer : customers) {
        System.out.format("%s\tcustomers/%d\n",
              customer.getCompanyName(), customer.getCompanyId());
    }
}

.NET

CustomersResource.ListRequest accountRequest = service.Customers.List();
accountRequest.PageSize = 100;
CustomerListCustomersResponse accountResponse = accountRequest.Execute();
IList<Company> customers = accountResponse.Customers ?? new List<Company>();
if (customers.Count == 0)
{
    // No accounts found for the user. Confirm the Google Account
    // that authorizes the request can access the zero-touch portal.
    Console.WriteLine("No zero-touch enrollment account found.");
}
foreach (Company customer in customers)
{
    Console.WriteLine("{0}\tcustomers/{1}",
                      customer.CompanyName,
                      customer.CompanyId);
}

Python

response = service.customers().list(pageSize=100).execute()
if 'customers' not in response:
  # No accounts found for the user. Confirm the Google Account
  # that authorizes the request can access the zero-touch portal.
  print('No zero-touch enrollment account found.')
  response['customers'] = []

for customer in response['customers']:
  print('{0}\tcustomers/{1}'.format(
      customer['companyName'], customer['companyId']))

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

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

Пользователи

Системные администраторы авторизуют запросы к API, которые ваше приложение отправляет от их имени. Чтобы авторизовать запросы к API, пользователю приложения нужно сделать следующее:

1. Связать аккаунт Google с адресом электронной почты.
2. Присоединитесь к аккаунту клиента, используя тот же адрес электронной почты.
3. Примите Условия использования автоматической настройки.

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

Управление доступом

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

Принятие Условий использования

Чтобы пользователи вашего приложения могли авторизовать вызовы API, они должны принять последнюю версию Условий использования. Это происходит, когда администраторы впервые используют автоматическую настройку или когда мы обновляем Условия использования. Если пользователь не принял последнюю версию Условий использования, API возвращает код статуса HTTP 403 Forbidden, а тело ответа содержит TosError.

При входе на портал пользователям автоматически предлагается принять последнюю версию Условий использования. Рекомендуемые подходы к реализации этой функции описаны в разделе Обработка Условий использования руководства по интеграции EMM.

Добавьте авторизацию в приложение

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

Важно! Чтобы упростить настройку авторизации и аутентификации, Google предоставляет клиентские библиотеки, которые позволяют уменьшить объем кода, который вам нужно написать, и сделать код более надежным. Для вызова Customer API рекомендуем использовать клиентскую библиотеку. Ознакомьтесь с краткими руководствами по Java, .NET и Python.

Инструкции

Мы предлагаем краткие руководства для приложений на Java, .NET и Python. Если вы используете другой язык, выполните два шага ниже, чтобы настроить авторизацию для приложения.

Шаг 1. Включите API автоматической настройки

1. Используйте этот мастер, чтобы создать или выбрать проект в Google Developers Console и автоматически включить API. Нажмите Продолжить, а затем – Перейти к учетным данным.
2. Нажмите Отмена в окне "Создать учетные данные".
3. В верхней части страницы выберите вкладку Окно запроса доступа OAuth. Выберите Адрес электронной почты, введите Название товара, если оно ещё не указано, и нажмите кнопку Сохранить.
4. Перейдите на вкладку Учетные данные, нажмите кнопку Создать учетные данные и выберите Идентификатор клиента OAuth.
5. Выберите тип приложения.
6. В поле Name (Название) укажите название приложения.
7. Нажмите Создать.
8. Нажмите Скачать JSON.
9. Переместите файл в рабочий каталог и переименуйте его в client_secret.json.

Шаг 2. Установите клиентскую библиотеку

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

1. Перейдите на страницу Клиентские библиотеки Google API и выберите нужный язык из списка поддерживаемых.
2. Следуйте инструкциям по установке клиентской библиотеки.

Подробнее об использовании OAuth 2.0 для доступа к API Google…

Области авторизации

Чтобы запросить токен доступа OAuth 2.0, используйте в приложении область авторизации API https://www.googleapis.com/auth/androidworkzerotouchemm.

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

Пример использования области действия автоматической настройки с клиентской библиотекой API Google можно найти в кратких руководствах по Java, .NET и Python. Подробнее об использовании OAuth 2.0 для доступа к API Google…

Рекомендации по работе с ключами API

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

Не встраивайте ключи API непосредственно в код

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

Не храните ключи API в файлах дерева кода приложения

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

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

Ограничив IP-адреса, URL перехода и мобильные приложения, которые могут использовать каждый ключ, вы можете снизить последствия компрометации ключа API. Вы можете указать хосты и приложения, которые могут использовать каждый ключ из Google API Console. Для этого откройте страницу учетных данных и создайте новый ключ API с нужными настройками или измените настройки существующего ключа API.

Удалите ненужные ключи API

Чтобы минимизировать риск атаки, удалите все ключи API, которые вам больше не нужны.

Периодически генерируйте ключи API заново

Вы можете повторно сгенерировать ключи API в Google API Console. Для этого откройте страницу учетных данных, выберите ключ API и нажмите Повторно сгенерировать ключ. Затем обновите приложения, чтобы использовать новые ключи. Старые ключи будут работать ещё 24 часа после создания новых.

Проверяйте код перед публикацией

Прежде чем публиковать код, убедитесь, что в нем нет ключей API и другой конфиденциальной информации.