サーバー間アプリケーションに OAuth 2.0 を使用する

<0x0 詳細については、Google Cloud Platform ドキュメントの認証の概要をご覧ください。

Google OAuth 2.0 システムは、ウェブ アプリケーションと Google サービス間など、サーバー間のインタラクションをサポートしています。このシナリオでは、個々のエンドユーザーではなく、アプリケーションに属するアカウントであるサービス アカウントが必要です。サービス アカウントの代わりにアプリケーションによって Google API が呼び出されるため、ユーザーが直接関与することはありません。このシナリオは、「2 レッグ OAuth」または「2LO」と呼ばれることがあります。（関連用語の「3-legged OAuth」は、アプリケーションがエンドユーザーに代わって Google API を呼び出すシナリオを指します。このシナリオでは、ユーザーの同意が必要になることがあります）。

通常、アプリケーションが Google API を使用してユーザーのデータではなく独自のデータを操作する場合、アプリケーションはサービス アカウントを使用します。たとえば、データの永続性に Google Cloud Datastore を使用するアプリケーションは、サービス アカウントを使用して Google Cloud Datastore API への呼び出しを認証します。

Google Workspace ドメイン管理者は、ドメイン内のユーザーに代わってユーザーデータにアクセスするサービス アカウントにドメイン全体の権限を付与することもできます。

このドキュメントでは、Google API クライアント ライブラリ（推奨）または HTTP を使用して、アプリケーションがサーバー間の OAuth 2.0 フローを完了する方法について説明します。

一部の Google API では、OAuth 2.0 ではなく署名付き JWT を使用して認証済み API 呼び出しを行うことができます。これにより、ネットワーク リクエストを節約できます。付録: OAuth を使用しないサービス アカウントの認可をご覧ください。

概要

サーバー間のインタラクションをサポートするには、まず API Consoleでプロジェクトのサービス アカウントを作成します。Google Workspace アカウントのユーザーのユーザーデータにアクセスする場合は、サービス アカウントにドメイン全体のアクセス権を委任します。

次に、アプリケーションは、サービス アカウントの認証情報を使用して OAuth 2.0 認証サーバーからアクセス トークンをリクエストし、承認された API 呼び出しを行う準備をします。

最後に、アプリケーションはアクセス トークンを使用して Google API を呼び出すことができます。

推奨事項: アプリケーションは、使用する言語の Google API クライアント ライブラリを使用するか、HTTP を使用して OAuth 2.0 システムと直接やり取りすることで、これらのタスクを完了できます。ただし、サーバー間認証のメカニズムでは、アプリケーションで JSON ウェブトークン（JWT）を作成して暗号で署名する必要があります。重大なエラーが発生しやすく、アプリケーションのセキュリティに深刻な影響を与える可能性があります。

そのため、アプリケーション コードとは別に暗号化を抽象化するライブラリ（Google API クライアント ライブラリなど）の使用を強くおすすめします。

サービス アカウントの作成

サービス アカウントの認証情報には、一意の生成されたメールアドレスと、少なくとも 1 つの公開鍵/秘密鍵のペアが含まれます。ドメイン全体の委任が有効になっている場合、クライアント ID もサービス アカウントの認証情報の一部になります。

アプリケーションが Google App Engine で実行されている場合、プロジェクトの作成時にサービス アカウントが自動的に設定されます。

アプリケーションが Google Compute Engine で実行されている場合、プロジェクトの作成時にサービス アカウントも自動的に設定されますが、Google Compute Engine インスタンスの作成時に、アプリケーションがアクセスする必要があるスコープを指定する必要があります。詳細については、サービス アカウントを使用するようにインスタンスを準備するをご覧ください。

アプリケーションが Google App Engine または Google Compute Engine で実行されていない場合は、 Google API Consoleでこれらの認証情報を取得する必要があります。サービス アカウントの認証情報を生成するか、すでに生成した公開認証情報を表示するには、次の操作を行います。

まず、サービス アカウントを作成します。

1. Service accounts page開きます。
2. If prompted, select a project, or create a new one.
3. [サービス アカウントの作成] をクリックします。
4. [サービス アカウントの詳細] で、サービス アカウントの名前、ID、説明を入力し、[作成して続行] をクリックします。
5. オプション: [ Grant this service account access to project ] で、サービス アカウントに付与する IAM ロールを選択します。
6. [続行]をクリックします。
7. オプション: [ユーザーにこのサービス アカウントへのアクセスを許可する] で、サービス アカウントの使用と管理を許可するユーザーまたはグループを追加します。
8. [完了]をクリックします。

次に、サービス アカウント キーを作成します。

1. 作成したサービス アカウントのメール アドレスをクリックします。
2. [キー] タブをクリックします。
3. [キーの追加]ドロップダウン リストで、[新しいキーの作成]を選択します。
4. [作成]をクリックします。

新しい公開鍵と秘密鍵のペアが生成され、マシンにダウンロードされます。秘密鍵の唯一のコピーとして機能します。あなたはそれを安全に保管する責任があります。このキー ペアを紛失した場合は、新しいキー ペアを生成する必要があります。

API Console にはいつでも戻って、メールアドレス、公開鍵のフィンガープリントなどの情報を表示したり、公開鍵と秘密鍵のペアを追加で生成したりできます。 API Consoleのサービス アカウント認証情報の詳細については、 API Consoleヘルプファイルのサービス アカウントをご覧ください。

サービス アカウントのメールアドレスをメモし、サービス アカウントの秘密鍵ファイルをアプリケーションからアクセスできる場所に保存します。アプリケーションが承認済み API 呼び出しを行うには、これらのキーが必要です。

注: 開発環境と本番環境の両方で、秘密鍵を安全に保管、管理する必要があります。Google は秘密鍵のコピーを保持せず、公開鍵のみを保持します。詳しくは、OAuth 2.0 ポリシーのクライアント認証情報を安全に処理するセクションをご覧ください。

サービス アカウントにドメイン全体の権限を委任する

組織の Workspace 管理者は、Google Workspace アカウントを使用して、Google Workspace ドメインのユーザーに代わって Workspace ユーザーデータにアクセスするアプリケーションを認可できます。たとえば、Google Calendar API を使用して Google Workspace ドメイン内のすべてのユーザーのカレンダーに予定を追加するアプリケーションの場合、ユーザーの代わりにサービス アカウントを使用して Google Calendar API にアクセスします。ドメイン内でユーザーに代わってデータにアクセスすることをサービス アカウントに承認することは、サービス アカウントへの「ドメイン全体の権限の委任」と呼ばれることもあります。

注: Google Workspace Marketplace を使用してドメインにアプリケーションをインストールすると、インストール時に必要な権限がアプリケーションに自動的に付与されます。アプリケーションが使用するサービス アカウントを手動で承認する必要はありません。

注: Google Workspace ドメインから実行されるアプリケーションでサービス アカウントを使用できますが、サービス アカウントは Google Workspace アカウントのメンバーではなく、Google Workspace 管理者が設定したドメイン ポリシーの対象にもなりません。たとえば、Google Workspace 管理コンソールで設定された、Google Workspace エンドユーザーがドメイン外でドキュメントを共有する機能を制限するポリシーは、サービス アカウントには適用されません。

サービス アカウントにドメイン全体の権限を委任するには、Google Workspace ドメインの特権管理者が次の手順を完了する必要があります。

1. Google Workspace ドメインの 管理コンソールから、メインメニュー > [セキュリティ] > [アクセスとデータ管理] > [API の制御] に移動します。
2. [ドメイン全体の委任] ペインで、[ドメイン全体の委任を管理] を選択します。
3. [新しく追加] をクリックします。
4. [クライアント ID] フィールドに、サービス アカウントのクライアント ID を入力します。サービス アカウントのクライアント ID は Service accounts pageで確認できます。
5. [OAuth scopes (comma-delimited)] フィールドに、アプリケーションにアクセス権を付与するスコープのリストを入力します。たとえば、Google Drive API と Google Calendar API にドメイン全体でフルアクセスできる必要がある場合は、https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar と入力します。
6. [承認] をクリックします。

これで、アプリケーションは Google Workspace ドメインのユーザーとして API 呼び出しを行う権限（ユーザーに「成り代わる」権限）を持つようになりました。これらの委任された API 呼び出しを行う準備をする際に、権限を借用するユーザーを明示的に指定します。

注: 通常、クライアント ID の追加後、数分で権限借用アクセス権が付与されますが、Google アカウントのすべてのユーザーに反映されるまでに最長で 24 時間かかる場合があります。

委任された API 呼び出しを行う準備

Java

API Consoleからクライアント メールアドレスと秘密鍵を取得したら、Java 用 Google 認証ライブラリを使用して、サービス アカウントの認証情報とアプリケーションがアクセスする必要があるスコープから GoogleCredentials オブジェクトを作成します。次に例を示します。

import com.google.auth.oauth2.GoogleCredentials;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Google Cloud Platform でアプリを開発している場合は、代わりにアプリケーションのデフォルト認証情報を使用すると、プロセスを簡素化できます。

ドメイン全体の権限を委任する

サービス アカウントにドメイン全体のアクセス権を委任し、ユーザー アカウントを偽装する場合は、GoogleCredentials オブジェクトの createDelegated メソッドを使用して、ユーザー アカウントのメールアドレスを指定します。例:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

上記のコードでは、GoogleCredentials オブジェクトを使用して createDelegated() メソッドを呼び出しています。createDelegated() メソッドの引数は、Workspace アカウントに属するユーザーである必要があります。リクエストを行うコードは、この認証情報を使用してサービス アカウントで Google API を呼び出します。

Python

API Consoleからクライアント メールアドレスと秘密鍵を取得したら、Python 用 Google API クライアント ライブラリを使用して、次の手順を完了します。

1. サービス アカウントの認証情報と、アプリケーションがアクセスする必要があるスコープから Credentials オブジェクトを作成します。次に例を示します。

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Google Cloud Platform でアプリを開発している場合は、代わりにアプリケーションのデフォルト認証情報を使用すると、プロセスを簡素化できます。

2. ドメイン全体の権限を委任する

   サービス アカウントにドメイン全体のアクセス権を委任し、ユーザー アカウントの権限を借用する場合は、既存の ServiceAccountCredentials オブジェクトの with_subject メソッドを使用します。次に例を示します。

   delegated_credentials = credentials.with_subject('[e-mail]')

Credentials オブジェクトを使用して、アプリケーションで Google API を呼び出します。

HTTP/REST

推奨事項: アプリケーションは HTTP を使用して OAuth 2.0 システムと直接やり取りすることでこれらのタスクを完了できますが、サーバー間認証のメカニズムでは、アプリケーションで JSON ウェブトークン（JWT）を作成して暗号で署名する必要があります。重大なエラーが発生しやすく、アプリケーションのセキュリティに深刻な影響を及ぼす可能性があります。

そのため、アプリケーション コードとは別に暗号化を抽象化するライブラリ（Google API クライアント ライブラリなど）の使用を強くおすすめします。

API Consoleからクライアント ID と秘密鍵を取得したら、アプリケーションで次の手順を完了する必要があります。

1. ヘッダー、クレームセット、署名を含む JSON Web Token（JWT、「ジョット」と発音）を作成します。
2. Google OAuth 2.0 認証サーバーからアクセス トークンをリクエストします。
3. 認可サーバーから返された JSON レスポンスを処理します。

以降のセクションでは、これらの手順を完了する方法について説明します。

レスポンスにアクセス トークンが含まれている場合は、アクセス トークンを使用して Google API を呼び出すことができます。（レスポンスにアクセス トークンが含まれていない場合は、JWT とトークン リクエストが正しく作成されていないか、サービス アカウントにリクエストされたスコープにアクセスする権限がない可能性があります）。

アクセス トークンの有効期限が切れると、アプリケーションは別の JWT を生成して署名し、別のアクセス トークンをリクエストします。

このセクションの残りの部分では、JWT の作成、JWT の署名、アクセス トークン リクエストの作成、レスポンスの処理について詳しく説明します。

JWT の作成

JWT は、ヘッダー、クレームセット、署名の 3 つの部分で構成されています。ヘッダーとクレームセットは JSON オブジェクトです。これらの JSON オブジェクトは UTF-8 バイトにシリアル化され、Base64url エンコードを使用してエンコードされます。このエンコードは、エンコード オペレーションの繰り返しによるエンコードの変更に対する復元力を提供します。ヘッダー、クレームセット、署名はピリオド（.）で連結されます。

JWT は次のように構成されています。

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

署名のベース文字列は次のとおりです。

{Base64url encoded header}.{Base64url encoded claim set}

JWT ヘッダーの作成

ヘッダーは、署名アルゴリズム、アサーションの形式、JWT の署名に使用された [サービス アカウント キーのキー ID](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) を示す 3 つのフィールドで構成されます。アルゴリズムと形式は必須で、各フィールドには 1 つの値のみが含まれます。アルゴリズムと形式が追加されると、このヘッダーもそれに応じて変更されます。鍵 ID は省略可能です。誤った鍵 ID が指定された場合、GCP はサービス アカウントに関連付けられているすべての鍵を試してトークンを検証し、有効な鍵が見つからない場合はトークンを拒否します。Google は、今後、キー ID が正しくないトークンを拒否する権利を有します。

サービス アカウントは、RSA SHA-256 アルゴリズムと JWT トークン形式に依存しています。その結果、ヘッダーの JSON 表現は次のようになります。

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

この Base64url 表現は次のとおりです。

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

JWT クレーム セットの作成

JWT クレーム セットには、リクエストされた権限（スコープ）、トークンのターゲット、発行者、トークンの発行時刻、トークンの有効期間など、JWT に関する情報が含まれています。ほとんどのフィールドは必須です。JWT ヘッダーと同様に、JWT クレーム セットは JSON オブジェクトであり、署名の計算に使用されます。

必須クレーム

JWT クレーム セットに必要なクレームを以下に示します。これらは、クレーム セット内で任意の順序で表示されることがあります。

名前	説明
iss	サービス アカウントのメールアドレス。
scope	アプリケーションがリクエストする権限のスペース区切りリスト。
aud	アサーションの対象となるターゲットの記述子。アクセス トークン リクエストを行う場合、この値は常に https://oauth2.googleapis.com/token です。
exp	アサーションの有効期限。1970 年 1 月 1 日 00:00:00 UTC からの経過秒数で指定します。この値は、発行時刻から最大 1 時間です。
iat	アサーションが発行された時刻。1970 年 1 月 1 日 00:00:00 UTC からの経過秒数として指定します。

JWT クレーム セットの必須フィールドの JSON 表現は次のとおりです。

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

その他の申し立て

企業によっては、アプリケーションがドメイン全体の委任を使用して、組織内の特定のユーザーに代わって操作を行うことがあります。このタイプのユーザーの権限借用を実行する権限は、アプリケーションがユーザーの権限を借用する前に付与する必要があります。通常、この権限は特権管理者が処理します。詳細については、API アクセスをドメイン全体の委任で制御するをご覧ください。

アプリケーションにリソースへの委任アクセスを許可するアクセス トークンを取得するには、JWT クレーム セットにユーザーのメールアドレスを sub フィールドの値として含めます。

名前	説明
sub	アプリケーションが委任されたアクセス権をリクエストしているユーザーのメールアドレス。

ユーザーを偽装する権限がアプリケーションにない場合、sub フィールドを含むアクセス トークン リクエストに対するレスポンスはエラーになります。

sub フィールドを含む JWT クレーム セットの例を次に示します。

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

JWT クレームセットのエンコード

JWT ヘッダーと同様に、JWT クレームセットは UTF-8 にシリアル化され、Base64url セーフでエンコードされる必要があります。以下に、JWT クレーム セットの JSON 表現の例を示します。

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

署名の計算

JSON Web Signature（JWS）は、JWT の署名生成のメカニズムを規定する仕様です。署名の入力は、次のコンテンツのバイト配列です。

{Base64url encoded header}.{Base64url encoded claim set}

署名の計算時には、JWT ヘッダーの署名アルゴリズムを使用する必要があります。Google OAuth 2.0 認証サーバーでサポートされている署名アルゴリズムは、SHA-256 ハッシュ アルゴリズムを使用する RSA のみです。これは、JWT ヘッダーの alg フィールドで RS256 として表されます。

Google API Consoleから取得した秘密鍵を使用して、SHA256withRSA（SHA-256 ハッシュ関数を使用した RSASSA-PKCS1-V1_5-SIGN とも呼ばれます）で入力の UTF-8 表現に署名します。出力はバイト配列になります。

署名は Base64url でエンコードする必要があります。ヘッダー、クレームセット、署名はピリオド（.）で連結されます。結果は JWT です。次のようになります（わかりやすくするために改行を追加しています）。

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

以下は、Base64url エンコード前の JWT の例です。

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

以下は、署名されて送信準備が整った JWT の例です。

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

アクセス トークン リクエストを行う

署名付き JWT を生成した後、アプリケーションはそれを使用してアクセス トークンをリクエストできます。このアクセス トークン リクエストは HTTPS POST リクエストで、本文は URL エンコードされています。URL は次のとおりです。

https://oauth2.googleapis.com/token

HTTPS POST リクエストでは、次のパラメータが必要です。

名前	説明
grant_type	必要に応じて URL エンコードされた次の文字列を使用します。 urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	署名を含む JWT。

アクセス トークン リクエストで使用される HTTPS POST リクエストの未加工のダンプは次のとおりです。

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

以下は、curl を使用した同じリクエストです。

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

レスポンスの処理

JWT とアクセス トークン リクエストが正しく作成され、サービス アカウントにオペレーションを実行する権限がある場合、認可サーバーからの JSON レスポンスにはアクセス トークンが含まれます。レスポンスの例を次に示します。

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

アクセス トークンは、expires_in 値で指定された期間ウィンドウ内で再利用できます。

Google API の呼び出し

Java

GoogleCredentials オブジェクトを使用して Google API を呼び出す手順は次のとおりです。

1. GoogleCredentials オブジェクトを使用して、呼び出す API のサービス オブジェクトを作成します。次に例を示します。

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();

2. サービス オブジェクトによって提供されるインターフェースを使用して、API サービスにリクエストを行います。たとえば、exciting-example-123 プロジェクトの Cloud SQL データベースのインスタンスを一覧表示するには:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

承認済みの Credentials オブジェクトを使用して Google API を呼び出す手順は次のとおりです。

1. 呼び出す API のサービス オブジェクトをビルドします。サービス オブジェクトは、API の名前とバージョン、承認済みの Credentials オブジェクトを指定して build 関数を呼び出すことで作成します。たとえば、Cloud SQL Administration API のバージョン 1beta3 を呼び出すには:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. サービス オブジェクトによって提供されるインターフェースを使用して、API サービスにリクエストを行います。たとえば、exciting-example-123 プロジェクトの Cloud SQL データベースのインスタンスを一覧表示するには:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

アプリケーションがアクセス トークンを取得したら、API で必要なアクセス スコープが付与されている場合、特定のサービス アカウントまたはユーザー アカウントの代わりにトークンを使用して Google API を呼び出すことができます。これを行うには、access_token クエリ パラメータまたは Authorization HTTP ヘッダー Bearer 値のいずれかを含めることで、API へのリクエストにアクセス トークンを含めます。クエリ文字列はサーバーログに表示される傾向があるため、可能な場合は HTTP ヘッダーを使用することをおすすめします。ほとんどの場合、クライアント ライブラリを使用して Google API への呼び出しを設定できます（たとえば、Drive Files API を呼び出す場合など）。

OAuth 2.0 Playground では、すべての Google API を試して、そのスコープを確認できます。

HTTP GET の例

Authorization: Bearer HTTP ヘッダーを使用して drive.files エンドポイント（ドライブ ファイル API）を呼び出すと、次のようになります。独自のアクセス トークンを指定する必要があります。

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

以下は、access_token クエリ文字列パラメータを使用して、認証済みユーザーに対して同じ API を呼び出す例です。

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl の例

これらのコマンドは、curl コマンドライン アプリケーションでテストできます。HTTP ヘッダー オプション（推奨）を使用する例を次に示します。

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

または、クエリ文字列パラメータ オプションを使用します。

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

アクセス トークンの有効期限

Google OAuth 2.0 認証サーバーによって発行されたアクセス トークンは、expires_in 値で指定された期間が経過すると期限切れになります。アクセス トークンの有効期限が切れた場合、アプリケーションは別の JWT を生成して署名し、別のアクセス トークンをリクエストする必要があります。

JWT エラーコード

error フィールド	error_description フィールド	意味	解決方法
unauthorized_client	Unauthorized client or scope in request.	ドメイン全体の委任を使用しようとしている場合、サービス アカウントがユーザーのドメインの管理コンソールで承認されていません。	管理コンソールの [ ドメイン全体の委任] ページで、sub クレーム（フィールド）のユーザーに対してサービス アカウントが承認されていることを確認します。 通常は数分で完了しますが、Google アカウントのすべてのユーザーに承認が反映されるまでに最長で 24 時間ほどかかることがあります。
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	管理コンソールで、クライアント ID（数値）ではなくクライアントのメールアドレスを使用してサービス アカウントが承認されました。	管理コンソールの [ ドメイン全体の委任] ページで、クライアントを削除し、数値 ID を使用して再度追加します。
access_denied	（任意の値）	ドメイン全体の委任を使用している場合、リクエストされた 1 つ以上のスコープが管理コンソールで承認されていません。	サービス アカウントが、管理コンソールの [ ドメイン全体の委任] ページで sub クレーム（フィールド）のユーザーに対して承認されていること、また、JWT の scope クレームでリクエストしているすべてのスコープが含まれていることを確認します。 通常は数分で完了しますが、Google アカウントのすべてのユーザーに承認が反映されるまでに最長で 24 時間ほどかかることがあります。
admin_policy_enforced	（任意の値）	Google アカウントの Google Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを承認できません。	管理者が、OAuth クライアント ID にアクセス権が明示的に付与されるまで、すべてのスコープまたは機密性の高い制限付きスコープへのアクセスを制限する方法について詳しくは、Google Workspace 管理者向けヘルプ記事のGoogle Workspace のデータにアクセスできるサードパーティ製アプリと内部アプリを制御するをご覧ください。
invalid_client	（任意の値）	OAuth クライアントまたは JWT トークンが無効であるか、正しく構成されていません。 詳細については、エラーの説明を参照してください。	JWT トークンが有効で、正しいクレームが含まれていることを確認します。 OAuth クライアントとサービス アカウントが正しく構成され、正しいメールアドレスを使用していることを確認します。 JWT トークンが正しく、リクエストのクライアント ID に対して発行されたものであることを確認します。
deleted_client	（任意の値）	リクエストの作成に使用されている OAuth クライアントが削除されました。削除は、未使用のクライアント の場合に手動または自動で行われます。削除したクライアントは、削除後 30 日以内であれば復元できます。詳しくは、こちらをご覧ください。	有効なクライアント ID を使用します。
invalid_grant	Not a valid email.	このユーザーは存在しません。	sub クレーム（フィールド）のメールアドレスが正しいことを確認します。
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	通常、これはローカル システムの時刻が正しくないことを意味します。また、exp 値が iat 値より 65 分以上未来の場合や、exp 値が iat 値より小さい場合にも発生する可能性があります。	JWT が生成されるシステムの時計が正しいことを確認します。必要に応じて、Google NTP と時刻を同期します。
invalid_grant	Invalid JWT Signature.	JWT アサーションが、クライアント メールアドレスで識別されるサービス アカウントに関連付けられていない秘密鍵で署名されているか、使用された鍵が削除、無効化、または期限切れになっています。 また、JWT アサーションが正しくエンコードされていない可能性もあります。JWT アサーションは、改行やパディングの等号なしで Base64 でエンコードする必要があります。	JWT クレームセットをデコードし、アサーションに署名したキーがサービス アカウントに関連付けられていることを確認します。 Google 提供の OAuth ライブラリを使用して、JWT が正しく生成されていることを確認してください。
invalid_scope	Invalid OAuth scope or ID token audience provided.	スコープがリクエストされていない（スコープのリストが空）、またはリクエストされたスコープのいずれかが存在しない（無効である）。	JWT の scope クレーム（フィールド）が入力されていることを確認し、そのクレームに含まれるスコープと、使用する API のドキュメントに記載されているスコープを比較して、エラーやタイプミスがないことを確認します。 scope クレームのスコープのリストは、カンマではなくスペースで区切る必要があります。
disabled_client	The OAuth client was disabled.	JWT アサーションの署名に使用される鍵が無効になっている。	Google API Consoleに移動し、[IAM と管理 > サービス アカウント] で、アサーションの署名に使用される「キー ID」を含むサービス アカウントを有効にします。
org_internal	This client is restricted to users within its organization.	リクエスト内の OAuth クライアント ID は、特定の Google Cloud 組織内の Google アカウントへのアクセスを制限するプロジェクトの一部です。	組織のサービス アカウントを使用して認証します。OAuth アプリケーションのユーザータイプの構成を確認します。

付録: OAuth を使用しないサービス アカウントの認可

一部の Google API では、OAuth 2.0 アクセス トークンではなく署名付き JWT を署名なしトークンとして直接使用する認証済み API を呼び出すことができます。こちらが使用できる場合、API を呼び出す前に Google の認証サーバーへのネットワーク リクエストを作成する必要がなくなります。

呼び出す API に Google API GitHub リポジトリで公開されているサービス定義がある場合、アクセス トークンではなく JWT を使用して認証済み API 呼び出しを行うことができます。手順は次のとおりです。

1. 上記の説明に従って、サービス アカウントを作成します。アカウントの作成時に取得した JSON ファイルは必ず保管してください。
2. jwt.io にあるものなど、標準の JWT ライブラリを使用して、次の例のようなヘッダーとペイロードを含む JWT を作成します。

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• ヘッダーの kid フィールドに、サービス アカウントの秘密鍵 ID を指定します。この値は、サービス アカウントの JSON ファイルの private_key_id フィールドで確認できます。
• iss フィールドと sub フィールドに、サービス アカウントのメールアドレスを指定します。この値は、サービス アカウントの JSON ファイルの client_email フィールドで確認できます。
• aud フィールドに API エンドポイントを指定します。例: https://SERVICE.googleapis.com/。
• iat フィールドには現在の Unix 時間を指定し、exp フィールドには JWT の有効期限が切れる 3,600 秒後の時間を指定します。

サービス アカウントの JSON ファイルにある秘密鍵を使用して、RSA-256 で JWT に署名します。

次に例を示します。

Java

google-auth-library-java と java-jwt を使用した場合:

import com.google.auth.oauth2.ServiceAccountCredentials;
...
GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey();
String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

PyJWT を使用した実装例:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. 署名付き JWT をベアラートークンとして使用して、API を呼び出します。

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com

クロスアカウント保護機能の実装

ユーザーのアカウントを保護するために行うべき追加の手順として、Google のクロス アカウント保護サービスを利用してクロス アカウント保護を実装することが挙げられます。このサービスでは、ユーザー アカウントの大きな変更に関する情報をアプリケーションに提供するセキュリティ イベント通知を登録できます。この情報を使用して、イベントへの対応方法に応じてアクションを実行できます。

Google のクロス アカウント保護サービスからアプリに送信されるイベントタイプの例を次に示します。

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

クロスアカウント保護の実装方法と利用可能なイベントの完全なリストについては、 クロスアカウント保護でユーザー アカウントを保護する をご覧ください。