アカウントは、業界標準の OAuth 2.0 インプリシット フローと認可コードフローを使用してリンクされます。サービスは、OAuth 2.0 準拠の認可エンドポイントとトークン交換エンドポイントをサポートする必要があります。
暗黙的フローでは、Google がデベロッパーのブラウザで認可エンドポイントを開きます。ログインに成功したら、認可エンドポイントから長期のアクセス トークンを Google に返します。このアクセス トークンは、Google から送信されるすべてのリクエストに含まれます。
認証コードフローでは、次の 2 つのエンドポイントが必要になります。
認可エンドポイント。ログインしていないユーザーにログイン用の UI を表示します。認可エンドポイントは、リクエストされたアクセスに対するユーザーの同意を記録するために、有効期間の短い認可コードも作成します。
トークン交換エンドポイント。次の 2 種類の交換を行います。
- 長期の更新トークンと短期のアクセス トークンの認可コードを交換します。この処理は、ユーザーがアカウントのリンクフローを行ったときに発生します。
- 長期の更新トークンを短期のアクセス トークンと交換します。この処理は、トークンが期限切れになり、新しいアクセス トークンが必要になった場合に発生します。
OAuth 2.0 フローを選択する
暗黙的フローの実装は簡単ですが、暗黙的フローによって発行されたアクセス トークンには有効期限を設定しないことをおすすめします。これは、暗黙的フローでトークンが期限切れになると、ユーザーがアカウントを再度リンクしなければならないためです。セキュリティ上の理由からトークンに有効期限を設定する必要がある場合は、代わりに認可コードフローを使用することを強くおすすめします。
設計ガイドライン
このセクションでは、OAuth リンクフロー用にホストするユーザー画面の設計要件と推奨事項について説明します。Google のアプリから呼び出されると、プラットフォームはユーザーに Google にログインするページとアカウントのリンクに関する同意画面を表示します。アカウントのリンクに同意すると、ユーザーは Google のアプリに戻されます。
要件
- ユーザーのアカウントは、Google Home や Google アシスタントなどの特定の Google プロダクトではなく、Google にリンクされることを伝える必要があります。
推奨事項
次のことをおすすめします。
Google のプライバシー ポリシーを表示する。同意画面に Google のプライバシー ポリシーへのリンクを含めます。
共有するデータ。明確で簡潔な表現を使用して、Google に必要なデータとその理由をユーザーに伝えます。
行動を促す明確なフレーズ同意画面に「同意してリンク」など、わかりやすい行動を促すフレーズを表示します。これは、アカウントをリンクするために Google と共有する必要があるデータをユーザーが理解する必要があるためです。
キャンセルできること。ユーザーがリンクしないことを選択した場合に、ユーザーが戻るまたはキャンセルできる方法を提供します。
ログイン プロセスを明確にする。ユーザーが Google アカウントにログインするための明確な方法（ユーザー名とパスワードのフィールド、Google でログインなど）があることを確認します。
リンクを解除できること。ユーザーがリンクを解除するためのメカニズム（プラットフォームのアカウント設定への URL など）を提供します。または、ユーザーがリンクされたアカウントを管理できる Google アカウントへのリンクを含めることもできます。
ユーザー アカウントを変更する機能。ユーザーがアカウントを切り替える方法を提案します。これは、ユーザーが複数のアカウントを持っている場合に特に便利です。
- ユーザーがアカウントを切り替えるために同意画面を閉じる必要がある場合は、回復可能なエラーを Google に送信して、ユーザーが OAuth リンクと暗黙的フローを使用して目的のアカウントにログインできるようにします。
ロゴを含めます。同意画面に会社のロゴを表示します。 スタイル ガイドラインに沿ってロゴを配置します。Google のロゴも表示する場合は、ロゴと商標をご覧ください。
プロジェクトを作成する
アカウント リンクを使用するプロジェクトを作成するには:
- Go to the Google API Console.
- [プロジェクトの作成] をクリックします。
- 名前を入力するか、生成された候補をそのまま使用します。
- 残りのフィールドを確認または編集します。
- [作成] をクリックします。
プロジェクト ID を表示するには:
- Go to the Google API Console.
- ランディング ページの表でプロジェクトを見つけます。プロジェクト ID は [ID] 列に表示されています。
OAuth 同意画面を構成する
Google アカウントのリンク プロセスには、ユーザーのデータへのアクセスをリクエストしているアプリケーション、リクエストしているデータの種類、適用される条件をユーザーに知らせる同意画面が含まれます。Google API クライアント ID を生成する前に、OAuth 同意画面を構成する必要があります。
- Google API Console の [OAuth 同意画面] ページを開きます。
- プロンプトが表示されたら、作成したプロジェクトを選択します。
[OAuth 同意画面] ページで、フォームに記入して [保存] ボタンをクリックします。
アプリケーション名: 同意を求めるアプリケーションの名前。名前はアプリを正確に反映し、ユーザーが他の場所で見るアプリ名と一致している必要があります。アプリケーション名は、アカウント リンクの同意画面に表示されます。
アプリケーションのロゴ: 同意画面に表示される画像で、ユーザーがアプリを認識するのに役立ちます。ロゴは、アカウントのリンクの同意画面とアカウント設定に表示されます。
サポートのメールアドレス: ユーザーが同意について問い合わせる際に使用します。
Google API のスコープ: スコープを使用すると、アプリケーションはユーザーの非公開の Google データにアクセスできます。Google アカウントのリンクのユースケースでは、デフォルトのスコープ（email、profile、openid）で十分です。機密性の高いスコープを追加する必要はありません。一般的に、スコープは事前にリクエストするのではなく、アクセスが必要になったときに段階的にリクエストすることがベスト プラクティスです。詳細
承認済みドメイン: デベロッパーとユーザーを保護するために、Google では、OAuth を使用して認証するアプリケーションのみに承認済みドメインの使用を許可しています。アプリケーションのリンクは、承認済みドメインでホストする必要があります。詳細
アプリケーションのホームページへのリンク: アプリケーションのホームページ。承認済みドメインでホストされている必要があります。
アプリケーション プライバシー ポリシーへのリンク: Google アカウントのリンクの同意画面に表示されます。承認済みドメインでホストされている必要があります。
アプリケーション利用規約のリンク（省略可）: 承認済みドメインでホストされている必要があります。
図 1. 架空のアプリケーション Tunery の Google アカウントのリンクの同意画面
[Verification Status]（確認ステータス）を確認します。アプリケーションの確認が必要な場合は、[Submit For Verification]（確認のために送信）ボタンをクリックして、確認のためにアプリケーションを送信します。詳しくは、OAuth の確認要件をご覧ください。
OAuth サーバーを実装する
OAuth 2.0 の暗黙的フローをサポートするには、サービスで認証を行います。 使用できます。このエンドポイントは、認証と認可を担当します。 データアクセスについてユーザーから同意を得る。認可エンドポイントは、ログインしていないユーザーにログイン用の UI を表示し、リクエストされたアクセスへの同意を記録します。
Google アプリケーションが、サービスの承認済み API のいずれかを呼び出す必要がある場合は、 Google はこのエンドポイントを使用して、これらの API を呼び出す権限をユーザーから取得します 委任できます。
通常、Google が開始する OAuth 2.0 インプリシット フローのセッションは次のような流れになります。
- Google がユーザーのブラウザで認可エンドポイントを開きます。「 ユーザーがログインし（まだログインしていない場合）、Google に次の権限を与える API を使用してデータにアクセスする必要があります（まだ権限を付与していない場合）。
- サービスによってアクセス トークンが作成され、トークンが Googleそのためには、アクセス権を使ってユーザーのブラウザを Google にリダイレクトします。 リクエストに添付されたトークンです。
- Google がサービスの API を呼び出し、アクセス トークンを できます。サービスが、そのアクセス トークンが Google Cloud アクセスが承認され、API 呼び出しが完了します。
認可リクエストの処理
Google アプリケーションで OAuth 2.0 経由でアカウント リンクを実行する必要がある場合 の暗黙的フローで、Google はユーザーを認可エンドポイントに送り、 次のパラメータを含むリクエストです。
| 認可エンドポイントのパラメータ | |
|---|---|
client_id |
Google に割り当てたクライアント ID。 |
redirect_uri |
このリクエストに対するレスポンスを送信する URL。 |
state |
リダイレクト URL で変更されずに Google に返される会計上の値。 |
response_type |
レスポンスで返される値のタイプ。OAuth 2.0 暗黙の API では、
レスポンス タイプは常に token です。 |
user_locale |
Google アカウントの言語設定は RFC5646 ユーザーの使用言語にコンテンツをローカライズするために使用される形式を使用すること。 |
たとえば、認可エンドポイントが
https://myservice.example.com/auth の場合、リクエストは次のようになります。
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE
認可エンドポイントでログイン リクエストを処理するには、次の操作を行います。 手順:
client_idとredirect_uriの値を検証する 意図しないクライアント アプリへのアクセスや構成ミスのあるクライアント アプリclient_idが、指定したクライアント ID と一致することを確認します。 割り当てられていますredirect_uriで指定された URL を確認します。 パラメータの形式は次のとおりです。https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
ユーザーがサービスにログインしているかどうか確認します。ユーザーがログインしていない場合は、サービスのログインまたは登録フローを完了します。
Google が API にアクセスするために使用するアクセス トークンを生成します。「 アクセス トークンには任意の文字列値を指定できますが、アクセス トークンを一意に 推測できるようにする必要があります。
ユーザーのブラウザを URL にリダイレクトする HTTP レスポンスを送信する
redirect_uriパラメータで指定します。URL フラグメントに次のパラメータをすべて含めます。access_token: 生成したアクセス トークンtoken_type: 文字列bearerstate: 元の状態から変更されていない状態の値 リクエスト
結果の URL の例を次に示します。
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
Google の OAuth 2.0 リダイレクト ハンドラがアクセス トークンを受け取り、
state 値が変更されていないことを確認します。Google は、
そのトークンを後続の呼び出しにアタッチします。
サービス API に追加できます。
userinfo リクエストを処理する
userinfo エンドポイントは、OAuth 2.0 で保護されたリソースで、リンクされたユーザーに関するクレームを返します。userinfo エンドポイントの実装とホストは任意ですが、以下のユースケースを除きます。
- Google One タップによるリンクされたアカウントへのログイン。
- Android TV のスムーズな定期購入。
トークン エンドポイントからアクセス トークンが正常に取得されると、Google は、リンクされたユーザーに関する基本的なプロフィール情報を取得するためのリクエストを userinfo エンドポイントに送信します。
| userinfo エンドポイント リクエスト ヘッダー | |
|---|---|
Authorization header |
Bearer タイプのアクセス トークン。 |
たとえば、userinfo エンドポイントが
https://myservice.example.com/userinfo の場合、リクエストは次のようになります。
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
userinfo エンドポイントでリクエストを処理するには、次の手順を行います。
- Authorization ヘッダーからアクセス トークンを抽出し、そのアクセス トークンに関連付けられたユーザーの情報を返します。
- アクセス トークンが無効な場合は、
WWW-Authenticateレスポンス ヘッダーを使用して HTTP 401 Unauthorized エラーを返します。userinfo エラー レスポンスの例を次に示します。HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
アクセス トークンが有効な場合は、HTTPS の本文に次の JSON オブジェクトを含む HTTP 200 レスポンスを返します。 レスポンス:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }userinfo エンドポイント レスポンス subシステム内でユーザーを識別する一意の ID。 emailユーザーのメールアドレス。 given_name省略可: ユーザーの名。 family_name省略可: ユーザーの姓。 name省略可: ユーザーの氏名。 picture省略可: ユーザーのプロフィール写真。
実装の検証
実装を検証するには、OAuth 2.0 Playground ツールを使用します。
ツールで、次の操作を行います。
- [Configuration] をクリックして [OAuth 2.0 Configuration] ウィンドウを開きます。
- [OAuth flow] フィールドで、[Client-side] を選択します。
- [OAuth Endpoints]（OAuth エンドポイント）で、[Custom]（カスタム）を選択します。
- 対応するフィールドに、OAuth 2.0 エンドポイントと Google に割り当てたクライアント ID を指定します。
- [ステップ 1] セクションで、Google スコープは選択しないでください。代わりに、このフィールドを空白のままにするか、サーバーで有効なスコープを入力します（OAuth スコープを使用しない場合は任意の文字列を入力します）。完了したら、[API を承認] をクリックします。
- ステップ 2 とステップ 3 のセクションで OAuth 2.0 フローを実行し、各ステップが意図したとおりに機能することを確認します。
実装を検証するには、Google アカウント リンクのデモツールを使用します。
ツールで次の操作を行います。
- [Google でログイン] ボタンをクリックします。
- リンクするアカウントを選択します。
- サービス ID を入力します。
- 必要に応じて、アクセスをリクエストするスコープを 1 つ以上入力します。
- [デモを開始] をクリックします。
- リンク リクエストに同意できることを確認して、リクエストを拒否します。
- プラットフォームにリダイレクトされることを確認します。