アカウント リンク API

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

前提条件と基準

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

  • OAuth 2.0: RFC 6749 に準拠しています。
  • トークンの取り消し: RFC 7009 に準拠しています。
  • JSON Web Token（JWT）: RFC 7519 に準拠（Streamlined Linking に必要）。
  • HTTPS: すべてのエンドポイントは安全な HTTPS 接続で配信する必要があります。

承認エンドポイント

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

  • URL: Actions Console または Google Cloud Console で構成されます。
  • メソッド: GET

リクエスト パラメータ

パラメータ 説明
client_id Google に割り当てたクライアント ID。
redirect_uri このリクエストに対するレスポンスを送信する宛先 URL。
state リダイレクト URI でそのまま Google に返される状態値。
response_type 認証コードフローの場合は code にする必要があります。
scope （省略可）Google がリクエストしているデータのスコープのスペース区切りリスト。
user_locale （省略可）Google アカウントの言語設定。BCP-47 言語タグ（en-US など）を使用して指定します。

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

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

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

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

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

リクエスト パラメータ

パラメータ 説明
client_id Google に割り当てたクライアント ID。
client_secret Google に割り当てたクライアント シークレット。
grant_type authorization_code を指定します。
code 認証エンドポイントから受信した認証コード。
redirect_uri 最初のリクエストで使用されたリダイレクト URI。

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

アクセス トークンを更新するときは、次のパラメータが使用されます。

リクエスト パラメータ

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

レスポンス（JSON）

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

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

エラー レスポンス

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

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

合理化されたリンク設定インテントを処理する

サービスがアカウント リンクの簡素化（Google でログインする OAuth）をサポートしている場合、トークン交換エンドポイントは JSON ウェブトークン（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 仕様で指定されているように、リンクされたユーザーに関する基本的なプロフィール情報を取得するために使用されます。これは、「リンクの簡素化」や「ワンタップ ログイン」などの機能に必要です。

  • メソッド: 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>