OAuth 2.0 서버 구현

모든 Cloud-to-cloud 통합에는 사용자를 인증하기 위한 메커니즘이 포함되어야 합니다.

인증을 사용하면 사용자의 Google 계정을 인증 시스템의 사용자 계정에 연결할 수 있습니다. 이렇게 하면 처리에서 스마트 홈 인텐트를 수신할 때 사용자를 식별할 수 있습니다. Google 스마트 홈은 승인 코드 흐름이 있는 OAuth만 지원합니다.

이 페이지에서는 Cloud-to-cloud 통합과 호환되도록 OAuth 2.0 서버를 설정하는 방법을 설명합니다.

OAuth를 통한 Google 계정 연결

승인 코드 흐름에는 두 개의 엔드포인트가 필요합니다.

  • authorization 엔드포인트: 아직 로그인하지 않은 사용자에게 로그인 UI를 표시합니다. 승인 엔드포인트는 요청된 액세스에 대한 사용자의 동의를 기록하는 단기 승인 코드도 만듭니다.

  • 2가지 유형의 교환을 담당하는 토큰 교환 엔드포인트:

    1. 승인 코드를 수명이 긴 갱신 토큰과 단기 액세스 토큰으로 교환합니다. 이러한 교환은 사용자가 계정 연결 과정을 거칠 때 발생합니다.
    2. 수명이 긴 갱신 토큰을 수명이 짧은 액세스 토큰으로 교환합니다. 액세스 토큰이 만료되어 Google에서 새 액세스 토큰이 필요할 때 교환이 발생합니다.

디자인 가이드라인

이 섹션에서는 OAuth 연결 흐름을 호스팅하는 사용자 화면의 설계 요구사항과 권장사항을 설명합니다. Google 앱에서 호출한 후 플랫폼에는 Google 페이지에 로그인 및 사용자에게 동의 화면을 연결하는 계정이 표시됩니다. 사용자가 계정 연결에 동의한 후 Google 앱으로 다시 리디렉션됩니다.

이 그림은 사용자가 Google 계정을 인증 시스템에 연결하는 단계를 보여줍니다. 첫 번째 스크린샷은 플랫폼에서 사용자가 시작한 연결을 보여줍니다. 두 번째 이미지는 사용자가 Google에 로그인하는 과정을 보여주며, 세 번째 이미지는 사용자의 Google 계정을 앱과 연결하는 것에 대한 사용자 동의 및 확인을 보여줍니다. 마지막 스크린샷은 Google 앱에서 성공적으로 연결된 사용자 계정을 보여줍니다.
그림 1. 계정 연결 사용자가 Google에 로그인한 화면과 동의 화면

요구사항

  1. 사용자의 계정이 Google Home이나 Google 어시스턴트와 같은 특정 Google 제품이 아니라 Google에 연결됨을 알려야 합니다.
  2. '로그인하면 Google에서 기기를 제어하도록 승인하는 것으로 간주됩니다.'와 같은 Google 승인 문구가 있어야 합니다. Google Home 개발자 정책의 Google 기기 제어 승인 섹션을 참고하세요.
  3. 사용자가 연결하지 않기로 한 경우 뒤로 돌아가거나 취소할 수 있는 방법을 제공해야 합니다.
  4. 웹 OAuth 연결 페이지를 열고 사용자에게 사용자 이름 및 비밀번호 필드와 같이 Google 계정에 로그인할 수 있는 명확한 방법이 있는지 확인해야 합니다. 사용자가 웹 OAuth 연결 페이지로 이동하지 않고도 연결할 수 있도록 하는 Google 로그인 (GSI) 방법을 사용해서는 안 됩니다. 이러한 행위는 Google 정책에 위배됩니다.

권장사항

다음을 수행하는 것이 좋습니다.

  1. Google 개인정보처리방침을 표시합니다. 동의 화면에 Google 개인정보처리방침 링크를 포함합니다.

  2. 공유할 데이터. 명확하고 간결한 표현을 사용하여 Google에 필요한 데이터와 이유를 사용자에게 안내합니다.

  3. 명확한 클릭 유도 문구. 동의 화면에 '동의 및 연결'과 같은 명확한 클릭 유도 문구를 명시합니다. 이는 사용자가 계정을 연결하기 위해 Google과 공유해야 하는 데이터를 이해해야 하기 때문입니다.

  4. 연결 해제 기능. 플랫폼의 계정 설정으로 연결되는 URL과 같이 사용자가 연결을 해제할 수 있는 메커니즘을 제공합니다. 또는 사용자가 연결된 계정을 관리할 수 있는 Google 계정 링크를 포함할 수 있습니다.

  5. 사용자 계정 변경 기능. 사용자가 계정을 전환하는 방법을 제안합니다. 사용자가 여러 계정을 사용하는 경향이 있는 경우 특히 유용합니다.

    • 사용자가 계정을 전환하기 위해 동의 화면을 닫아야 하는 경우 복구 가능한 오류를 Google에 전송하여 사용자가 OAuth 연결을 통해 원하는 계정에 로그인할 수 있도록 합니다.

  6. 로고를 포함하세요. 동의 화면에 회사 로고를 표시합니다. 스타일 가이드라인을 사용하여 로고를 배치합니다. Google 로고도 표시하려면 로고 및 상표를 참조하세요.

승인 코드 흐름

An OAuth 2.0 server implementation of the authorization code flow consists of two endpoints, which your service makes available by HTTPS. The first endpoint is the authorization endpoint, which is responsible for finding or obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access. The second endpoint is the token exchange endpoint, which is used to obtain encrypted strings, called tokens, that authorize a user to access your service.

When a Google application needs to call one of your service's APIs, Google uses these endpoints together to get permission from your users to call these APIs on their behalf.

An OAuth 2.0 authorization code flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. If the flow started on a voice-only device for an Action, Google transfers the execution to a phone.
  2. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
  3. Your service creates an authorization code and returns it to Google. To do so, redirect the user's browser back to Google with the authorization code attached to the request.
  4. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an access token and a refresh token. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.
  5. After the user has completed the account linking flow, every subsequent request sent from Google contains an access token.

Handle authorization requests

When you need to perform account linking using the OAuth 2.0 authorization code flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The Client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
scope Optional: A space-delimited set of scope strings that specify the data Google is requesting authorization for.
response_type The type of value to return in the response. For the OAuth 2.0 authorization code flow, the response type is always code.
user_locale The Google Account language setting in RFC5646 format, used to localize your content in the user's preferred language.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

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

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify that the client_id matches the Client ID you assigned to Google, and that the redirect_uri matches the redirect URL provided by Google for your service. These checks are important to prevent granting access to unintended or misconfigured client apps. If you support multiple OAuth 2.0 flows, also confirm that the response_type is code.
  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.
  3. Generate an authorization code for Google to use to access your API. The authorization code can be any string value, but it must uniquely represent the user, the client the token is for, and the code's expiration time, and it must not be guessable. You typically issue authorization codes that expire after approximately 10 minutes.
  4. Confirm that the URL specified by the redirect_uri parameter has the following form: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
  5. Redirect the user's browser to the URL specified by the redirect_uri parameter. Include the authorization code you just generated and the original, unmodified state value when you redirect by appending the code and state parameters. The following is an example of the resulting URL: 
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Handle token exchange requests

Your service's token exchange endpoint is responsible for two kinds of token exchanges:

  • Exchange authorization codes for access tokens and refresh tokens
  • Exchange refresh tokens for access tokens

Token exchange requests include the following parameters:

Token exchange endpoint parameters
client_id A string that identifies the request origin as Google. This string must be registered within your system as Google's unique identifier.
client_secret A secret string that you registered with Google for your service.
grant_type The type of token being exchanged. It's either authorization_code or refresh_token.
code When grant_type=authorization_code, this parameter is the code Google received from either your sign-in or token exchange endpoint.
redirect_uri When grant_type=authorization_code, this parameter is the URL used in the initial authorization request.
refresh_token When grant_type=refresh_token, this parameter is the refresh token Google received from your token exchange endpoint.

Configure how Google sends credentials to your server

Depending on its implementation, your authorization server expects to receive client credentials either in the request body, or in the request header.

By default, Google sends the credentials in the request body. If your authorization server requires the client credentials to be in the request header, you must configure your Cloud-to-cloud integration accordingly:

Go to the Developer Console

  1. From the list of projects, click Open next to the project you want to work with.

  2. Under Cloud-to-Cloud, select Develop.

  3. Click Open next your integration.

  4. Scroll down to the Permissions (optional) section and select the Have Google transmit Client ID and secret via HTTP basic auth header checkbox.

  5. Click Save to save your changes.

Exchange authorization codes for access tokens and refresh tokens

After the user signs in and your authorization endpoint returns a short-lived authorization code to Google, Google sends a request to your token exchange endpoint to exchange the authorization code for an access token and a refresh token.

For these requests, the value of grant_type is authorization_code, and the value of code is the value of the authorization code you previously granted to Google. The following is an example of a request to exchange an authorization code for an access token and a refresh token:

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

To exchange authorization codes for an access token and a refresh token, your token exchange endpoint responds to POST requests by executing the following steps:

  1. Verify that the client_id identifies the request origin as an authorized origin, and that the client_secret matches the expected value.
  2. Verify that the authorization code is valid and not expired, and that the client ID specified in the request matches the client ID associated with the authorization code.
  3. Confirm that the URL specified by the redirect_uri parameter is identical to the value used in the initial authorization request.
  4. If you can't verify all of the above criteria, return an HTTP 400 Bad Request error with {"error": "invalid_grant"} as the body.
  5. Otherwise, use the user ID from the authorization code to generate a refresh token and an access token. These tokens can be any string value, but they must uniquely represent the user and the client the token is for, and they must not be guessable. For access tokens, also record the expiration time of the token, which is typically an hour after you issue the token. Refresh tokens don't expire.
  6. Return the following JSON object in the body of the HTTPS response: 
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google stores the access token and the refresh token for the user and records the expiration of the access token. When the access token expires, Google uses the refresh token to get a new access token from your token exchange endpoint.

Exchange refresh tokens for access tokens

When an access token expires, Google sends a request to your token exchange endpoint to exchange a refresh token for a new access token.

For these requests, the value of grant_type is refresh_token, and the value of refresh_token is the value of the refresh token you previously granted to Google. The following is an example of a request to exchange a refresh token for an access token:

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

To exchange a refresh token for an access token, your token exchange endpoint responds to POST requests by executing the following steps:

  1. Verify that the client_id identifies the request origin as Google, and that the client_secret matches the expected value.
  2. Verify that the refresh token is valid, and that the client ID specified in the request matches the client ID associated with the refresh token.
  3. If you can't verify all of the above criteria, return an HTTP 400 Bad Request error with {"error": "invalid_grant"} as the body.
  4. Otherwise, use the user ID from the refresh token to generate an access token. These tokens can be any string value, but they must uniquely represent the user and the client the token is for, and they must not be guessable. For access tokens, also record the expiration time of the token, typically an hour after you issue the token.
  5. Return the following JSON object in the body of the HTTPS response: 
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

사용자 정보 요청 처리

userinfo 엔드포인트는 연결된 사용자에 대한 클레임을 반환하는 OAuth 2.0 보호 리소스입니다. 다음 사용 사례를 제외하고 userinfo 엔드포인트를 구현하고 호스팅하는 것은 선택사항입니다.

토큰 엔드포인트에서 액세스 토큰을 성공적으로 가져오면 Google은 사용자 정보 엔드포인트에 요청을 보내 연결된 사용자에 대한 기본 프로필 정보를 가져옵니다.

사용자 정보 엔드포인트 요청 헤더
Authorization header Bearer 유형의 액세스 토큰입니다.

예를 들어 https://myservice.example.com/userinfo인 경우 요청은 다음과 같을 수 있습니다.

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

userinfo 엔드포인트에서 요청을 처리하려면 다음 단계를 수행합니다.

  1. 승인 헤더에서 액세스 토큰을 추출하고 액세스 토큰과 연결된 사용자의 정보를 반환합니다.
  2. 액세스 토큰이 유효하지 않은 경우 WWW-Authenticate 응답 헤더를 사용하여 HTTP 401 승인되지 않은 오류를 반환합니다. 다음은 userinfo 오류 응답의 예입니다. 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    연결 과정 중에 401 승인되지 않음 또는 기타 실패한 오류 응답이 반환되면 오류는 복구할 수 없으며 검색된 토큰은 삭제되며 사용자는 연결 프로세스를 다시 시작해야 합니다.

  3. 액세스 토큰이 유효하면 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 엔드포인트가 HTTP 200 성공 응답을 반환하는 경우 가져온 토큰과 클레임은 사용자의 Google 계정에 등록됩니다.

    사용자 정보 엔드포인트 응답
    sub 시스템에서 사용자를 식별하는 고유 ID
    email 사용자의 이메일 주소입니다.
    given_name 선택사항: 사용자의 이름입니다.
    family_name 선택사항: 사용자의 성.
    name 선택사항: 사용자의 전체 이름입니다.
    picture 선택사항: 사용자의 프로필 사진입니다.
이전
개발자 체크리스트
다음
Cloud-to-Cloud 프로젝트 만들기