アカウント リンク API

このリファレンス ページでは、Google とのアカウント リンクをサポートするためにサービスで実装する必要がある API エンドポイントについて説明します。これには、OAuth リンク、 簡素化されたアカウント リンク、および アプリ切り替えが含まれます。

前提条件と標準

これらのエンドポイントを正常に実装するには、サービスが次の標準に準拠している必要があります。

  • OAuth 2.0: RFC 6749 に準拠している。
  • トークンの取り消し: RFC 7009 に準拠している。
  • JSON Web Token（JWT）: RFC 7519 に準拠している（ 簡素化されたリンクに必要）。
  • HTTPS: すべてのエンドポイントは、安全な HTTPS 接続で提供する必要があります。

承認エンドポイント

承認エンドポイントは、ユーザーの認証と、アカウントを Google にリンクするための同意の取得を行います。

  • URL: Actions Console または Google Cloud コンソールで構成します。
  • メソッド: GET

リクエスト パラメータ

パラメータ 説明
client_id Google に割り当てたクライアント ID。
redirect_uri このリクエストに対するレスポンスを送信する宛先 URL。
state リダイレクト URI で変更されずに Google に返される会計上の値。
response_type 認可コードフローの場合は code にする必要があります。
scope （省略可）Google がリクエストしているデータのスコープのスペース区切りリスト。
user_locale （省略可）Google アカウントの言語設定。BCP-47 言語タグ（en-US など）を使用して指定します。
code_challenge （OAuth 2.1 で必須）コード検証ツールから派生したチャレンジ。
code_challenge_method （省略可）チャレンジの派生に使用するメソッド（S256 など）。

トークン交換エンドポイント

このエンドポイントは、トークンの認証コードの交換と、期限切れのアクセス トークンの更新を行います。

  • URL: Actions Console または Google Cloud コンソールで構成します。
  • メソッド: POST
  • Content-Type: application/x-www-form-urlencoded

認証コードをトークンと交換する

最初のトークン交換リクエストでは、次のパラメータが使用されます。

リクエスト パラメータ

パラメータ 説明
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。
grant_type authorization_code にする必要があります。
code 承認エンドポイントから受信した認証コード。
redirect_uri 最初のリクエストで使用したリダイレクト URI と同じ。
code_verifier （PKCE で必須）元の暗号化ランダム文字列。

更新トークンとアクセス トークンを交換する

アクセス トークンを更新する場合は、次のパラメータを使用します。

リクエスト パラメータ

パラメータ 説明
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。
grant_type refresh_token にする必要があります。
refresh_token 以前に Google に発行された更新トークン。

レスポンス（JSON）

HTTPS レスポンスの本文に JSON オブジェクトを含む成功レスポンスを返します。

OpenAPI 3.1 スキーマ

type: object
required:
  - token_type
  - access_token
  - expires_in
properties:
  token_type:
    type: string
    enum: [bearer]
  access_token:
    type: string
  refresh_token:
    type: string
  expires_in:
    type: integer
  • HTTP ステータス: 200 OK
  • Content-Type: application/json;charset=UTF-8
フィールド 説明
token_type 必須。bearer にする必要があります。
access_token 必須。サービスの API へのアクセスに使用される有効期間の短いトークン。
refresh_token authorization_code grant_type で必須。新しいアクセス トークンを取得するために使用される有効期間の長いトークン。
expires_in 必須。アクセス トークンの残りの有効期間（秒単位）。

エラー レスポンス

トークン エンドポイントへのリクエストが失敗した場合は、HTTP 400 Bad Request エラーと、次のフィールドを含む JSON レスポンスを返します。

  • HTTP ステータス: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
エラー フィールド（JSON） 説明
error 必須。invalid_grant にする必要があります。
error_description （省略可）追加情報を提供する人間が読めるテキスト。

簡素化されたリンク インテントを処理する

サービスが簡素化されたアカウント リンク（Google でログインを使用した OAuth）をサポートしている場合、トークン交換エンドポイントは JSON Web Token（JWT）アサーションもサポートし、check、create、get インテントを実装する必要があります。

これらのリクエストでは、次のパラメータが使用されます。

リクエスト パラメータ

パラメータ 説明
intent リクエストされている特定の簡素化されたリンク インテント: check、get、create。
grant_type これらのリクエストの場合、このパラメータの値は常に urn:ietf:params:oauth:grant-type:jwt-bearer です。
assertion Google ユーザー ID の署名付きアサーションを提供する JSON Web Token（JWT）。この JWT には、ユーザーの Google アカウント ID、名前、メールアドレスなどの情報が含まれます。

サーバーは、JWT 検証セクションに記載されている条件を使用して、この JWT を検証する必要があります 。
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。
scope 省略可: Google からユーザーに同意を求めるように構成したスコープ。通常、get インテントと create インテントで存在します。
response_type create インテントで必須: token に設定する必要があります。

JWT 検証

簡素化されたリンクのセキュリティを確保するには、サーバーで次の条件を使用して assertion（JWT）を検証する必要があります。

  • 署名: Google の公開鍵（ Google の JWK エンドポイントで入手可能）に対して署名を検証します。
  • 発行者（iss）: https://accounts.google.com にする必要があります。
  • 対象（aud）: 統合に割り当てられた Google API クライアント ID と一致する必要があります。
  • 有効期限（exp）: 未来にする必要があります。

check インテントに対するレスポンス

intent=check のリクエストは、Google アカウント（デコードされた JWT アサーションの sub クレームまたは email クレームで識別）がユーザー データベースに存在するかどうかを確認します。

  • HTTP ステータス: 200 OK（アカウントが見つかった場合）または 404 Not Found（アカウントが見つからなかった場合）
  • Content-Type: application/json;charset=UTF-8
フィールド 説明
account_found 必須。アカウントが存在する場合は true、存在しない場合は false。

get インテントに対するレスポンス

intent=get のリクエストは、既存の Google アカウントのアクセス トークンをリクエストします。

  • HTTP ステータス: 200 OK
  • Content-Type: application/json;charset=UTF-8

成功レスポンスの JSON オブジェクトは、 成功した 標準のトークン交換レスポンス（ access_token、refresh_token などを返す）と同じ構造を使用します。

アカウントをリンクできない場合は、HTTP 401 エラーが返されます。

  • HTTP ステータス: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
エラー フィールド（JSON） 説明
error 必須。linking_error にする必要があります。
login_hint （省略可）フォールバック OAuth リンクフローに渡すユーザーのメールアドレス。

create インテントに対するレスポンス

intent=create のリクエストは、JWT で提供された情報を使用して新しいユーザー アカウントの作成をリクエストします。

  • HTTP ステータス: 200 OK
  • Content-Type: application/json;charset=UTF-8

成功レスポンスの JSON オブジェクトは、 成功した 標準のトークン交換レスポンス（ access_token、refresh_token などを返す）と同じ構造を使用します。

ユーザーがすでに存在する場合は、HTTP 401 エラーが返され、既存のアカウントをリンクするように求められます。

  • HTTP ステータス: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
エラー フィールド（JSON） 説明
error 必須。linking_error にする必要があります。
login_hint フォールバック OAuth リンクフローに渡すユーザーのメールアドレス。

UserInfo エンドポイント（省略可）

OpenID Connect Core 1.0 仕様で指定されているように、リンクされたユーザーの基本的なプロフィール情報を取得するために使用されます。これは、「簡素化されたリンク」や「One Tap サインイン」などの機能に必要です。

  • メソッド: GET
  • 認証: Authorization: Bearer ACCESS_TOKEN

レスポンス（JSON）

HTTPS レスポンスの本文に JSON オブジェクトを含む成功レスポンスを返します。

  • HTTP ステータス: 200 OK
  • Content-Type: application/json;charset=UTF-8

レスポンスのフィールド

フィールド 説明
sub 必須。システム内でユーザーを識別する一意の ID。
email 必須。ユーザーのメールアドレス。
email_verified 必須。メールアドレスが確認済みかどうかを示すブール値。
given_name （省略可）ユーザーの名。
family_name （省略可）ユーザーの姓。
name （省略可）ユーザーのフルネーム。
picture （省略可）ユーザーのプロフィール写真の URL。

エラー レスポンス

アクセス トークンが無効または期限切れの場合は、HTTP 401 Unauthorized エラーを返します。WWW-Authenticate レスポンス ヘッダーも含める必要があります。

アカウントへの関連付け中に返された失敗レスポンス（4xx または 5xx）は、回復不能とみなされます。このような場合、Google は取得したトークンを破棄し、ユーザーはアカウントへの関連付けプロセスを再度開始する必要があります。

トークン取り消しエンドポイント（省略可）

ユーザーが Google サーフェスからアカウントのリンクを解除したときに、Google がサービスに通知できるようにします。このエンドポイントは、 RFC 7009に記載されている要件を満たしている必要があります。

  • メソッド: POST
  • Content-Type: application/x-www-form-urlencoded

リクエスト パラメータ

パラメータ 説明
client_id リクエスト元を Google として識別する文字列。この文字列は、Google の一意の識別子としてシステムに登録されている必要があります。
client_secret Google に登録したサービスのシークレット文字列。
token 取り消すトークン。
token_type_hint （省略可）取り消されるトークンのタイプ（access_token または refresh_token）に関するヒント。指定しない場合のデフォルトは access_token です。

回答

トークンが正常に削除された場合、またはトークンがすでに無効な場合は、成功レスポンスを返します。

  • HTTP ステータス: 200 OK
  • Content-Type: application/json;charset=UTF-8

エラー レスポンス

何らかの理由でトークンを削除できない場合（データベースが利用できないなど）、HTTP 503 エラー を返します。Google は、後でリクエストを再試行するか、Retry-After ヘッダーで指定されたとおりにリクエストを再試行します。

  • HTTP ステータス: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • ヘッダー: Retry-After: <HTTP-date / delay-seconds>