授权

应用可使用 OAuth 授权调用零触摸注册客户 API。本文档介绍了该 API 对企业移动管理 (EMM) 提供商和企业 IT 开发者的授权。 阅读本文档后,您将了解如何向应用中的 API 请求授权,并向应用用户说明帐号要求。

授权快速入门

  • 如需使用零触摸注册 API 和 OAuth 客户端密钥设置 Google Cloud Platform 项目,请运行此向导
  • 使用 Java.NETPython 构建快速入门示例代码。使用 Google 的 API 客户端库支持其他语言。

概览

设备和客户资源关系

  1. 一位或多位 IT 管理员是零触摸注册客户帐号的用户。
  2. IT 管理员使用 Google 帐号进行身份验证。
  3. API 请求会传递 OAuth2 令牌,以代表 IT 管理员为 API 请求授权。

客户账号

组织的配置、设备和(IT 管理员)用户属于客户帐号。客户帐号类似于群组,而不是单个用户。组织在首次购买设备以进行零触摸注册时,转销商会对客户进行设置。IT 管理员使用零触摸注册门户管理组织中的其他用户。

该 API 使用数字格式的客户 ID 来标识帐号。调用 API 方法时,您可以将客户 ID 作为网址路径的一部分进行传递。您的应用在调用任何 API 方法之前都需要获取用户的客户 ID。

以下示例展示了如何获取授权 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 个帐号。如需了解如何执行此操作,请参阅分页结果

一个组织通常有一个客户帐号,但较大的组织可能会为每个部门使用单独的客户帐号。由于 IT 管理员可以是不同客户帐号的成员,因此您的应用应帮助用户查找和使用新的客户帐号。在您的应用中,使用 companyName 值标记每个客户帐号。

用户

IT 管理员负责授权您的应用代表他们发送的 API 请求。如需向 API 请求授权,应用用户需要执行以下操作:

  1. 将 Google 帐号与其电子邮件地址相关联。
  2. 使用同一电子邮件地址加入客户帐号。
  3. 接受零触摸注册客户的服务条款 (ToS)。

为帮助应用的用户完成设置,请重复使用我们面向 IT 管理员提供的使用入门指南和您自己文档中的关联 Google 帐号

用户管理

IT 管理员在零触摸注册门户中管理其客户帐号的用户。客户帐号中的用户具有所有者管理员角色。这两个角色对客户 API 拥有相同的访问权限,但所有者可以管理其他用户。

服务条款接受

应用用户必须先接受最新的服务条款 (TOS),然后才能授权 API 调用。当 IT 管理员首次使用零触摸注册或我们更新服务条款时,就会发生这种情况。如果用户尚未接受最新的服务条款,该 API 会返回 HTTP 403 Forbidden 状态代码,并且响应正文会包含 TosError

当用户登录时,该门户会自动提示用户接受最新的服务条款。如需查看您的应用可包含的建议方法,请阅读 EMM 集成指南中的处理服务条款

向您的应用添加授权

您的应用向客户 API 发送的每个请求都必须包含授权令牌。Google 也可通过此令牌识别您的应用。由于客户 API 会访问用户数据,因此必须由数据所有者进行授权。您的应用使用 OAuth 2.0 协议将 API 授权委托给 IT 管理员。

操作说明

我们为 Java.NETPython 应用提供了快速入门指南。如果您使用的是其他语言,请按照以下两个步骤为您的应用设置授权。

如需详细了解授权,请参阅使用 OAuth 2.0 访问 Google API

授权范围

在您的应用中使用 API 授权范围 https://www.googleapis.com/auth/androidworkzerotouchemm 来请求 OAuth 2.0 访问令牌。

范围参数用于控制访问令牌允许调用的一组资源和操作。访问令牌仅对令牌请求范围中描述的一组操作和资源有效。该 API 涵盖上述单个零触摸注册范围的所有方法和资源。

如需查看用于 Google API 客户端库的零触摸注册范围示例,请参阅 Java.NETPython 快速入门。如需详细了解如何使用 Google API 范围,请参阅使用 OAuth 2.0 访问 Google API

API 密钥最佳实践

在您的应用中使用 API 密钥时,请注意确保 API 密钥的安全。 公开泄露凭据可能会导致您的帐号被盗用,这可能会使您的帐号产生预料之外的费用。为保障 API 密钥的安全,请遵循以下最佳实践:

不要直接在代码中嵌入 API 密钥
嵌入代码中的 API 密钥可能会被意外公开。例如,如果您忘记从共享的代码中移除密钥。您可以将 API 密钥存储在环境变量或应用源代码树之外的文件中,而不是将 API 密钥嵌入到应用中。
不要将 API 密钥存储在应用源代码树内的文件中
如果您将 API 密钥存储在文件中,请将文件保留在应用的源代码树之外,这有助于确保密钥最终不会进入源代码控制系统。如果您使用公共源代码管理系统(如 GitHub),这种做法尤为重要。
将您的 API 密钥限制为仅供 IP 地址、引荐来源网址以及需要它们的移动应用使用
通过限制可以使用每个密钥的 IP 地址、引荐来源网址和移动应用,您可以降低 API 密钥被盗用时造成的影响。您可以从 Google API 控制台指定可以使用每个密钥的主机和应用,方法是打开“凭据”页面,然后使用所需的设置创建新的 API 密钥,或者修改 API 密钥的设置。
删除不需要的 API 密钥
为尽可能降低遭到攻击的风险,请删除您不再需要的所有 API 密钥。
定期重新生成 API 密钥
您可以从 Google API 控制台重新生成 API 密钥,具体方法是打开“凭据”页面,选择一个 API 密钥,然后点击每个密钥对应的重新生成密钥。然后,更新您的应用以使用新生成的密钥。生成替换密钥后,旧密钥将在 24 小时内继续有效。
在公开发布之前检查您的代码
在公开发布代码之前,请确保您的代码不包含 API 密钥或任何其他私密信息。