OAuth 2.0 Flow: Client-side web apps

OAuth 2.0 흐름은 JavaScript 기반 웹 애플리케이션이 인증된 Google API 요청을 전송할 수 있도록 설계되었습니다. 이러한 애플리케이션은 지속적으로 상태를 유지할 수 없습니다. 즉, 사용자가 애플리케이션에 있는 동안에만 애플리케이션이 YouTube Data 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 엔드포인트에서 인증 코드의 반환 여부를 결정합니다. JavaScript 애플리케이션은 매개변수 값을 token으로 설정해야 합니다. 이 값은 Google 인증 서버가 서버에서 반환하는 리디렉션 URI의 해시(#) 프래그먼트에 name=value 쌍으로 액세스 토큰을 반환하도록 지시합니다.
    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로 설정합니다.
    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=token
    
  2. Google의 응답 처리

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

    • 사용자가 애플리케이션에 대한 액세스 권한을 부여한 경우 Google은 아래 샘플 URI에서와 같이 유효 기간이 짧은 액세스 토큰을 리디렉션 URI의 해시 프래그먼트에 추가합니다. 응답에는 expires_intoken_type 매개변수도 포함됩니다. 매개변수는 토큰의 수명을 초 단위로 표시하고 반환되는 토큰의 종류를 각각 표시합니다. 마지막으로, 인증 서버로의 원래 요청에 state 매개변수가 포함된 경우 응답에 state 매개변수가 포함됩니다.

      http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600

      참고: 또한 애플리케이션에서 응답의 해시 프래그먼트에 다른 매개변수가 포함되도록 허용해야 합니다. 위의 단락에서는 redirect_uri에 반환되는 이름-값 쌍의 최소 집합에 대해 설명합니다.

      페이지에서 실행 중인 JavaScript 코드는 window.location.hash 값으로부터 액세스 토큰을 가져올 수 있으며 토큰을 쿠키에 저장하거나 서버에 POST 할 수 있습니다.

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

      http://localhost/oauth2callback#error=access_denied
  3. 사용자의 토큰 검증

    사용자가 애플리케이션에 대한 액세스 권한을 부여했다고 가정하고 redirect_uri에 반환된 토큰을 명시적으로 검증해야 합니다. 토큰을 검증하거나 확인함으로써 애플리케이션이 대리인 혼동 문제(confused deputy problem)에 취약하지 않도록 해야 합니다.

    토큰을 검증하려면 https://www.googleapis.com/oauth2/v1/tokeninfo에 요청을 보낸 다음 토큰을 access_token 매개변수 값으로 설정합니다. 해당 URL은 토큰을 발급한 애플리케이션, 토큰과 연결된 사용자, 사용자가 액세스 권한을 부여한 범위, 토큰 만료까지 남은 시간을 포함하여 토큰과 관련된 정보를 허용하고 반환합니다.

    아래 샘플 URL은 토큰 검증 요청을 전송할 위치를 보여줍니다.

    https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=ACCESS_TOKEN
  4. 토큰 검증 응답 처리

    토큰 검증 요청에 대한 응답으로 Google 인증 서버는 토큰을 설명하는 JSON 개체 또는 오류 메시지를 포함한 JSON 개체를 반환합니다.

    • 토큰이 유효한 경우 JSON 개체는 다음 속성을 포함합니다.

      필드
      audience 액세스 토큰의 사용자인 애플리케이션입니다.

      중요: 토큰을 사용하기 전에 필드 값이 Google APIs consoleClient ID와 정확하게 일치하는지 확인해야 합니다. 이러한 검증을 통해 애플리케이션이 대리인 혼동 문제에 취약하지 않게 됩니다.
      expires_in 토큰이 만료되기까지 남은 시간(초)입니다.
      scope 사용자가 액세스 권한을 부여한 범위 목록으로 공백으로 구분되어 있습니다. 이 목록은 1단계의 인증 요청에서 지정한 범위와 일치해야 합니다.
      userid 이 값을 통해 프로필 정보를 여러 Google API와 연결할 수 있습니다. 1단계의 요청에서 https://www.googleapis.com/auth/userinfo.profile 범위를 포함한 경우에만 응답에 표시됩니다. 필드 값은 로그인한 사용자와 관련된 변경할 수 없는 식별자이며 애플리케이션에서 사용자 세션을 만들고 관리하는 데 사용할 수 있습니다.

      샘플 응답은 아래와 같습니다.

      {
        "audience":"8819981768.apps.googleusercontent.com",
        "user_id":"123456789",
        "scope":"https://www.googleapis.com/auth/youtube",
        "expires_in":436
      }
      
    • 토큰이 만료 또는 변경되거나 해당 권한이 취소된 경우 Google 인증 서버는 JSON 개체에 오류 메시지를 반환합니다. 오류는 400 오류 및 아래와 같은 형식의 JSON 본문으로 표시됩니다.

      {"error":"invalid_token"}

      설계에 따라 실패의 원인과 관련된 추가 정보는 제공되지 않습니다.

      참고: 실제로 400 오류는 일반적으로 부적절한 URL 이스케이핑으로 인해 액세스 토큰 요청 URL의 형식이 잘못되었음을 나타냅니다.

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 토큰 값을 올바로 설정하도록 코드를 수정할 수 있습니다.