アカウントは、業界標準の OAuth 2.0 インプリシット フローと認可コードフローを使用してリンクされます。サービスは、OAuth 2.0 準拠の認可エンドポイントとトークン交換エンドポイントをサポートする必要があります。
In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.
In the authorization code flow, you need two endpoints:
The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.
The token exchange endpoint, which is responsible for two types of exchanges:
- Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
- Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.
Choose an OAuth 2.0 flow
Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.
Design guidelines
This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.
Requirements
- You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
Recommendations
We recommend that you do the following:
Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.
Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.
Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.
Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.
Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.
- If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking and the implicit flow.
Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.
プロジェクトを作成する
アカウントのリンクを使用するプロジェクトを作成するには:
- Go to the Google API Console.
- [ プロジェクトを作成]をクリックします 。
- 名前を入力するか、生成された提案を受け入れます。
- 残りのフィールドを確認または編集します。
- 作成をクリックします 。
To view your project ID:
- Go to the Google API Console.
- Find your project in the table on the landing page. The project ID appears in the ID column.
OAuth 同意画面を構成する
Google アカウントのリンクのプロセスには、データへのアクセスをリクエストするアプリがユーザーに対し、どのようなデータを要求し、適用される規約があるかを伝える同意画面が含まれます。Google API クライアント ID を生成する前に、OAuth 同意画面を構成する必要があります。
- Google API コンソールの OAuth 同意画面ページを開きます。
- プロンプトが表示されたら、作成したプロジェクトを選択します。
[OAuth 同意画面] ページで、フォームに記入して [保存] ボタンをクリックします。
アプリケーション名: 同意を求めるアプリの名前。名前は、アプリを正確に反映し、ユーザーが他の場所で目にするアプリ名と一貫している必要があります。アプリケーション名は、アカウントのリンクの同意画面に表示されます。
アプリのロゴ: ユーザーがアプリを認識できるように、同意画面に表示する画像。ロゴは、アカウントのリンクに関する同意画面とアカウント設定に表示されます。
サポートメール: ユーザーが同意について問い合わせる際に使用するメールです。
Google API のスコープ: スコープを使用すると、アプリケーションがユーザーの非公開の Google データにアクセスできるようになります。Google アカウントのリンクのユースケースでは、デフォルトのスコープ(email、profile、openid)で十分であり、機密性の高いスコープを追加する必要はありません。通常、事前にではなく、アクセスが必要になったときにスコープを段階的にリクエストすることをおすすめします。詳細
承認済みドメイン: デベロッパーとユーザーを保護するため、Google では OAuth を使用して認証するアプリケーションのみに承認済みドメインの使用を許可しています。アプリのリンクは、承認済みドメインでホストする必要があります。詳細
アプリケーションのホームページへのリンク: アプリケーションのホームページ。承認済みドメインでホストされている必要があります。
アプリケーションのプライバシー ポリシーのリンク: Google アカウントのリンクの同意画面に表示されます。承認済みドメインでホストされている必要があります。
アプリケーションの利用規約へのリンク(省略可): 承認済みドメインでホストされている必要があります。
図 1. 架空のアプリ「Tunery」の Google アカウントのリンクに関する同意画面
[確認ステータス] を確認します。アプリの確認が必要な場合は、[確認のために送信] ボタンをクリックして確認のためにアプリを送信します。詳しくは、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
: 文字列bearer
state
: 元の状態から変更されていない状態の値 リクエスト
結果の 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 に追加できます。
Handle userinfo requests
The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:
- Linked Account Sign-In with Google One Tap.
- Frictionless subscription on AndroidTV.
After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.
userinfo endpoint request headers | |
---|---|
Authorization header |
The access token of type Bearer. |
For example, if your userinfo endpoint is available at
https://myservice.example.com/userinfo
, a request might look like the following:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
For your userinfo endpoint to handle requests, do the following steps:
- Extract access token from the Authorization header and return information for the user associated with the access token.
- If the access token is invalid, return an HTTP 401 Unauthorized error with using the
WWW-Authenticate
Response Header. Below is an example of a userinfo error response: If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:
If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
userinfo endpoint response sub
A unique ID that identifies the user in your system. email
Email address of the user. given_name
Optional: First name of the user. family_name
Optional: Last name of the user. name
Optional: Full name of the user. picture
Optional: Profile picture of the user.
実装の検証
You can validate your implementation by using the OAuth 2.0 Playground tool.
In the tool, do the following steps:
- Click Configuration to open the OAuth 2.0 Configuration window.
- In the OAuth flow field, select Client-side.
- In the OAuth Endpoints field, select Custom.
- Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
- In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
- In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.
You can validate your implementation by using the Google Account Linking Demo tool.
In the tool, do the following steps:
- Click the Sign-in with Google button.
- Choose the account you'd like to link.
- Enter the service ID.
- Optionally enter one or more scopes that you will request access for.
- Click Start Demo.
- When prompted, confirm that you may consent and deny the linking request.
- Confirm that you are redirected to your platform.