トークンの種類

このページでは、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 APIs と Identity and Access Management（IAM）を含み、きめ細かなアクセス制御を提供します。
expires_in トークンの期限が切れるまでの秒数。詳細については、アクセス トークンの有効期間をご覧ください。

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

デフォルトでは、アクセス トークンの有効期間は 1 時間（3,600 秒）です。アクセス トークンが期限切れになると、トークン管理コードで新しいトークンを取得する必要があります。

有効期間が長い、または短いアクセス トークンが必要な場合は、serviceAccounts.generateAccessToken メソッドを使用してトークンを作成できます。この方法では、トークンの存続期間を選択できます。最大存続期間は 12 時間です。

トークンの有効期間をデフォルトより長くする場合は、iam.allowServiceAccountCredentialLifetimeExtension 制約を有効にする組織のポリシーを作成する必要があります。ユーザー認証情報または外部 ID に対して、有効期間が長いアクセス トークンを作成することはできません。詳細については、有効期間の短いアクセス トークンを作成するをご覧ください。

ID トークン

ID トークンは、OpenID Connect（OIDC）仕様に準拠した JSON Web Token（JWT）です。これらは、クレームと呼ばれる一連の Key-Value ペアで構成されます。

アプリケーションで検査できない不透明なオブジェクトであるアクセス トークンとは異なり、ID トークンはアプリケーションで検査して使用するためのものです。トークンの署名者や ID トークンが発行された ID など、トークンの情報はアプリケーションで使用できます。

Google の OIDC 実装の詳細については、OpenID Connect をご覧ください。JWT の使用に関するベスト プラクティスについては、JSON Web Token の現在のベスト プラクティスをご覧ください。

ID トークンの内容

Google OAuth 2.0 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 Functions、Identity-Aware Proxy などの Google サービスを使用する場合、Google は ID トークンを検証します。このような場合、ID トークンは Google によって署名されている必要があります。

アプリケーション内で ID トークンを検証する必要がある場合、検証は可能ですが、高度なワークフローです。詳細については、ID トークンの検証をご覧ください。

自己署名 JSON ウェブトークン（JWT）

API Gateway を使用してデプロイされた API の認証には、自己署名 JWT が必要です。また、自己署名 JWT を使用すると、承認サーバーからアクセス トークンを取得しなくても、一部の Google API に対する認証を行うことができます。

自己署名 JWT の作成は、Google API にアクセスするための独自のクライアント ライブラリを作成する場合には推奨されますが、高度なワークフローです。自己署名 JWT の詳細については、自己署名 JSON ウェブトークンの作成をご覧ください。JWT の使用に関するベスト プラクティスについては、JSON Web Token の現在のベスト プラクティスをご覧ください。

更新トークン

デフォルトでは、アクセス トークンと ID トークンの有効期間は 1 時間です。更新トークンは、追加のアクセス トークンまたは ID トークンを取得するために使用される特別なトークンです。アプリケーションが最初に認証すると、アクセス トークン（または ID トークン）と更新トークンを受け取ります。その後、アプリケーションがリソースに再度アクセスする必要があり、以前に提供したトークンが期限切れになった場合、更新トークンを使用して新しいトークンをリクエストします。更新トークンは、Cloud Identity や Google Workspace などのユーザー認証にのみ使用されます。

更新トークンには有効期間が設定されていません。期限切れになる可能性はありますが、継続して使用できる状態です。Google Workspace または Cloud Identity Premium Edition のユーザー アクセスの場合、セッションの長さを構成すれば、ユーザーが定期的にログインして、Google Cloud サービスへのアクセスを維持できるようにすることができます。

アプリケーションで独自のトークンを作成して管理する場合は、更新トークンも管理する必要があります。詳細は、次のリンク先をご覧ください。

連携トークン

連携トークンは、Workload Identity 連携による中間ステップとして使用されます。連携トークンはセキュリティ トークン サービスによって返されるため、直接使用できません。これらは、サービス アカウントの権限借用を使用してアクセス トークンと交換する必要があります。

署名なしトークン

署名なしトークンは、トークンを所有するパーティーにアクセス権を付与する一般的なクラスです。アクセス トークン、ID トークン、自己署名 JWT はすべて署名なしトークンです。

署名なしトークンの認証の使用は、HTTPS などの暗号化されたプロトコルによって提供されるセキュリティに依存します。署名なしトークンがインターセプトされると、不正な行為者がこれを利用してアクセスできるようになる可能性があります。

署名なしトークンでユースケースに十分なセキュリティが得られない場合は、別の暗号化レイヤを追加するか、BeyondCorp Enterprise などの相互 Transport Layer Security（mTLS）ソリューションの使用を検討してください。これにより、アクセスできるのは、信頼できるデバイスの認証済みユーザーのみとなります。

次のステップ