TV 및 제한된 입력 장치 애플리케이션 용 OAuth 2.0

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

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

이 흐름을 사용하는 응용 프로그램은 개별 장치에 배포되므로 앱이 비밀을 유지할 수 없다고 가정합니다. 사용자가 앱에있는 동안 또는 앱이 백그라운드에서 실행 중일 때 Google API에 액세스 할 수 있습니다.

대안

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

전제 조건

프로젝트에 API 사용

Google API를 호출하는 모든 애플리케이션은 API Console에서 해당 API를 활성화해야합니다.

프로젝트에 API를 사용하려면 다음을 수행하십시오.

  1. Google API Console의 Open the API Library.
  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 단계 : 기기 및 사용자 코드 요청

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

매개 변수
client_id 필수

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

scope 필수

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

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

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

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

client_id=client_id&scope=email%20profile

이 예는 동일한 요청을 보내는 curl 명령을 보여줍니다.

curl -d "client_id=client_id&scope=email%20profile" \
     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에 식별하는 대소 문자를 구분하는 값입니다. 사용자 인터페이스는 사용자에게 더 풍부한 입력 기능이있는 별도의 장치에이 값을 입력하도록 지시합니다. 그런 다음 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 단계 : 사용자 코드 표시

디스플레이 verification_urluser_code 사용자에게 2 단계에서 얻을 수 있습니다. 두 값 모두 US-ASCII 문자 집합의 인쇄 가능한 문자를 포함 할 수 있습니다. 당신이 사용자에게 표시하는 내용은로 이동하도록 지시한다 verification_url 별도의 장치에 입력하고 엔터 user_code .

다음 규칙을 염두에두고 사용자 인터페이스 (UI)를 디자인하십시오.

  • user_code
    • user_code 는 15 개의 'W'크기 문자를 처리 할 수있는 필드에 표시되어야합니다. 즉, 코드 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 합니다.

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

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 Files 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 요청을 Google의 인증 서버 ( https://oauth2.googleapis.com/token )로 보냅니다.

필드
client_id API Console에서 얻은 클라이언트 ID입니다.
client_secret API Console에서 얻은 클라이언트 암호입니다.
grant_type OAuth 2.0 사양에 정의 된 refresh_token 필드의 값은 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 요청을 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

Drive 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