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

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

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

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

대안

브라우저 및 전체 입력 기능에 액세스 할 수 있습니다 (유니버설 윈도우 플랫폼 포함) 안드로이드, 아이폰 OS, 맥 OS, 리눅스, 또는 Windows와 같은 플랫폼을위한 응용 프로그램을 작성하는 경우, 사용하는 모바일 및 데스크톱 응용 프로그램의 OAuth 2.0 흐름을 . (앱이 그래픽 인터페이스가 없는 명령줄 도구인 경우에도 해당 흐름을 사용해야 합니다.)

전제 조건

프로젝트에 API 활성화

구글 API를 호출하는 응용 프로그램은에서와 API를 활성화 할 필요가 API Console.

프로젝트에 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가 목록에 표시되지 않으면 사용 검색을 찾거나이 속한 제품군에서 모두보기를 클릭합니다.
  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 요청을 전송 https://oauth2.googleapis.com/device/code , 식별 응용 프로그램뿐만 아니라 액세스 응용 프로그램은 사용자의에 액세스 싶어 스코프로 이익. 당신은에서 URL을 검색해야 검색 문서 사용 device_authorization_endpoint 메타 데이터 값입니다. 다음 HTTP 요청 매개변수를 포함합니다.

매개변수
client_id 필수의

애플리케이션의 클라이언트 ID입니다. 당신은이 값 찾을 수 있습니다 API ConsoleCredentials 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 초 폴링 요청을 보내야합니다. 참조 3 단계 자세한 내용을.
user_code 애플리케이션이 액세스를 요청하는 범위를 Google에 식별하는 대소문자를 구분하는 값입니다. 사용자 인터페이스는 사용자에게 더 풍부한 입력 기능이 있는 별도의 장치에 이 값을 입력하도록 지시합니다. 그런 다음 Google은 사용자에게 애플리케이션에 대한 액세스 권한을 부여하라는 메시지를 표시할 때 값을 사용하여 올바른 범위 집합을 표시합니다.
verification_url 사용자가 별도의 장치에로 이동해야합니다 입력하는 URL user_code 하고 부여 또는 응용 프로그램에 대한 액세스를 거부합니다. 사용자 인터페이스에도 이 값이 표시됩니다.

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

{
  "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 선택적으로 표시 할 계획 제거를 제외하고, 어떤 식 으로든. 당신은 계획 (예를 없애기 계획 할 경우 https:// 표시 이유로 URL에서 있는지 앱이 모두 처리 할 수있는 수) httphttps 변형.

4단계: Google의 인증 서버 폴링

사용자가 탐색 할 별도의 장치를 사용되기 때문에 verification_url 액세스 및 승인 (또는 부인), 요청 장치는 자동으로 액세스 요청을 할 때 사용자의 응답을 통보하지 않는다. 이러한 이유로 요청하는 기기는 사용자가 요청에 응답한 시점을 확인하기 위해 Google의 인증 서버를 폴링해야 합니다.

요청하는 장치는, 사용자가 액세스 요구에 응답 할 때까지 또는 것을 나타내는 응답을 수신 할 때까지 폴링 요청을 전송한다 계속 device_codeuser_code 얻어진 2 단계가 만료한다. interval 요청 사이의 대기 (초) 단계 2 지정 시간을 반환.

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

매개변수
client_id 애플리케이션의 클라이언트 ID입니다. 당신은이 값 찾을 수 있습니다 API ConsoleCredentials page.
client_secret 제공된에 대한 클라이언트의 비밀 client_id . 당신은이 값 찾을 수 있습니다 API ConsoleCredentials page.
device_code device_code 에서 인증 서버에서 반환 2 단계 .
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단계: 사용자가 액세스 요청에 응답

사용자가이를 탐색 할 때 표시되는 내용에 페이지와 유사한 다음 이미지 쇼 verification_url 당신이 표시되는 것을 3 단계 :

코드를 입력하여 장치 연결

유입 후 user_code 이미 로그인 구글에 로그인,하지 않을 경우, 그리고, 사용자는 아래와 같은 동의 화면을 본다 :

디바이스 클라이언트의 동의 화면 예시

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

Google의 인증 서버는 다음 응답 중 하나로 각 폴링 요청에 응답합니다.

액세스 권한 부여

장치에 사용자 부여 액세스 (클릭하여 경우 Allow 동의 화면에서), 다음 응답은 액세스 토큰 및 새로 고침 토큰이 포함되어 있습니다. 토큰은 당신의 장치 수 있도록 구글 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를 호출할 수 있습니다. 이렇게하려면 중 하나를 포함하여 API에 요청에 액세스 토큰이 포함 access_token 쿼리 매개 변수 또는 Authorization HTTP 헤더 Bearer 값입니다. 쿼리 문자열이 서버 로그에 표시되는 경향이 있기 때문에 가능하면 HTTP 헤더를 사용하는 것이 좋습니다. 대부분의 경우 구글 API에 통화를 설정하는 클라이언트 라이브러리를 사용할 수 있습니다 (예를 들어, 드라이브 파일 API를 호출 ).

당신은 모든 구글 API를 시도하고 그들의 범위를 볼 수 OAuth는 2.0 놀이터 .

HTTP GET 예제

받는 호출 drive.files 엔드 포인트 (드라이브 파일 API)를 사용하여 Authorization: Bearer HTTP 헤더는 다음과 같이 보일 수 있습니다. 고유한 액세스 토큰을 지정해야 합니다.

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

여기에 사용하여 인증 된 사용자에 대해 동일한 API를 호출입니다 access_token 쿼리 문자열 매개 변수 :

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 클라이언트 ID가로부터 얻어 API Console.
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 흐름은 다음 범위에서만 지원됩니다.

오픈 ID 연결 , 구글 로그인

  • email
  • openid
  • profile

드라이브 API

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

유튜브 API

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