このページでは、Google API、Google Cloud サービス、Google Cloud でホストされる顧客作成のサービスに対する認証に使用されるトークンの種類について説明します。
クライアント ライブラリを使用して Google API とサービスにアクセスする場合、アプリケーションのデフォルト認証情報を設定できます。クライアント ライブラリはトークンの処理を行います。これはおすすめの方法です。
トークンとは
認証と認可の場合、トークンは、リクエストを行っているプリンシパルの ID と、認可されているアクセスの種類に関する情報を含むデジタル オブジェクトです。ほとんどの認証フローでは、アプリケーションまたはアプリケーションで使用されるライブラリがトークンの認証情報を交換して、アプリケーションがどのリソースにアクセスできるかを決定します。
トークンの種類
使用されるトークンは、環境によって異なります。このページで説明するトークンの種類は次のとおりです。
このページでは、認証情報と見なされる API キーまたはクライアント ID については説明しません。アクセス トークン
アクセス トークンは、OAuth 2.0 フレームワークに準拠する不透明トークンです。これには認可情報が含まれますが、ID 情報は含まれません。これらは、認証を行い、Google API に認証情報を提供するために使用されます。
アプリケーションのデフォルト認証情報（ADC）と Cloud クライアント ライブラリまたは Google API クライアント ライブラリを使用する場合、アクセス トークンを管理する必要はありません。ライブラリは自動的に認証情報を取得し、アクセス トークンと交換して、必要に応じてアクセス トークンを更新します。
アクセス トークンの内容
アクセス トークンは不透明トークンであり、独自の形式です。アプリケーションでは検査できません。
有効な（有効期限が切れていないか、失効していない）アクセス トークンから情報を取得するには、Google OAuth 2.0 tokeninfo エンドポイントを使用します。
ACCESS_TOKEN は、有効期限内の有効なアクセス トークンに置き換えます。
curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"
このコマンドは、次の例のような値を返します。
{ "azp": "32553540559.apps.googleusercontent.com", "aud": "32553540559.apps.googleusercontent.com", "sub": "111260650121245072906", "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth", "exp": "1650056632", "expires_in": "3488", "email": "user@example.com", "email_verified": "true" }
次の表に、最も重要なフィールドを示します。
| フィールド | 説明 |
|---|---|
azp |
トークンをリクエストしたアプリケーションのプロジェクト、メール、またはサービス アカウント ID。この値は、スコープのリストで https://www.googleapis.com/auth/userinfo.email が指定されている場合にのみ含まれます。 |
scope |
このアクセス トークンに追加された OAuth スコープ。Google Cloud サービスについては、
https://www.googleapis.com/auth/cloud-platform
スコープを使用することをおすすめします。 これはすべての Google Cloud API と、
Identity and Access Management（IAM）を含み、きめ細かなアクセス制御を提供します。
|
expires_in |
トークンの期限が切れるまでの秒数。詳細については、アクセス トークンの有効期間をご覧ください。 |
アクセス トークンの有効期間
デフォルトでは、アクセス トークンの有効期間は 1 時間（3,600 秒）です。アクセス トークンが期限切れになると、トークン管理コードで新しいトークンを取得する必要があります。
有効期間が長い、または短いアクセス トークンが必要な場合は、serviceAccounts.generateAccessToken メソッドを使用してトークンを作成できます。この方法では、トークンの存続期間を選択できます。最大存続期間は 12 時間です。
トークンの有効期間をデフォルトより長くする場合は、iam.allowServiceAccountCredentialLifetimeExtension 制約を有効にする組織のポリシーを作成する必要があります。詳細については、有効期間の短いアクセス トークンを作成するをご覧ください。
ID トークン
ID トークンは、OpenID Connect（OIDC）仕様に準拠した JSON Web Token（JWT）です。これらは、クレームと呼ばれる一連の Key-Value ペアで構成されます。
アプリケーションで検査できない不透明なオブジェクトであるアクセス トークンとは異なり、ID トークンはアプリケーションで検査して使用するためのものです。トークンの署名者や ID トークンが発行された ID など、トークンの情報はアプリケーションで使用できます。
Google の OIDC 実装の詳細については、OpenID Connect をご覧ください。 JWT の使用に関するベスト プラクティスについては、JSON Web Token の現在のベスト プラクティスをご覧ください。ID トークンの内容
tokeninfo エンドポイントを使用すると、有効な（有効期限が切れていないか、失効していない）ID トークンを検査できます。
ID_TOKEN は、有効期限内の有効な ID トークンに置き換えます。
curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"
このコマンドは、次の例のような値を返します。
{ "iss": "https://accounts.google.com", "azp": "32555350559.apps.googleusercontent.com", "aud": "32555350559.apps.googleusercontent.com", "sub": "111260650121185072906", "hd": "google.com", "email": "user@example.com", "email_verified": "true", "at_hash": "_LLKKivfvfme9eoQ3WcMIg", "iat": "1650053185", "exp": "1650056785", "alg": "RS256", "kid": "f1338ca26835863f671403941738a7b49e740fc0", "typ": "JWT" }
次の表に、必須またはよく使用される ID トークンのクレームを示します。
| 反論 | 説明 |
|---|---|
iss |
トークンの発行者（または署名者）。Google によって署名された ID トークンの場合、この値は https://accounts.google.com になります。 |
azp |
省略可。トークンの発行者。 |
aud |
トークンの対象。このクレームの値は、トークンを使用してリクエストを認証するアプリケーションまたはサービスと一致する必要があります。詳細については、ID トークン aud クレームをご覧ください。 |
sub |
サブジェクト: リクエストを行っているプリンシパルを表す ID。 |
iat |
トークンが発行された Unix エポック時刻。 |
exp |
トークンの有効期限が切れる Unix エポック時刻。 |
発行者とアプリケーションによっては、他のクレームが存在する場合もあります。
ID トークン aud クレーム
aud クレームには、このトークンが呼び出すために作成されたサービス名が記述されます。サービスが ID トークンを受け取った場合、その整合性（署名）、有効性（期限切れかどうか）、aud クレームが期待される名前と一致することを確認する必要があります。一致しない場合、別のシステムに対してリプレイされる可能性があるため、サービスはトークンを拒否する必要があります。
一般に、ID トークンを取得するときは、ユーザー認証情報ではなく、サービス アカウントから提供される認証情報を使用します。これは、ユーザー認証情報を使用して生成された ID トークンに対する aud クレームが、ユーザーが認証に使用したアプリケーションに静的にバインドされているためです。サービス アカウントを使用して ID トークンを取得する場合は、aud クレームに異なる値を指定できます。
ID トークンの存続期間
ID トークンの有効期間は最大 1 時間（3,600 秒）です。ID トークンが期限切れになった場合は、新しいトークンを取得する必要があります。
ID トークンの検証
サービスやアプリケーションが Cloud Run、Cloud Run 関数、Identity-Aware Proxy などの Google サービスを使用する場合、Google は ID トークンを検証します。このような場合、ID トークンは Google によって署名されている必要があります。
アプリケーション内で ID トークンを検証する必要がある場合、検証は可能ですが、高度なワークフローです。詳細については、ID トークンの検証をご覧ください。
自己署名 JSON Web Token（JWT）
自己署名 JWT を使用すると、承認サーバーからアクセス トークンを取得しなくても、一部の Google API に対する認証を行うことができます。自己署名 JWT の作成は、Google API にアクセスするための独自のクライアント ライブラリを作成する場合には推奨されますが、高度なワークフローです。自己署名 JWT の詳細については、自己署名 JSON ウェブトークンの作成をご覧ください。JWT の使用に関するベスト プラクティスについては、JSON Web Token の現在のベスト プラクティスをご覧ください。
更新トークン
IdP は、長期間有効なトークンの有効期間を管理します。例外はローカル ADC ファイルです。ローカル ADC ファイルには、認証ライブラリがクライアント ライブラリのアクセス トークンを自動的に更新するために使用する更新トークンが含まれています。
連携トークン
連携トークンは、Workload Identity 連携と Workforce Identity 連携によってフェデレーション ID から生成されます。
連携トークンは次のように使用されます。
こうしたトークンをサポートするサービスでは、連携トークンを直接使用できます。この方法は、直接アクセスと呼ばることもあります。
連携トークンは、Security Token Service API を使用して OAuth 2.0 アクセス トークンと交換できます。
Workload Identity 連携と Workforce Identity 連携が返す連携トークンは、Workload Identity Federation for GKE が返すトークンと同等ではありません。Google Kubernetes Engine アプリケーションが Google API に対して認証を行う方法の詳細については、Workload Identity Federation for GKE を使用するようにアプリケーションを構成するをご覧ください。
署名なしトークン
署名なしトークンは、トークンを所有するパーティーにアクセス権を付与する一般的なクラスです。アクセス トークン、ID トークン、自己署名 JWT はすべて署名なしトークンです。
署名なしトークンの認証の使用は、HTTPS などの暗号化されたプロトコルによって提供されるセキュリティに依存します。署名なしトークンがインターセプトされると、不正な行為者がこれを利用してアクセスできるようになる可能性があります。
次のステップ
- ADC の認証情報を設定する方法を確認する。
- ID トークンの取得について確認する。
- 認証方法について詳しく理解する。