OAuth 2.0 Flow: Devices

OAuth 2.0 흐름은 게임 콘솔 또는 비디오 카메라와 같은 제한된 입력 기능을 가진 기기에서 실행되는 애플리케이션용으로 설계되었습니다. 이 흐름에서 사용자는 기기의 애플리케이션과 상호작용하여 URL 및 기기 코드를 받습니다. 그런 다음 컴퓨터나 스마트폰 같은 다양한 입력 기능을 가진 다른 기기로 전환하여 기기 코드를 인증합니다.

Important: You need to obtain authorization credentials in the Google API Console to be able to use OAuth 2.0 authorization.

This document contains the following sections:

Obtaining OAuth 2.0 access tokens

이 흐름의 단계는 다음과 같습니다.

  1. 애플리케이션에 client_idclient_secret 포함

    Google에 애플리케이션을 등록한 후 등록 과정에서 생성된 client IDclient secret을 애플리케이션에 포함해야 합니다. 두 값 모두 Google APIs console에서 확인할 수 있습니다.

  2. 기기 코드 요청

    기기에서 Google 인증 서버(https://accounts.google.com/o/oauth2/device/code)로 POST 요청을 전송하며, 이 요청으로 다음 매개변수를 지정합니다.

    매개변수
    client_id 필수 항목. 애플리케이션의 OAuth 2.0 클라이언트 ID입니다.
    scope 필수 항목. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다.

    다음은 기기 코드 검색 방법을 보여주는 샘플 요청입니다.

    POST /o/oauth2/device/code HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    scope=https://www.googleapis.com/auth/youtube
    
  3. Google의 응답 처리

    Google은 기기에 JSON 개체를 반환함으로써 요청에 응답합니다. 샘플 응답은 아래와 같습니다.

    {
      "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
      "user_code" : "a9xfwk9c",
      "verification_url" : "http://www.google.com/device",
      "expires_in" : "1800"
      "interval" : 5,
    }
    

    기기의 애플리케이션은 user_codeverification_url을 사용자에게 표시해야 하며, 4단계에서 사용할 device_code, expires_in, interval 값을 저장해야 합니다.

  4. Google 인증 서버 폴링 시작

    애플리케이션은 3단계의 JSON 응답에서 반환된 device_code를 사용하여 Google 인증 서버 폴링을 시작할 수 있습니다. 이를 시작하기 위해 애플리케이션에서 POST 요청을 다음 키-값 쌍을 지정하는 https://accounts.google.com/o/oauth2/token으로 전송합니다.

    client_id 애플리케이션의 OAuth 2.0 클라이언트 ID입니다.
    client_secret 클라이언트 ID와 연결된 클라이언트 비밀번호로, 이 값은 Google APIs console에 표시됩니다.
    code 3단계에서 받은 기기 코드입니다.
    grant_type 이 값은 http://oauth.net/grant_type/device/1.0으로 설정합니다.

    다음은 샘플 폴링 요청입니다. 3단계의 JSON 응답에서 반환된 interval은 최소 시간을 초 단위로 지정하며, 이는 애플리케이션이 폴링 요청 간에 대기해야 하는 시간을 의미합니다.

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
    code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
    grant_type=http://oauth.net/grant_type/device/1.0
    

    사용자가 5단계에서 7단계까지 완료할 때까지 애플리케이션은 각 폴링 요청별로 아래 응답 중 하나를 받게 됩니다.

    • 다음 응답은 사용자가 기기에 대한 API 액세스 권한을 부여하는 단계를 아직 완료하지 않았음을 나타냅니다.

      {
        "error" : "authorization_pending"
      }
      
    • 다음 응답은 애플리케이션이 폴링 요청을 너무 자주 전송하고 있음을 나타냅니다.

      {
        "error" : "slow_down"
      }
      
  5. 사용자가 별도의 브라우저에 user_code 입력

    사용자가 컴퓨터나 휴대전화 등 다른 기기에서 브라우저를 실행한 후 verification_url로 이동합니다. 이 URL은 사용자가 3단계에서 받은 user_code를 입력할 수 있는 페이지를 표시합니다.

    참고: user_code는 대소문자를 구분하므로 응답에 표시된 대로 정확하게 입력해야 합니다.

  6. 사용자가 Google 계정에 로그인

    user_code를 입력하면 기기의 YouTube Data API 요청을 인증하는 데 사용할 Google 계정에 로그인하라는 메시지가 표시됩니다. (이미 로그인한 사용자는 다음 단계로 바로 이동합니다.)

  7. 폴링 서버의 응답을 처리하여 토큰 받기

    사용자가 애플리케이션에 대한 액세스 권한을 부여하면 기기에서 전송하는 다음 폴링 요청은 액세스 토큰 및 갱신 토큰이 포함된 JSON 개체를 반환합니다.

    {
      "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
      "expires_in":3920,
      "token_type":"Bearer",
      "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
    }
    

    중요: 애플리케이션은 두 값을 모두 저장해야 합니다.

    • YouTube Data API 호출 섹션에서는 액세스 토큰을 사용하여 인증된 요청을 제출하는 방법을 설명합니다.

    • 액세스 토큰 갱신 섹션에서는 현재 보유 중인 토큰이 만료되는 경우 갱신 토큰을 사용하여 새 액세스 토큰을 받는 방법을 설명합니다.

YouTube Data API 를 호출

애플리케이션에서 사용자에 대한 액세스 토큰을 받은 후, 이 토큰으로 사용자를 대신하여 인증된 API 요청을 제출할 수 있습니다. API는 다음과 같은 두 가지 방법으로 액세스 토큰을 지정합니다.

  1. 액세스 토큰을 Authorization: Bearer HTTP 요청 헤더 값으로 지정합니다. 권장 방법입니다.

    GET /youtube/v3/channels?part=id&mine=true HTTP/1.1
    Host: www.googleapis.com
    Authorization: Bearer ACCESS_TOKEN
    ...
    

    다음 명령을 포함한 cURL을 사용하여 테스트할 수 있습니다.

    curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true
    
  2. 액세스 토큰을 access_token 쿼리 매개변수 값으로 지정합니다.

    https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

    다음 명령을 포함한 cURL을 사용하여 테스트할 수 있습니다.

    curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN
    

만료되었거나 가짜이거나 범위가 잘못되었거나 기타 다른 이유로 유효하지 않은 액세스 토큰으로 보호된 리소스에 액세스하기 위한 요청을 제출하는 경우 API는 HTTP 401 응답 코드(Unauthorized)를 반환합니다.

API가 HTTP 403 응답 코드를 반환하면 애플리케이션이 등록되지 않을 수 있습니다. 대부분의 API는 등록되지 않은 애플리케이션에 대한 쿼리 수량 한도를 0으로 설정하며 이 쿼리 한도를 초과하는 경우 403 응답 코드를 반환합니다.

다음 섹션에서는 액세스 토큰을 갱신하는 방법을 설명합니다.

액세스 토큰 갱신

액세스 토큰은 정기적으로 만료되며, 만료되는 경우 갱신해야 합니다. 액세스 토큰이 만료되거나 만료되기 전에 애플리케이션에서 갱신 토큰을 사용하여 유효한 새 액세스 토큰을 받을 수 있습니다. 서버측 웹 애플리케이션, 설치된 애플리케이션, 기기는 모두 인증 절차를 진행하는 동안 갱신 토큰을 받습니다.

액세스 토큰을 갱신하려면 애플리케이션에서 Google 인증 서버로 클라이언트 ID, 클라이언트 비밀번호, 사용자의 갱신 토큰을 지정하는 POST 요청을 전송합니다. 또한 이 요청으로 refresh_tokengrant_type 매개변수 값을 설정합니다. 다음은 이러한 요청의 예입니다.

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

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

인증 서버는 아래와 같이 새 액세스 토큰이 포함된 JSON 개체를 반환합니다.

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer"
}

발급되는 갱신 토큰의 수는 제한되며, 클라이언트/사용자 조합당 한도 및 모든 클라이언트의 사용자당 한도가 있습니다. 갱신 토큰을 장기적으로 보관할 수 있는 저장소에 저장하여 유효기간까지 계속 사용해야 합니다. 애플리케이션에서 너무 많은 갱신 토큰을 요청하면 이러한 한도에 도달할 수 있으며, 이 경우 기존 갱신 토큰의 작동이 중지됩니다.

토큰 취소

액세스 토큰을 취소하는 방법은 두 가지가 있습니다.

  • 사용자는 아래 URL로 이동하여 액세스를 명시적으로 취소함으로써 애플리케이션에 부여된 액세스 권한을 취소할 수 있습니다.

    https://accounts.google.com/b/0/IssuedAuthSubTokens

    이 페이지로 이동하려면 다음 단계를 수행합니다.

    1. Google 샌드바에 있는 사용자의 사진을 클릭한 다음 계정 링크를 클릭하거나 다른 방법으로 사용자 Google 계정의 계정 개요 페이지로 이동합니다.
    2. 링크를 따라 보안 설정 페이지로 이동합니다.
    3. 사용자 Google 계정의 세부정보에 액세스하고 사용할 수 있는 연결된 애플리케이션 및 웹사이트에 대한 액세스를 관리하려면 버튼을 클릭합니다.

  • 애플리케이션은 프로그래밍 방식을 통해 액세스를 자체적으로 취소할 수 있습니다. 이 취소 유형은 사용자가 구독을 취소하거나 애플리케이션을 제거하는 경우에 유용하며, 이 경우 애플리케이션에 부여된 권한을 삭제하는 API 요청이 삭제 절차에 포함되어야 합니다.

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

    curl https://accounts.google.com/o/oauth2/revoke?token={token}

    지정된 토큰은 액세스 토큰 또는 갱신 토큰일 수 있습니다. 액세스 토큰이 지정되고 해당 갱신 토큰이 있는 경우, 갱신 토큰도 함께 취소됩니다.

    취소가 성공적으로 완료된 경우 응답 상태 코드는 200입니다. 오류가 발생한 경우 응답 상태 코드는 400이며 응답에 오류 코드도 포함됩니다.

클라이언트 라이브러리

Google로 로그인

참고: Google 기능을 사용하여 로그인 기능을 제공하려고 계획 중인 경우 OAuth 2.0 인증 메커니즘 및 Google+의 소셜 기능에 대한 추가 액세스를 제공하는 Google+ Sign-in을 사용하는 것이 좋습니다.

아래 나열된 클라이언트 라이브러리를 사용하여 애플리케이션에서 OAuth 2.0을 구현할 수 있습니다. 직접 코드를 작성하는 것보다 클라이언트 라이브러리를 사용하는 것이 좋습니다. 사용자 및 애플리케이션의 안전 및 보안을 위해 표준 라이브러리를 사용해야 합니다.

YouTube Data API 호출 섹션의 안내에 따라 OAuth 2.0 토큰 값을 올바로 설정하도록 코드를 수정할 수 있습니다.