OAuth로 Google 계정 연결

계정은 업계 표준 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:

  1. 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.
  2. 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

1. 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:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. 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.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. 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.

6. 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.

7. 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.

8. 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.

Create the project

To create your project to use account linking:

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

1. Open the OAuth consent screen page of the Google APIs console.
2. If prompted, select the project you just created.

3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

   Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

   Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

   Support email: For users to contact you with questions about their consent.

   Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

   Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

   Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

   Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

   Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

   

   Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

OAuth 서버 구현

승인 코드 흐름의 OAuth 2.0 서버 구현은 다음으로 구성됩니다. 서비스가 HTTPS를 통해 사용할 수 있도록 하는 두 개의 엔드포인트 첫 번째 엔드포인트는 승인 엔드포인트로, 승인 엔드포인트는 사용자의 동의를 얻어야 합니다. 승인 엔드포인트는 로그인 UI를 사용자에게 제공하고 이에 대한 동의를 기록 액세스 권한을 요청합니다. 두 번째 엔드포인트는 토큰 교환 엔드포인트로, 토큰이라는 암호화된 문자열을 가져오는 데 사용되며, 이 문자열은 사용자에게 서비스에 액세스할 수 있습니다

Google 애플리케이션이 서비스의 API 중 하나를 호출해야 하는 경우 Google은 이러한 API를 호출할 수 있는 권한을 사용자로부터 얻기 위해 이러한 엔드포인트를 함께 모읍니다. 위임할 수 있습니다

Google에서 시작한 OAuth 2.0 승인 코드 흐름 세션에는 다음 흐름을 따라 하세요.

1. Google은 사용자의 브라우저에서 승인 엔드포인트를 엽니다. 흐름이 작업을 위해 음성 전용 기기에서 시작된 경우 Google은 실행되는 것입니다.
2. 사용자가 아직 로그인하지 않은 경우 로그인하여 Google에 다음 권한을 부여합니다. 아직 권한을 부여하지 않은 경우 API를 통해 데이터에 액세스할 수 있습니다.
3. 서비스에서 승인 코드를 생성하여 Google에 반환합니다. 해야 할 일 승인 코드를 사용하여 사용자의 브라우저를 Google로 다시 리디렉션합니다. 이 요청에 첨부됩니다.
4. Google은 토큰 교환 엔드포인트로 승인 코드를 전송합니다. 코드의 신뢰성을 확인하고 액세스 토큰과 갱신 토큰을 선택합니다. 액세스 토큰은 사용자 인증 정보로 수락합니다. 갱신 토큰은 새 액세스 토큰을 획득할 때 Google이 저장하고 사용할 수 있는 만료됩니다.
5. 사용자가 계정 연결 흐름을 완료한 후 Google에서 전송한 요청에는 액세스 토큰이 포함됩니다.

승인 요청 처리

OAuth 2.0 승인 코드를 사용하여 계정 연결을 수행해야 하는 경우 Google은 승인 엔드포인트로 에는 다음 매개변수가 포함됩니다.

예를 들어 승인 엔드포인트를 https://myservice.example.com/auth인 경우 요청은 다음과 같을 수 있습니다.

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

승인 엔드포인트가 로그인 요청을 처리하도록 하려면 다음을 수행합니다. 단계:

1. client_id이 Google에 할당한 클라이언트 ID와 일치하고 redirect_uri가 Google에서 서비스에 제공한 리디렉션 URL과 일치하는지 확인합니다. 이러한 확인은 서비스 계정에 의도하지 않거나 잘못 구성된 클라이언트 앱에 액세스할 수 없습니다. 여러 개의 OAuth 2.0 흐름에서 response_type가 code인지도 확인합니다.
2. 사용자가 서비스에 로그인했는지 확인합니다. 사용자가 로그인하지 않은 경우 서비스의 로그인 또는 가입 흐름을 완료할 수 있습니다.
3. Google에서 API에 액세스하는 데 사용할 승인 코드를 생성합니다. 승인 코드는 임의의 문자열 값이 될 수 있지만 고유해야 합니다. 사용자, 토큰의 대상 클라이언트, 코드의 만료 시간을 나타내는 추측할 수 없어야 합니다. 일반적으로 승인을 발행합니다. 코드는 약 10분 후에 만료됩니다.
4. redirect_uri 매개변수로 지정된 URL에 다음 양식을 제출해 주세요.

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. 사용자의 브라우저를 redirect_uri 매개변수 제출한 승인 코드 포함 리디렉션할 때 수정되지 않은 원래 상태 값과 code 및 state 매개변수를 추가합니다. 다음은 결과 URL의 예는 다음과 같습니다.

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

토큰 교환 요청 처리

서비스의 토큰 교환 엔드포인트는 두 가지 종류의 토큰을 담당합니다. 있습니다.

• 승인 코드를 액세스 토큰 및 갱신 토큰으로 교환
• 갱신 토큰을 액세스 토큰으로 교환

토큰 교환 요청에는 다음 매개변수가 포함됩니다.

승인 코드를 액세스 토큰 및 갱신 토큰으로 교환

사용자가 로그인하고 승인 엔드포인트에서 단기 응답을 반환한 후 Google에서 토큰 교환으로 요청을 엔드포인트에서 승인 코드를 액세스 토큰으로 교환하고 토큰입니다.

이러한 요청에서 grant_type 값은 authorization_code이고 code 값은 이전에 부여한 승인 코드의 값입니다. Google에 문의하기 다음은 승인 코드는 다음과 같습니다.

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

승인 코드를 액세스 토큰 및 갱신 토큰으로 교환하려면 토큰 교환 엔드포인트는 다음을 실행하여 POST 요청에 응답합니다. 단계:

1. client_id이 요청 출처를 승인된 출처이고 client_secret가 예상값과 일치하는지 확인합니다.
2. 승인 코드가 유효하고 만료되지 않았는지, 요청에 지정된 클라이언트 ID가 승인 코드가 필요합니다.
3. redirect_uri 매개변수로 지정된 URL이 동일한지 확인 초기 승인 요청에 사용된 값으로 설정합니다.
4. 위의 기준을 모두 확인할 수 없는 경우 {"error": "invalid_grant"}이 본문으로 있는 400 잘못된 요청 오류입니다.
5. 그렇지 않은 경우 승인 코드의 사용자 ID를 사용하여 새로고침을 생성하세요. 액세스 토큰을 만들 수 있습니다 토큰은 임의의 문자열 값이 될 수 있지만 토큰이 대상으로 하는 사용자와 클라이언트를 고유하게 나타내야 하며, 추측할 수 없어야 합니다. 액세스 토큰의 경우 이 시간은 일반적으로 토큰을 발급하고 한 시간 후에 이뤄집니다 갱신 토큰은 만료되지 않습니다.
6. HTTPS 응답 본문에 다음 JSON 객체를 반환합니다.

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Google에서 사용자 및 기록의 액세스 토큰과 갱신 토큰을 저장함 만료되어야 합니다 액세스 토큰이 만료되면 Google은 토큰 교환 엔드포인트에서 새 액세스 토큰을 가져옵니다.

갱신 토큰을 액세스 토큰으로 교환

액세스 토큰이 만료되면 Google에서 토큰 교환으로 요청을 전송합니다. 새 액세스 토큰으로 교환합니다.

이러한 요청에서 grant_type 값은 refresh_token이고 refresh_token는 이전에 부여한 갱신 토큰의 값입니다. Google 다음은 갱신 토큰 교환 요청의 예시입니다. 다음을 수행합니다.

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

갱신 토큰을 액세스 토큰으로 교환하려면 토큰 교환 엔드포인트 다음 단계를 실행하여 POST 요청에 응답합니다.

1. client_id가 요청 출처를 Google로 식별하는지 확인합니다. client_secret가 예상값과 일치하는지 확인합니다.
2. 갱신 토큰이 유효하고 요청이 갱신 토큰과 연결된 클라이언트 ID와 일치하는지 확인합니다.
3. 위의 기준을 모두 확인할 수 없는 경우 HTTP 400을 반환합니다. 본문이 {"error": "invalid_grant"}인 잘못된 요청 오류입니다.
4. 그렇지 않은 경우 갱신 토큰의 사용자 ID를 사용하여 액세스 권한을 생성하세요. 토큰입니다. 토큰은 임의의 문자열 값이 될 수 있지만 고유하게 사용자와 클라이언트를 나타내야 하며 있습니다. 액세스 토큰의 경우 토큰의 만료 시간도 기록합니다. 일반적으로 토큰을 발급하고 1시간 후에
5. HTTPS의 본문에서 다음 JSON 객체를 반환합니다. 응답:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

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.

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:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. 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:

   HTTP/1.1 401 Unauthorized
   WWW-Authenticate: error="invalid_token",
   error_description="The Access Token expired"
   

   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.

3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

   {
   "sub": "USER_UUID",
   "email": "EMAIL_ADDRESS",
   "given_name": "FIRST_NAME",
   "family_name": "LAST_NAME",
   "name": "FULL_NAME",
   "picture": "PROFILE_PICTURE",
   }

   If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

   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.

구현 확인

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击配置 settings 以打开 OAuth 2.0 配置窗口。
2. 在 OAuth flow 字段中，选择 Client-side（客户端）。
3. 在 OAuth 端点字段中，选择自定义。
4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
5. 在第 1 步部分，不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围（如果您不使用 OAuth 范围，则可以输入任意字符串）。完成后，点击授权 API。
6. 在 Step 2 和 Step 3 部分中，完成 OAuth 2.0 流程，并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示版工具验证您的实现。

在该工具中，执行以下步骤：

1. 点击使用 Google 账号登录按钮。
2. 选择您要关联的账号。
3. 输入服务 ID。
4. （可选）输入您要请求访问权限的一个或多个范围。
5. 点击开始演示。
6. 当系统提示时，请确认您同意或拒绝关联请求。
7. 确认您已被重定向到您的平台。