应用可使用 OAuth 授权调用零触摸注册客户 API。本文档介绍了该 API 对企业移动管理 (EMM) 提供商和企业 IT 开发者的授权。 阅读本文档后,您将了解如何向应用中的 API 请求授权,并向应用用户说明帐号要求。
授权快速入门
- 如需使用零触摸注册 API 和 OAuth 客户端密钥设置 Google Cloud Platform 项目,请运行此向导。
- 使用 Java、.NET 或 Python 构建快速入门示例代码。使用 Google 的 API 客户端库支持其他语言。
概览
- 一位或多位 IT 管理员是零触摸注册客户帐号的用户。
- IT 管理员使用 Google 帐号进行身份验证。
- 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 请求授权,应用用户需要执行以下操作:
- 将 Google 帐号与其电子邮件地址相关联。
- 使用同一电子邮件地址加入客户帐号。
- 接受零触摸注册客户的服务条款 (ToS)。
为帮助应用的用户完成设置,请重复使用我们面向 IT 管理员提供的使用入门指南和您自己文档中的关联 Google 帐号。
用户管理
IT 管理员在零触摸注册门户中管理其客户帐号的用户。客户帐号中的用户具有所有者或管理员角色。这两个角色对客户 API 拥有相同的访问权限,但所有者可以管理其他用户。
服务条款接受
应用用户必须先接受最新的服务条款 (TOS),然后才能授权 API 调用。当 IT 管理员首次使用零触摸注册或我们更新服务条款时,就会发生这种情况。如果用户尚未接受最新的服务条款,该 API 会返回 HTTP 403 Forbidden
状态代码,并且响应正文会包含 TosError
。
当用户登录时,该门户会自动提示用户接受最新的服务条款。如需查看您的应用可包含的建议方法,请阅读 EMM 集成指南中的处理服务条款。
向您的应用添加授权
您的应用向客户 API 发送的每个请求都必须包含授权令牌。Google 也可通过此令牌识别您的应用。由于客户 API 会访问用户数据,因此必须由数据所有者进行授权。您的应用使用 OAuth 2.0 协议将 API 授权委托给 IT 管理员。
操作说明
我们为 Java、.NET 和 Python 应用提供了快速入门指南。如果您使用的是其他语言,请按照以下两个步骤为您的应用设置授权。
如需详细了解授权,请参阅使用 OAuth 2.0 访问 Google API。
授权范围
在您的应用中使用 API 授权范围 https://www.googleapis.com/auth/androidworkzerotouchemm
来请求 OAuth 2.0 访问令牌。
范围参数用于控制访问令牌允许调用的一组资源和操作。访问令牌仅对令牌请求范围中描述的一组操作和资源有效。该 API 涵盖上述单个零触摸注册范围的所有方法和资源。
如需查看用于 Google API 客户端库的零触摸注册范围示例,请参阅 Java、.NET 和 Python 快速入门。如需详细了解如何使用 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 密钥或任何其他私密信息。