アプリは OAuth を使用して、ゼロタッチ登録の Customer API の呼び出しを承認します。このドキュメントでは、企業向けモバイル管理(EMM)プロバイダと企業の IT デベロッパー向けの API 認可について説明します。このドキュメントを読むと、アプリで API リクエストを承認する方法と、アプリのユーザーにアカウント要件を説明する方法を理解できます。
認可のクイックスタート
- ゼロタッチ登録 API と OAuth クライアント シークレットを使用して Google Cloud Platform プロジェクトを設定するには、このウィザードを実行します。
- Java、.NET、Python のクイックスタート サンプルコードをビルドします。他の言語をサポートするには、Google の API クライアント ライブラリを使用します。
概要
- 1 人以上の IT 管理者がゼロタッチ登録のお客様アカウントのユーザーです。
- IT 管理者は Google アカウントを使用して自身の認証を行います。
- API リクエストは OAuth2 トークンを渡し、IT 管理者に代わって API リクエストを承認します。
顧客アカウント
組織の構成、デバイス、(IT 管理者)ユーザーは顧客アカウントに属します。顧客アカウントはグループと類似しており、個々のユーザーではありません。販売パートナーは、組織がゼロタッチ登録用のデバイスを初めて購入したときにお客様を設定します。IT 管理者は、ゼロタッチ登録ポータルを使用して組織内の他のユーザーを管理します。
この API では、数値のお客様 ID を使用してアカウントを識別します。API メソッドを呼び出すときは、URL パスの一部としてお客様 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 個のアカウントしか出力されないため、アプリではアカウントの結果ページに移動する必要があります。方法については、ページングされた結果をご覧ください。
通常、1 つの組織に 1 つのお客様アカウントがありますが、大規模な組織では部門ごとに個別のお客様アカウントを使用する場合があります。IT 管理者は異なる顧客アカウントのメンバーになる可能性があるため、アプリではユーザーが新規顧客アカウントを見つけて使用できるようにする必要があります。アプリで、companyName
値を使用して、各お客様のアカウントにラベルを付けます。
ユーザー数
IT 管理者は、アプリがユーザーに代わって送信する API リクエストを承認します。API リクエストを承認するには、アプリのユーザーが次の操作を行う必要があります。
- Google アカウントとメールアドレスを関連付けます。
- 同じメールアドレスを使用してお客様のアカウントに参加します。
- お客様のゼロタッチ登録の利用規約に同意します。
ユーザーがアプリを設定しやすくするには、スタートガイドと Google アカウントの関連付けにある IT 管理者向けのガイダンスを独自のドキュメントで再利用してください。
ユーザー管理
IT 管理者は、ゼロタッチ登録ポータルで顧客アカウントのユーザーを管理します。お客様アカウントのユーザーには、オーナーまたは管理者のロールが付与されています。どちらのロールでも顧客の API に対して同じアクセス権が付与されますが、オーナーは他のユーザーを管理できます。
利用規約への同意
アプリのユーザーは、API 呼び出しを承認する前に、最新の利用規約に同意する必要があります。これは、IT 管理者が初めてゼロタッチ登録を使用するとき、または Google が ToS を更新したときに発生します。ユーザーが最新の利用規約に同意していない場合、API は HTTP 403 Forbidden
ステータス コードを返し、レスポンスの本文には TosError
が含まれます。
ユーザーがログインするときに、最新の利用規約への同意を求めるプロンプトが自動的に表示されます。アプリに組み込むためのおすすめのアプローチについては、EMM 統合ガイドの利用規約に対応するをご覧ください。
アプリに認証を追加する
アプリが顧客の API に送信するすべてのリクエストには、認証トークンが含まれている必要があります。このトークンは Google でアプリケーションを識別するためにも使用されます。Customer API はユーザーデータにアクセスするため、データの所有者が承認する必要があります。アプリが OAuth 2.0 プロトコルを使用して IT 管理者に API 認証を委任する。
手順
Java、.NET、Python アプリのクイックスタート ガイドを提供しています。別の言語を使用している場合は、次の 2 つの手順でアプリの認証を設定します。
認証について詳しくは、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 キーをファイルに保存する場合は、キーがソースコード管理システムに保存されないように、アプリケーションのソースツリーの外部にファイルを保存します。GitHub のような公開ソースコード管理システムを使用する場合、これは特に重要です。
- API キーは、IP アドレス、参照 URL、およびその権限を必要とするモバイルアプリのみが使用できるように制限します。
- 各キーを使用できる IP アドレス、参照 URL、モバイルアプリを制限すると、API キーの不正使用の影響を軽減できます。Google API Console から各キーを使用できるホストとアプリを指定するには、[認証情報] ページを開き、目的の設定で新しい API キーを作成するか、API キーの設定を編集します。
- 不要な API キーの削除
- 攻撃を受ける可能性を最小限に抑えるため、不要になった API キーをすべて削除してください。
- API キーを定期的に再生成する
- Google API Console から API キーを再生成するには、[認証情報] ページを開き、API キーを選択して、各キーの [キーを再生成] をクリックします。次に、新しく生成されたキーを使用するようにアプリケーションを更新します。古い鍵は、代替の鍵を生成した後 24 時間は引き続き機能します。
- 公開前にコードを確認する
- コードを公開する前に、コードに API キーやその他の個人情報が含まれていないことを確認してください。