TV 및 제한적인 입력 기기 애플리케이션을 위한 OAuth 2.0

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 문서에서는 TV, 게임 콘솔, 프린터와 같은 기기에서 실행되는 애플리케이션을 통해 OAuth 2.0 승인을 구현하여 Google API에 액세스하는 방법을 설명합니다. 구체적으로 이 흐름은 브라우저에 액세스할 수 없거나 입력 기능이 제한된 기기를 위해 설계되었습니다.

OAuth 2.0을 사용하면 사용자가 사용자 이름과 비밀번호, 기타 정보를 비공개로 유지하면서 애플리케이션과 특정 데이터를 공유할 수 있습니다. 예를 들어 TV 애플리케이션은 OAuth 2.0을 사용하여 Google Drive에 저장된 파일을 선택할 수 있는 권한을 얻을 수 있습니다.

이 흐름을 사용하는 애플리케이션은 개별 기기에 배포되므로 앱에서 보안 비밀을 유지할 수 없다고 가정합니다. 사용자가 앱에 있거나 앱이 백그라운드에서 실행 중일 때 Google API에 액세스할 수 있습니다.

대안

Android, iOS, macOS, Linux 또는 Windows(범용 Windows 플랫폼 포함)와 같은 플랫폼용 앱을 작성하고 브라우저 및 전체 입력 기능에 액세스할 수 있는 앱을 작성하는 경우 모바일 및 데스크톱 애플리케이션용 OAuth 2.0 흐름을 사용하세요. 앱이 그래픽 인터페이스가 없는 명령줄 도구인 경우에도 이 흐름을 사용해야 합니다.

Google 계정으로 로그인하고 JWT ID 토큰을 사용하여 기본 사용자 프로필 정보를 가져오려면 TV 및 제한된 입력 기기에서 로그인을 참조하세요.

기본 요건

프로젝트에 API 사용 설정

Google API를 호출하는 모든 애플리케이션은 API Console에서 이러한 API를 사용 설정해야 합니다.

프로젝트에 API를 사용 설정하려면 다음 단계를 따르세요.

  1. Open the API Library ( Google API Console)
  2. If prompted, select a project, or create a new one.
  3. API Library 에는 사용 가능한 모든 API가 제품군 및 인기도별로 분류되어 있습니다. 사용 설정하려는 API가 목록에 없는 경우 검색을 사용하여 찾거나 해당 API 제품군이 속한 제품군에서 모두 보기를 클릭합니다.
  4. 사용 설정하려는 API를 선택한 다음 사용 설정 버튼을 클릭합니다.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

승인 사용자 인증 정보 만들기

OAuth 2.0을 사용하여 Google API에 액세스하는 모든 애플리케이션에는 Google OAuth 2.0 서버에 대한 애플리케이션을 식별하는 승인 사용자 인증 정보가 있어야 합니다. 다음 단계에서는 프로젝트의 사용자 인증 정보를 만드는 방법을 설명합니다. 그러면 애플리케이션이 사용자 인증 정보를 사용하여 해당 프로젝트에서 사용 설정한 API에 액세스할 수 있습니다.

  1. Go to the Credentials page.
  2. 사용자 인증 정보 만들기 > OAuth 클라이언트 ID를 클릭합니다.
  3. TV 및 입력 제한 기기 애플리케이션 유형을 선택합니다.
  4. OAuth 2.0 클라이언트 이름을 지정하고 만들기를 클릭합니다.

액세스 범위 확인

범위를 사용하면 애플리케이션에서 필요한 리소스에 대한 액세스만 요청하는 동시에 사용자가 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 획득 가능성 사이에는 반비례적인 관계가 있을 수 있습니다.

OAuth 2.0 승인을 구현하기 전에 앱에 액세스 권한이 필요한 범위를 식별하는 것이 좋습니다.

설치된 앱 또는 기기는 허용된 범위 목록을 참조하세요.

OAuth 2.0 액세스 토큰 가져오기

애플리케이션이 입력 기능이 제한된 기기에서 실행되더라도 사용자는 이 승인 절차를 완료하려면 입력 기능이 더 풍부한 기기에 별도의 액세스 권한이 있어야 합니다. 흐름의 단계는 다음과 같습니다.

  1. 애플리케이션에서 Google에 액세스 권한을 요청하는 범위를 식별하는 승인 서버에 요청을 보냅니다.
  2. 서버는 후속 단계에서 사용되는 기기 정보, 사용자 코드 등 몇 가지 정보를 통해 응답합니다.
  3. 사용자가 앱을 승인하기 위해 별도의 기기에 입력할 수 있는 정보를 표시합니다.
  4. 애플리케이션에서 Google의 인증 서버를 폴링하여 사용자가 앱을 승인했는지 확인합니다.
  5. 사용자가 입력 기능이 더 풍부한 기기로 전환한 후 웹브라우저를 실행하고 3단계에 표시된 URL로 이동하여 3단계에도 표시되는 코드를 입력합니다. 그러면 사용자는 애플리케이션에 대한 액세스 권한을 부여 (또는 거부)할 수 있습니다.
  6. 폴링 요청에 대한 다음 응답에는 앱에서 사용자를 대신하여 요청을 승인하는 데 필요한 토큰이 포함됩니다. (사용자가 애플리케이션에 대한 액세스를 거부한 경우 응답에 토큰이 포함되지 않습니다.)

아래 이미지는 이 프로세스를 보여줍니다.

사용자가 브라우저가 있는 별도의 기기에 로그인

다음 섹션에서는 이러한 단계를 자세히 설명합니다. 다양한 기능 및 런타임 환경이 기기에 있을 수 있다는 점을 고려하여 이 문서에 표시된 예에서는 curl 명령줄 유틸리티를 사용합니다. 이러한 예는 다양한 언어 및 런타임으로 쉽게 포팅할 수 있어야 합니다.

1단계: 기기 및 사용자 코드 요청

이 단계에서는 기기가 사용자 및 애플리케이션이 사용자를 대신하여 액세스하려는 액세스 범위를 식별하는 HTTP POST 요청을 Google의 인증 서버(https://oauth2.googleapis.com/device/code)로 보냅니다. device_authorization_endpoint 메타데이터 값을 사용하여 검색 문서에서 이 URL을 검색해야 합니다. 다음 HTTP 요청 매개변수를 포함하세요.

매개변수
client_id 필수

애플리케이션의 클라이언트 ID입니다. 이 값은 API Console Credentials page에서 확인할 수 있습니다.

scope 필수

애플리케이션이 사용자를 대신하여 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위 목록입니다. 이러한 값은 Google에서 사용자에게 표시하는 동의 화면에 알립니다. 설치된 앱 또는 기기는 허용된 범위 목록을 참조하세요.

범위를 사용하면 애플리케이션에서 필요한 리소스에 대한 액세스만 요청할 수 있으며, 사용자가 애플리케이션에 부여하는 액세스 양을 제어할 수 있습니다. 따라서 요청된 범위 수와 사용자 동의 획득 가능성 사이에는 반비례적인 관계가 있습니다.

Examples

다음 스니펫은 샘플 요청을 보여줍니다.

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=

이 예시에서는 동일한 요청을 보내는 curl 명령어를 보여줍니다.

curl -d "client_id=client_id&scope=" \
     https://oauth2.googleapis.com/device/code

2단계: 승인 서버 응답 처리하기

승인 서버는 다음 응답 중 하나를 반환합니다.

성공 응답

요청이 유효하면 응답이 다음 속성이 포함된 JSON 객체가 됩니다.

속성
device_code 승인을 요청하는 앱을 실행하는 기기를 식별하기 위해 Google에서 고유하게 할당하는 값입니다. 사용자가 더 풍부한 입력 기능을 갖춘 다른 기기에서 기기를 승인합니다. 예를 들어 사용자는 TV에서 실행 중인 앱을 승인하기 위해 노트북이나 휴대전화를 사용할 수 있습니다. 이 경우 device_code은 TV를 식별합니다.

이 코드를 사용하면 앱을 실행하는 기기가 사용자가 액세스 권한을 부여했는지 또는 거부했는지 안전하게 판단할 수 있습니다.

expires_in device_codeuser_code가 유효한 시간(초)입니다. 그렇게 해도 사용자가 승인 절차를 완료하지 않고 기기에서 사용자의 결정 정보를 검색하기 위해 설문조사도 하지 않는 경우 1단계부터 이 프로세스를 다시 시작해야 할 수도 있습니다.
interval 기기에서 폴링 요청 간에 대기해야 하는 시간(초)입니다. 예를 들어 값이 5이면 기기에서 5초마다 폴링 요청을 Google 승인 서버에 전송해야 합니다. 자세한 내용은 3단계를 참고하세요.
user_code 애플리케이션에서 액세스를 요청하는 범위를 Google에 식별하는 대소문자를 구분하는 값입니다. 사용자 인터페이스에서는 사용자에게 입력 기능이 더 풍부한 별도의 기기에 이 값을 입력하도록 지시합니다. 그런 다음 이 값을 사용하여 사용자에게 애플리케이션 액세스 권한을 부여하라는 메시지를 표시할 때 올바른 범위 집합을 표시합니다.
verification_url 사용자가 별도의 기기에서 user_code를 입력하고 애플리케이션에 대한 액세스를 부여하거나 거부해야 하는 URL입니다. 사용자 인터페이스에도 이 값이 표시됩니다.

다음 스니펫은 샘플 응답을 보여줍니다.

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

할당량 초과 응답

기기 코드 요청이 클라이언트 ID와 관련된 할당량을 초과하면 다음 오류가 포함된 403 응답이 표시됩니다.

{
  "error_code": "rate_limit_exceeded"
}

이 경우 백오프 전략을 사용하여 요청 속도를 줄이세요.

3단계: 사용자 코드 표시하기

2단계에서 가져온 verification_urluser_code을 사용자에게 표시합니다. 두 값 모두 US-ASCII 문자 집합의 인쇄 가능한 문자를 포함할 수 있습니다. 사용자에게 표시하는 콘텐츠는 사용자에게 별도의 기기에서 verification_url로 이동하여 user_code를 입력하도록 안내해야 합니다.

다음 규칙을 염두에 두고 사용자 인터페이스 (UI)를 디자인합니다.

  • user_code
    • 15 'W' 크기 문자를 처리할 수 있는 필드에 user_code를 표시해야 합니다. 즉, WWWWWWWWWWWWWWW 코드를 올바르게 표시할 수 있다면 UI가 유효하므로 user_code가 UI에 표시되는 방식을 테스트할 때 이 문자열 값을 사용하는 것이 좋습니다.
    • user_code는 대소문자를 구분하며 대소문자를 변경하거나 다른 형식 문자를 입력하는 등 어떠한 방식으로도 수정해서는 안 됩니다.
  • verification_url
    • verification_url을 표시하는 공간은 너비가 40자인 URL 문자열을 처리할 만큼 충분히 넓어야 합니다.
    • 선택적으로 표시 체계를 삭제하는 경우를 제외하고 verification_url를 어떤 식으로든 수정해서는 안 됩니다. 표시 이유로 URL에서 스키마(예: https://)를 삭제할 계획이라면 앱에서 httphttps 변형을 모두 처리할 수 있는지 확인해야 합니다.

4단계: Google 승인 서버 설문조사

사용자가 별도의 기기를 사용하여 verification_url로 이동하고 액세스를 부여 (또는 거부)하므로 사용자가 액세스 요청에 응답해도 요청 기기에 자동으로 알림이 전송되지 않습니다. 따라서 요청한 기기가 Google의 인증 서버를 폴링하여 사용자가 요청에 응답한 시점을 확인해야 합니다.

요청 기기는 사용자가 액세스 요청에 응답했음을 나타내거나 2단계에서 가져온 device_codeuser_code가 만료될 때까지 폴링 요청을 계속 전송해야 합니다. 2단계에서 반환된 interval는 요청 간에 대기하는 시간(초)을 지정합니다.

폴링할 엔드포인트의 URL은 https://oauth2.googleapis.com/token입니다. 폴링 요청에는 다음 매개변수가 포함됩니다.

매개변수
client_id 애플리케이션의 클라이언트 ID입니다. 이 값은 API Console Credentials page에서 확인할 수 있습니다.
client_secret 제공된 client_id의 클라이언트 보안 비밀 이 값은 API Console Credentials page에서 확인할 수 있습니다.
device_code 2단계의 승인 서버에서 반환한 device_code
grant_type 이 값을 urn:ietf:params:oauth:grant-type:device_code로 설정합니다.

Examples

다음 스니펫은 샘플 요청을 보여줍니다.

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

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

이 예시에서는 동일한 요청을 보내는 curl 명령어를 보여줍니다.

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         /token

5단계: 사용자가 액세스 요청에 응답하기

다음 이미지는 3단계에서 표시된 verification_url로 이동할 때 사용자에게 표시되는 것과 비슷한 페이지를 보여줍니다.

코드를 입력하여 기기 연결

user_code에 들어가고 아직 로그인하지 않았다면 Google에 로그인하면 아래와 같은 동의 화면이 사용자에게 표시됩니다.

기기 클라이언트의 동의 화면 예

6단계: 폴링 요청에 대한 응답 처리

Google의 인증 서버는 각 설문조사 요청에 대해 다음 응답 중 하나로 응답합니다.

액세스 권한이 부여됨

사용자가 동의 화면에서 Allow를 클릭하여 기기에 액세스 권한을 부여한 경우 응답에 액세스 토큰과 갱신 토큰이 포함됩니다. 토큰을 사용하여 기기에서 사용자를 대신하여 Google API에 액세스할 수 있습니다. 응답의 scope 속성은 기기에서 액세스할 수 있는 API를 결정합니다.

이 경우 API 응답에 다음 필드가 포함됩니다.

필드
access_token Google API 요청을 승인하기 위해 애플리케이션에서 전송하는 토큰입니다.
expires_in 액세스 토큰의 남은 기간(초)입니다.
refresh_token 새 액세스 토큰을 얻는 데 사용할 수 있는 토큰입니다. 갱신 토큰은 사용자가 액세스 권한을 취소할 때까지 유효합니다. 갱신 토큰은 항상 기기에 대해 반환됩니다.
scope access_token에서 부여하는 액세스 범위이며 공백으로 구분된 대소문자를 구분하는 문자열 목록으로 표현됩니다.
token_type 반환된 토큰의 유형입니다. 현재 이 필드의 값은 항상 Bearer로 설정되어 있습니다.

다음 스니펫은 샘플 응답을 보여줍니다.

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

액세스 토큰의 전체 기간은 제한되어 있습니다. 애플리케이션에서 장기간 API에 액세스해야 하는 경우 갱신 토큰을 사용하여 새 액세스 토큰을 얻을 수 있습니다. 애플리케이션에 이러한 유형의 액세스 권한이 필요하다면 나중에 사용할 수 있도록 갱신 토큰을 저장해야 합니다.

액세스 거부됨

사용자가 기기에 대한 액세스 권한 부여를 거부하는 경우 서버 응답에 403 HTTP 응답 상태 코드(Forbidden)가 있습니다. 응답에 다음 오류가 포함됩니다.

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

승인 대기 중

사용자가 아직 승인 과정을 완료하지 않은 경우 서버에서 428 HTTP 응답 상태 코드(Precondition Required)를 반환합니다. 응답에 다음 오류가 포함되어 있습니다.

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

설문조사가 너무 많음

기기에서 폴링 요청을 너무 자주 전송하면 서버에서 403 HTTP 응답 상태 코드(Forbidden)를 반환합니다. 응답에는 다음 오류가 포함됩니다.

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

기타 오류

또한 조사 요청에 필수 매개변수가 누락되었거나 매개변수 값이 잘못된 경우에도 인증 서버가 오류를 반환합니다. 이러한 요청은 일반적으로 400(Bad Request) 또는 401 (Unauthorized) HTTP 응답 상태 코드를 갖습니다. 이러한 오류의 예는 다음과 같습니다.

오류 HTTP 상태 코드 설명
invalid_client 401 OAuth 클라이언트를 찾을 수 없습니다. 예를 들어 client_id 매개변수 값이 잘못된 경우 이 오류가 발생합니다.
invalid_grant 400 code 매개변수 값이 잘못되었습니다.
unsupported_grant_type 400 grant_type 매개변수 값이 잘못되었습니다.

Google API 호출

애플리케이션이 액세스 토큰을 획득한 후 API에 필요한 액세스 범위가 부여된 경우 특정 사용자 계정을 대신하여 Google API를 호출하는 데 토큰을 사용할 수 있습니다. 이를 위해 access_token 쿼리 매개변수 또는 Authorization HTTP 헤더 Bearer 값을 포함하여 API 요청에 액세스 토큰을 포함합니다. 쿼리 문자열은 서버 로그에 표시되는 경향이 있으므로 HTTP 헤더를 사용하는 것이 좋습니다. 대부분의 경우 클라이언트 라이브러리를 사용하여 Google API 호출을 설정할 수 있습니다 (예: Drive 파일 API 호출).

OAuth 2.0 Playground에서 모든 Google API를 사용해 보고 범위를 확인할 수 있습니다.

HTTP GET 예시

Authorization: Bearer HTTP 헤더를 사용한 drive.files 엔드포인트 (Drive Files API) 호출은 다음과 같습니다. 다음과 같이 자체 액세스 토큰을 지정해야 합니다.

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

다음은 access_token 쿼리 문자열 매개변수를 사용하여 인증된 사용자를 대상으로 동일한 API를 호출한 내역입니다.

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl

이 명령어는 curl 명령줄 애플리케이션으로 테스트할 수 있습니다. 다음은 HTTP 헤더 옵션을 사용하는 예입니다 (권장).

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

또는 쿼리 문자열 매개변수 옵션을 선택할 수도 있습니다.

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

액세스 토큰 갱신

액세스 토큰은 주기적으로 만료되어 관련 API 요청에 대해 잘못된 사용자 인증 정보가 됩니다. 토큰과 연결된 범위에 대한 오프라인 액세스를 요청한 경우 사용자에게 권한을 요청하지 않고 (사용자가 없는 경우 포함) 액세스 토큰을 새로고침할 수 있습니다.

액세스 토큰을 새로고침하기 위해 애플리케이션은 다음 매개변수를 포함하는 HTTPS POST 요청을 승인 서버(https://oauth2.googleapis.com/token)로 전송합니다.

필드
client_id API Console에서 가져온 클라이언트 ID입니다.
client_secret API Console에서 가져온 클라이언트 보안 비밀번호
grant_type OAuth 2.0 사양에 정의된 대로 이 필드의 값을 refresh_token로 설정해야 합니다.
refresh_token 승인 코드 교환에서 반환된 갱신 토큰입니다.

다음 스니펫은 샘플 요청을 보여줍니다.

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

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

사용자가 애플리케이션에 부여된 액세스 권한을 취소하지 않는 한 토큰 서버는 새 액세스 토큰이 포함된 JSON 객체를 반환합니다. 다음 스니펫은 샘플 응답을 보여줍니다.

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

발급될 갱신 토큰 수에는 제한이 있습니다. 하나는 클라이언트/사용자 조합당 한 개이며, 다른 하나는 모든 클라이언트에서 사용자에게 적용됩니다. 갱신 토큰을 장기 저장소에 저장하고 유효한 기간 동안 계속 사용해야 합니다. 애플리케이션에서 갱신 토큰을 너무 많이 요청하면 이 한도에 도달할 수 있으며, 이러한 경우 이전 갱신 토큰이 작동하지 않습니다.

토큰 취소

때에 따라 사용자는 애플리케이션에 부여된 액세스 권한을 취소하려고 할 수 있습니다. 사용자는 계정 설정으로 이동하여 액세스 권한을 취소할 수 있습니다. 자세한 내용은 계정 액세스 권한이 있는 타사 사이트 및 앱 또는 사이트의 액세스 권한 삭제 섹션 지원 문서를 참고하세요.

애플리케이션이 지정된 액세스 권한을 프로그래매틱 방식으로 취소할 수도 있습니다. 사용자가 구독을 취소하거나 애플리케이션을 삭제하거나 앱에서 필요한 API 리소스가 크게 변경된 경우 프로그래매틱 해지가 중요합니다. 즉, 이전에 애플리케이션에 부여된 권한이 삭제되도록 하는 API 요청이 삭제 프로세스의 일부에 포함될 수 있습니다.

프로그래매틱 방식으로 토큰을 취소하기 위해 애플리케이션은 https://oauth2.googleapis.com/revoke을 요청하고 토큰을 매개변수로 포함합니다.

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

토큰은 액세스 토큰 또는 갱신 토큰일 수 있습니다. 토큰이 액세스 토큰이고 해당하는 갱신 토큰이 있으면 갱신 토큰도 취소됩니다.

취소가 성공적으로 처리된 경우 응답의 HTTP 상태 코드는 200입니다. 오류 조건에서는 HTTP 상태 코드 400이 오류 코드와 함께 반환됩니다.

허용된 범위

기기의 OAuth 2.0 흐름은 다음 범위에서만 지원됩니다.

OpenID Connect, Google 로그인

  • email
  • openid
  • profile

드라이브 API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly