應用程式會使用 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 做為網址路徑的一部分傳遞。應用程式需要先取得使用者的客戶 ID,才能呼叫任何 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 個帳戶。如要瞭解操作方式,請參閱分頁結果。
機構通常只會有一個客戶帳戶,但大型機構可能會針對各部門使用不同的客戶帳戶。由於 IT 管理員可以成為不同客戶帳戶的成員,因此您的應用程式應協助使用者尋找及使用新的客戶帳戶。在應用程式中,使用 companyName
值為每個客戶帳戶加上標籤。
使用者
IT 管理員授權給您的應用程式代他們傳送的 API 要求。如要授權 API 要求,應用程式的使用者必須執行下列操作:
- 將 Google 帳戶與他們的電子郵件地址建立關聯。
- 使用同一個電子郵件地址加入客戶帳戶。
- 接受零接觸註冊機制客戶《服務條款》(ToS)。
為協助您為應用程式的使用者進行設定,請在自己的說明文件中重複使用 IT 管理員「開始使用」和「與 Google 帳戶建立關聯」一節的指南。
使用者管理
IT 管理員可在零接觸註冊入口網站中,管理客戶帳戶的使用者。客戶帳戶中的使用者俱有「擁有者」或「管理員」角色。這兩個角色對客戶 API 的存取權相同,但擁有者可以管理其他使用者。
接受《服務條款》
應用程式的使用者必須先接受最新的服務條款,才能授權 API 呼叫。如果 IT 管理員首次使用零接觸註冊機制,或當我們更新服務條款時,就會發生這種情況。如果使用者尚未接受最新的 ToS,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 金鑰儲存在檔案中,請將這類檔案存放在應用程式原始碼樹狀結構外的位置,以確保金鑰不會存在於原始碼控管系統中。假如您使用的是公開原始碼管理系統 (例如 GitHub),特別需要注意這點。
- 限制 API 金鑰只能用於有需要的 IP 位址、參照網址和行動應用程式
- 只要限制可使用各金鑰的 IP 位址、參照網址和行動應用程式,就能減少 API 金鑰遭駭時造成的影響。您可以透過 Google API 控制台指定主機和應用程式可以使用各種金鑰,方法是開啟「憑證」頁面,然後使用所需設定建立新的 API 金鑰,或是編輯 API 金鑰的設定。
- 刪除不需要的 API 金鑰
- 如要盡可能降低遭受攻擊的風險,請刪除任何不再需要的 API 金鑰。
- 定期重新產生 API 金鑰
- 您可以在 Google API 控制台中重新產生 API 金鑰,方法是開啟「憑證」頁面,選取 API 金鑰,然後按一下「重新產生金鑰」。然後更新應用程式,以使用新產生的金鑰。產生替代金鑰後,舊金鑰會繼續運作 24 小時。
- 請先檢查程式碼,再公開發布
- 在公開發布程式碼前,請確保程式碼不含 API 金鑰或任何其他私密資訊。