OAuth 2.0 Flow: Server-side web apps

OAuth 2.0 흐름은 기밀 정보를 저장하고 상태를 유지할 수 있는 서버를 사용하는 웹 애플리케이션용으로 설계되었습니다. 이러한 애플리케이션은 사용자가 실제로 애플리케이션을 사용하는 동안 또는 사용자가 애플리케이션을 종료한 후 YouTube Data API에 액세스할 수 있습니다.

이 시나리오는 사용자가 인증이 필요한 작업을 수행하려고 할 때 시작됩니다. 애플리케이션은 사용자를 애플리케이션에서 요구하는 API 액세스 유형을 지정하는 쿼리 매개변수가 포함된 Google URL로 리디렉션합니다.

Google은 사용자 인증 및 동의를 처리한 후 인증 코드를 반환합니다. 애플리케이션은 액세스 토큰을 받기 위해 client_idclient_secret과 함께 인증 코드를 사용하며, 이 인증 코드는 사용자를 대신하여 API 요청을 인증하는 데 사용될 수 있습니다. 이 단계에서 애플리케이션은 이전에 받은 토큰이 만료될 경우 애플리케이션이 새 액세스 토큰을 받을 수 있게 해주는 갱신 토큰을 요청할 수도 있습니다.

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. 액세스 토큰 받기

    참고: Google 인증 서버는 SSL(HTTPS)을 통해서만 액세스할 수 있고 HTTP 연결을 거부하므로 Google 인증 서버로 전송하는 요청은 http 대신 https를 사용해야 합니다.

    사용자가 처음으로 API 인증이 필요한 작업을 수행하려고 하면 사용자를 Google 인증 서버(https://accounts.google.com/o/oauth2/auth)로 안내해야 합니다. 다음 표에서는 URL에 포함해야 하거나 포함할 수 있는 요청 매개변수를 확인합니다. 구성한 요청 URI에는 URL로 올바로 이스케이프된 매개변수 값이 포함되어야 합니다.

    매개변수 설명
    client_id 필수 항목. 애플리케이션의 OAuth 2.0 클라이언트 ID로, APIs Console에서 값을 확인할 수 있습니다.
    redirect_uri 필수 항목. 클라이언트 ID에 대해 등록된 redirect_uri입니다. 애플리케이션에 대해 유효한 리디렉션 URI를 APIs Console에 등록합니다.
    response_type 필수 항목. Google OAuth 2.0 엔드포인트에서 인증 코드의 반환 여부를 결정합니다. 매개변수 값을 code로 설정합니다.
    scope 필수 항목. 사용자를 대신하여 애플리케이션이 액세스할 수 있는 리소스를 식별하는 공백으로 구분된 범위의 목록입니다. 이 값은 Google이 사용자에게 표시하는 동의 페이지에 나열되는 권한을 결정합니다.

    YouTube Data API은(는) 다음 범위를 지원합니다.

    범위
    https://www.googleapis.com/auth/youtube YouTube 계정을 관리합니다.
    https://www.googleapis.com/auth/youtube.readonly YouTube 계정을 확인합니다.
    https://www.googleapis.com/auth/youtube.upload YouTube 동영상을 업로드하고 관리합니다.
    https://www.googleapis.com/auth/youtubepartner-channel-audit channel 리소스에서 auditDetails 부분을 가져옵니다.
    approval_prompt 선택 항목. 이 매개변수는 사용자가 특정 작업을 완료하려고 시도할 때마다 애플리케이션에 대한 계정 액세스 권한을 부여하라는 메시지를 표시할지 여부를 나타냅니다. 기본값은 auto이며, 이는 사용자가 처음으로 보호된 리소스에 액세스하려고 하는 경우에만 액세스 권한을 부여하면 됨을 나타냅니다.

    특정 범위 집합과 관련해 이미 애플리케이션에 액세스 권한을 부여한 경우에도 사용자를 동의 페이지로 안내하려면 매개변수 값을 force로 설정합니다.
    access_type 권장 항목. 이 매개변수는 사용자가 브라우저에 없을 때 애플리케이션이 액세스 토큰을 갱신할 수 있는지 여부를 나타냅니다. 유효한 매개변수 값은 onlineoffline입니다. 사용자가 없을 때 애플리케이션이 갱신 토큰을 사용하도록 허용하려면 매개변수 값을 offline으로 설정합니다. (이 문서의 뒷부분에서 설명할 액세스 토큰의 갱신 방법입니다.)
    state 선택 항목. 애플리케이션이 요청 및 리디렉션 응답 간 상태를 유지하는 데 사용하는 문자열입니다. 전송한 정확한 값은 사용자가 애플리케이션의 액세스 요청에 동의하거나 거부한 후 redirect_uri의 해시(#) 프래그먼트에 있는 name=value 쌍으로 반환됩니다. 이 매개변수는 사용자를 애플리케이션 내 올바른 리소스로 안내하고 임시값을 전송하며 교차 사이트 요청 위조를 방지하는 등의 용도로 사용할 수 있습니다.
    login_hint 선택 항목. 애플리케이션이 인증을 시도하는 사용자를 알고 있는 경우 이 매개변수를 사용하여 Google 인증 서버에 힌트를 제공할 수 있습니다. 서버는 힌트를 사용하여 로그인 양식의 이메일 입력란을 미리 채워 놓거나 적절한 멀티 로그인 세션을 선택함으로써 로그인 흐름을 단순화합니다.

    아래 샘플 URL은 사용자를 대신하여 YouTube Data API 요청을 제출하기 위해 애플리케이션에 대한 권한 부여를 요청하는 Google 인증 서버 URI를 표시합니다. 매개변수 값은 URL로 올바로 이스케이프되어야 합니다.

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
      scope=https://www.googleapis.com/auth/youtube&
      response_type=code&
      access_type=offline
    
  2. Google의 응답 처리

    사용자가 애플리케이션에 대한 액세스 권한 부여에 동의하거나 거부하면 Google은 사용자를 1단계에서 지정한 redirect_uri로 리디렉션합니다.

    • 사용자가 애플리케이션에 대한 액세스 권한을 부여한 경우 Google은 code 매개변수를 redirect_uri에 추가합니다. 이 값은 4단계에 설명된 대로 액세스 토큰과 교환할 수 있는 임시 인증 코드입니다.

      http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf
    • 사용자가 애플리케이션에 대한 액세스 권한 부여를 거부한 경우 Google은 다음과 같이 redirect_uri의 해시 프래그먼트에 access_denied 오류 메시지를 포함합니다.

      http://localhost/oauth2callback#error=access_denied
  3. 인증 코드를 갱신 토큰 및 액세스 토큰으로 교환

    사용자가 애플리케이션에 대한 액세스 권한을 부여했다고 가정하고 3단계에서 받은 인증 코드를 갱신 토큰 및 액세스 토큰으로 교환합니다. 인증 코드를 교환하려면 POST 요청을 다음 키-값 쌍이 포함된 https://accounts.google.com/o/oauth2/token으로 전송합니다.

    code 3단계에서 Google이 redirect_uri로 반환한 인증 코드입니다.
    client_id 애플리케이션의 OAuth 2.0 클라이언트 ID로, 이 값은 Google APIs console에 표시됩니다.
    client_secret 클라이언트 ID와 연결된 클라이언트 비밀번호로, 이 값은 Google APIs console에 표시됩니다.
    redirect_uri 클라이언트 ID에 대해 등록된 redirect_uri입니다.
    grant_type 이 값은 authorization_code로 설정합니다.

    샘플 요청은 아래와 같습니다.

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
    redirect_uri=http://localhost/oauth2callback&
    grant_type=authorization_code
    
  4. 응답 처리 및 토큰 저장

    Google은 유효 기간이 짧은 액세스 토큰 및 갱신 토큰이 포함된 JSON 개체를 반환함으로써 POST 요청에 응답합니다.

    {
      "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
    }
    
    • 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 토큰 값을 올바로 설정하도록 코드를 수정할 수 있습니다.