OAuth 2.0 Flow: Installed apps

OAuth 2.0 흐름은 휴대전화 또는 컴퓨터와 같은 기기에 설치된 애플리케이션용으로 설계되었습니다. 이러한 애플리케이션은 사용자가 애플리케이션과 상호작용하는 동안 또는 애플리케이션이 사용자와의 직접적인 상호작용 없이 백그라운드에서 장시간 실행될 때 YouTube Data API에 액세스할 수 있습니다.

이 흐름에서는 사용자가 YouTube Data API과(와) 상호작용하도록 허용하는 토큰을 애플리케이션이 안전하게 저장할 수 없다고 가정합니다. 또한 애플리케이션이 시스템 브라우저에 액세스할 수 있거나 브라우저 컨트롤을 포함할 수 있어야 합니다. 애플리케이션이 위의 두 가지 조건에 부합하지 않는 경우 위에서 기기 탭을 클릭하여 기기와 관련된 OAuth 2.0 지침을 참조하세요.

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. 애플리케이션을 설치된 애플리케이션으로 등록

    애플리케이션을 등록할 때 설치된 애플리케이션으로 지정해야 합니다. 이에 따라 redirect_uri 매개변수의 기본값이 달라집니다.

  2. 액세스 토큰 받기

    참고: 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입니다. 설치된 애플리케이션을 등록하면 http://localhost:porturn:ietf:wg:oauth:2.0:oob 두 개의 redirect_uri 값이 자동으로 생성됩니다. 아래 설명을 참조하면 애플리케이션에 적합한 값을 선택하는 데 도움이 될 것입니다.

    http://localhost:port
    이 값은 Google 인증 서버가 인증 코드를 쿼리 문자열 매개변수로 클라이언트 기기의 웹 서버에 반환해야 함을 나타냅니다. 포트 번호는 Google APIs console에서 구성을 변경하지 않고 지정할 수 있습니다.

    이 URL에서 인증 코드를 받으려면 애플리케이션이 로컬 웹 서버를 수신해야 합니다. 플랫폼에서 해당 기능을 지원하는 경우 이 메커니즘을 사용해 인증 코드를 받는 것이 좋습니다. 하지만 모든 플랫폼이 이러한 접근 방식을 지원하는 것은 아니며 플랫폼에서 지원하더라도 다른 소프트웨어(예: Windows 방화벽)에서 메시지 전송을 차단할 수 있습니다.

    urn:ietf:wg:oauth:2.0:oob
    이 값은 Google 인증 서버가 브라우저의 제목 표시줄에 인증 코드를 반환해야 함을 나타냅니다. 클라이언트를 크게 변경하지 않으면 클라이언트가 HTTP 포트로 수신할 수 없는 경우에 유용한 옵션입니다. Windows 애플리케이션이 이러한 특징을 갖고 있습니다.

    애플리케이션이 이 값을 사용하는 경우 브라우저가 인증 서버로부터 받은 응답을 로드하는 시점을 결정해야 합니다. 그런 다음 브라우저에 제공된 페이지의 제목으로부터 인증 코드를 추출합니다. 페이지 제목에서 토큰을 파싱하는 방법에 대한 자세한 지침은 4단계를 참조하세요.

    또한 사용자에게 인증 코드가 있는 페이지가 표시되지 않도록 하려면 애플리케이션에서 브라우저 창을 닫아야 합니다. 창을 닫는 것과 관련된 메커니즘은 플랫폼에 따라 다릅니다.
    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 부분을 가져옵니다.
    state 선택 항목. 애플리케이션이 요청 및 리디렉션 응답 간 상태를 유지하는 데 사용하는 문자열입니다. 전송한 정확한 값은 사용자가 애플리케이션의 액세스 요청에 동의하거나 거부한 후 redirect_uri의 해시(#) 프래그먼트에 있는 name=value 쌍으로 반환됩니다. 이 매개변수는 사용자를 애플리케이션 내 올바른 리소스로 안내하고 임시값을 전송하며 교차 사이트 요청 위조를 방지하는 등의 용도로 사용할 수 있습니다.

    아래 샘플 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
    
  3. Google의 응답 처리

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

    • redirect_urihttp://localhost 또는 로컬 웹 서버의 일부 경로로 설정하면 다음 두 가지 시나리오 중 하나가 적용됩니다.

      • 사용자가 애플리케이션에 대한 액세스 권한을 부여한 경우 Google은 아래 샘플 URL에서와 같이 code 매개변수를 redirect_uri에 추가합니다. 이 값은 5단계에 설명된 대로 액세스 토큰과 교환하는 일회용 인증 코드를 지정합니다.

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

        http://localhost/oauth2callback#error=access_denied
    • redirect_uriurn:ietf:wg:oauth:2.0:oob로 설정하면 Google 인증 서버는 아래에 표시된 것과 같은 브라우저로 페이지를 반환합니다. 그러면 애플리케이션은 페이지 제목에서 인증 코드를 추출합니다.

      토큰을 추출하기 위해 애플리케이션은 페이지 제목의 마지막 공백 문자 다음에 표시되는 것은 모두 x=a&y=b 형식으로 된 매개변수 문자열이라고 가정합니다. 코드는 하위 문자열에서 매개변수를 파싱하여 페이지가 마지막 제목 문자열을 포함하고 있고 로그인 흐름이 완료되었음을 표시하기 위해 code= 또는 error= 할당을 찾아야 합니다. 페이지 제목이 code 매개변수에 값을 할당하면 해당 값이 토큰이 됩니다. 하지만 애플리케이션은 매개변수 문자열에 있는 토큰 길이나 매개변수 수에 대해 가정하면 안 됩니다.

      예를 들어 아래 스크린샷은 다음 속성을 갖는 페이지를 보여줍니다.

      • 페이지 제목: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • 매개변수 문자열: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • 인증 토큰: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

  4. 인증 코드를 갱신 토큰 및 액세스 토큰으로 교환

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

    code 4단계에서 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
    
  5. 응답 처리 및 토큰 저장

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