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

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

Google OAuth 2.0 システムは、ウェブ アプリケーションと Google サービスの間のようなサーバー間インタラクションをサポートしています。このシナリオではサービス アカウントが必要です。これは、個々のエンドユーザーではなく、アプリケーションに属するアカウントです。アプリケーションがサービス アカウントに代わって Google API を呼び出すため、ユーザーが直接関与することはありません。このシナリオは「2-legged 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 を使用しないサービス アカウント認証をご覧ください。

概要

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

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

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

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

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

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

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

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

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

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

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

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 ポリシーの「クライアントの認証情報を安全に処理する」をご覧ください。

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

Google Workspace アカウントをお持ちの場合、組織の管理者は、Google 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. [Add new] をクリックします。
4. [クライアント ID] フィールドに、サービス アカウントのクライアント ID を入力します。サービス アカウントのクライアント ID は Service accounts pageで確認できます。
5. [OAuth スコープ（カンマ区切り）] フィールドに、アプリケーションへのアクセスを許可するスコープのリストを入力します。たとえば、アプリケーションがドメイン全体の Google Drive API と Google Calendar API への完全アクセス権を必要とする場合は、「https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar」と入力します。
6. [承認] をクリックします。

これで、アプリケーションにはドメイン内のユーザーとして「なりすまし」を行う API 呼び出しを行う権限が付与されました。承認済み API 呼び出しの準備をするときは、権限を借用するユーザーを指定します。

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

承認済み API 呼び出しの準備

Java

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

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

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

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

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

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

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

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

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]')

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

HTTP/REST

推奨事項: アプリケーションは HTTP を使用して OAuth 2.0 システムを直接操作することでこれらのタスクを実行できますが、サーバー間認証インタラクションのメカニズムでは、アプリケーションが JSON Web Token（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 ヘッダーの形成

ヘッダーは、署名アルゴリズムとアサーションの形式を示す 2 つのフィールドで構成されます。どちらの項目も必須で、各フィールドの値は 1 つのみです。追加のアルゴリズムや形式が導入された時点で、このヘッダーは変更されます。

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

{"alg":"RS256","typ":"JWT"}

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

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

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 アクセスを制御するをご覧ください。

リソースへのアクセス権をアプリケーションに付与したアクセス トークンを取得するには、sub フィールドの値として設定された JWT クレームにユーザーのメールアドレスを含めます。

氏名	説明
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 を生成したら、アプリケーションはその 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

GoogleCredential オブジェクトを使用して Google API を呼び出すには、次の手順を行います。

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

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

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

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

Python

承認済みの Credentials オブジェクトを使用して Google API を呼び出すには、次の手順を行います。

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

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

2. サービス オブジェクトによって提供されるインターフェースを使用して API サービスへのリクエストを行います。たとえば、エキサイティングな 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 を呼び出すときなど）。

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

HTTP GET の例

Authorization: Bearer HTTP ヘッダーを使用した drive.files エンドポイント（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 Workspace 管理者のポリシーにより、リクエストされた 1 つ以上のスコープを Google アカウントが承認できません。	OAuth クライアント ID へのアクセスを明示的に付与するまで、すべてのスコープまたは機密性の高いスコープと制限付きスコープへのアクセスを管理者がどのように制限するかについて詳しくは、Google Workspace 管理者用ヘルプの記事をご覧ください。
invalid_client	（任意の値）	OAuth クライアントまたは JWT トークンが無効であるか正しく構成されていません。 詳細については、エラーの説明を参照してください。	JWT トークンが有効であり、正しいクレームが含まれていることを確認してください。 OAuth クライアントとサービス アカウントが正しく構成されていることと、正しいメールアドレスを使用していることを確認します。 JWT トークンが正しいこと、およびリクエスト内のクライアント 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 アサーションが正しくエンコードされていない可能性もあります。Base64 でエンコードして、改行やパディングの等号を付けないでください。	JWT クレームセットをデコードし、アサーションに署名した鍵がサービス アカウントに関連付けられていることを確認します。 Google 提供の OAuth ライブラリを使用して、JWT が正しく生成されることを確認してください。
invalid_scope	Invalid OAuth scope or ID token audience provided.	スコープが要求されていない（スコープの空のリスト）、またはリクエストされたスコープの 1 つが存在しない（つまり、無効）。	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 を直接使用して署名済みの JWT を使用し、承認済みの API 呼び出しを行うことができます。これにより、API 呼び出しを行う前に Google の承認サーバーにネットワーク リクエストを行う必要がなくなります。

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

1. 上のようなサービス アカウントを作成します。アカウントの作成時に取得した JSON ファイルを必ず保持してください。
2. 標準の JWT ライブラリ（jwt.io にあるものなど）を使用して、ヘッダーとペイロードを含む 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-api-java-client と java-jwt を使用する場合:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

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