자바스크립트 웹 애플리케이션에 OAuth 2.0 사용

OAuth 2.0 엔드포인트

https://accounts.google.com/o/oauth2/v2/auth에서 Google의 OAuth 2.0 엔드포인트에 액세스 권한을 요청하는 URL을 생성합니다. 이 엔드포인트는 HTTPS를 통해 액세스할 수 있습니다. 일반 HTTP 연결은 거부됩니다.

Google 승인 서버는 웹 서버 애플리케이션에 다음과 같은 쿼리 문자열 매개변수를 지원합니다.

Google 인증 서버로의 샘플 리디렉션

아래의 샘플 URL은 사용자의 YouTube 계정을 볼 수 있는 액세스를 허용하는 범위에 대한 오프라인 액세스(access_type=offline)를 요청합니다. 또한 점진적 승인을 사용하여 사용자가 이전에 애플리케이션 액세스 권한을 부여한 모든 범위에 새 액세스 토큰이 포함되는지 확인합니다. 이 URL은 필수 redirect_uri, response_type, client_id 매개변수와 state 매개변수의 값도 설정합니다. URL에는 가독성을 위해 줄바꿈과 공백이 포함되어 있습니다.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

요청 URL을 만든 후 사용자를 이 URL로 리디렉션합니다.

JavaScript 샘플 코드

다음 JavaScript 스니펫은 JavaScript용 Google API 클라이언트 라이브러리를 사용하지 않고 JavaScript에서 승인 흐름을 시작하는 방법을 보여줍니다. 이 OAuth 2.0 엔드포인트는 교차 출처 리소스 공유 (CORS)를 지원하지 않으므로 스니펫은 해당 엔드포인트에 대한 요청을 여는 양식을 만듭니다.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

OAuth 2.0 엔드포인트

OAuth 2.0 서버는 액세스 토큰 요청에 지정된 redirect_uri로 응답을 보냅니다.

사용자가 요청을 승인하면 응답에 액세스 토큰이 포함됩니다. 사용자가 요청을 승인하지 않으면 응답에 오류 메시지가 포함됩니다. 액세스 토큰 또는 오류 메시지는 아래와 같이 리디렉션 URI의 해시 프래그먼트에서 반환됩니다.

• 액세스 토큰 응답:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  프래그먼트 문자열에는 access_token 매개변수 외에도 항상 Bearer로 설정되는 token_type 매개변수와 토큰의 전체 기간(초)을 지정하는 expires_in 매개변수도 포함됩니다. state 매개변수가 액세스 토큰 요청에 지정된 경우 응답에도 값이 포함됩니다.

• 오류 응답:

  https://oauth2.example.com/callback#error=access_denied

샘플 OAuth 2.0 서버 응답

Google Drive의 파일 메타데이터를 보려는 읽기 전용 액세스를 요청하는 다음 샘플 URL을 클릭하여 이 흐름을 테스트할 수 있습니다.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=token&
 client_id=client_id

OAuth 2.0 흐름을 완료하면 http://localhost/oauth2callback로 리디렉션됩니다. 로컬 머신이 해당 주소에서 파일을 제공하지 않는 한 이 URL은 404 NOT FOUND 오류를 발생시킵니다. 다음 단계에서는 사용자가 애플리케이션으로 다시 리디렉션될 때 URI에 반환되는 정보에 관한 세부정보를 제공합니다.

OAuth 2.0 엔드포인트

애플리케이션이 액세스 토큰을 획득한 후 API에 필요한 액세스 범위가 부여된 경우 이 토큰을 사용하여 지정된 사용자 계정을 대신하여 Google API를 호출할 수 있습니다. 이렇게 하려면 access_token 쿼리 매개변수 또는 Authorization HTTP 헤더 Bearer 값을 포함하여 API에 대한 요청에 액세스 토큰을 포함하세요. 쿼리 문자열은 서버 로그에 표시되는 경향이 있으므로 가능하면 HTTP 헤더를 사용하는 것이 좋습니다. 대부분의 경우 클라이언트 라이브러리를 사용하여 Google API 호출을 설정할 수 있습니다 (예: YouTube Data API를 호출하는 경우).

YouTube Data API는 음반사, 영화 제작사와 같이 여러 YouTube 채널을 소유하고 관리하는 YouTube 콘텐츠 소유자의 서비스 계정만 지원합니다.

OAuth 2.0 플레이그라운드에서 모든 Google API를 사용해 보고 범위를 확인할 수 있습니다.

HTTP GET 예시

Authorization: Bearer HTTP 헤더를 사용하여 youtube.channels 엔드포인트 (YouTube Data API)를 호출하면 다음과 같은 형식이 됩니다. 자체 액세스 토큰을 지정해야 합니다.

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

다음은 access_token 쿼리 문자열 매개변수를 사용하여 인증된 사용자의 동일한 API를 호출하는 예입니다.

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

curl 예

curl 명령줄 애플리케이션을 사용하여 이러한 명령어를 테스트할 수 있습니다. 다음은 HTTP 헤더 옵션을 사용하는 예입니다 (권장).

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

또는 쿼리 문자열 매개변수 옵션을 사용할 수 있습니다.

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

JavaScript 샘플 코드

아래 코드 스니펫은 CORS (교차 출처 리소스 공유)를 사용하여 Google API에 요청을 보내는 방법을 보여줍니다. 이 예에서는 JavaScript용 Google API 클라이언트 라이브러리를 사용하지 않습니다. 그러나 클라이언트 라이브러리를 사용하지 않더라도 라이브러리 문서의 CORS 지원 가이드를 참고하면 이러한 요청을 보다 잘 이해할 수 있습니다.

이 코드 스니펫에서 access_token 변수는 승인된 사용자를 대신하여 API 요청을 하기 위해 획득한 토큰을 나타냅니다. 전체 예에서는 브라우저의 로컬 저장소에 토큰을 저장하고 API 요청을 할 때 이를 검색하는 방법을 보여줍니다.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

OAuth 2.0 엔드포인트

이 코드 샘플은 JavaScript용 Google API 클라이언트 라이브러리를 사용하지 않고 JavaScript에서 OAuth 2.0 흐름을 완료하는 방법을 보여줍니다. 이 코드는 API 요청을 시도하는 버튼을 표시하는 HTML 페이지용입니다. 버튼을 클릭하면 코드는 페이지가 브라우저의 로컬 저장소에 API 액세스 토큰을 저장했는지 확인합니다. 그렇다면 API 요청을 실행합니다. 그러지 않으면 OAuth 2.0 흐름이 시작됩니다.

OAuth 2.0 흐름의 경우 페이지는 다음 단계를 따릅니다.

1. 사용자를 Google의 OAuth 2.0 서버로 안내하여 https://www.googleapis.com/auth/youtube.force-ssl 범위에 대한 액세스를 요청합니다.
2. 하나 이상의 요청된 범위에 액세스 권한을 부여하거나 거부하면 사용자는 원본 페이지로 리디렉션되며 이 원본 페이지는 프래그먼트 식별자 문자열에서 액세스 토큰을 파싱합니다.

3. 페이지는 액세스 토큰을 사용하여 샘플 API 요청을 실행합니다.

   이 API 요청은 YouTube Data API의 channels.list 메서드를 호출하여 승인된 사용자의 YouTube 채널에 관한 데이터를 가져옵니다.

4. 요청이 실행되면 API 응답이 브라우저의 디버깅 콘솔에 로깅됩니다.

Google 계정의 권한 페이지를 통해 앱에 대한 액세스 권한을 취소할 수 있습니다. 앱이 Google API 문서용 OAuth 2.0 데모로 표시됩니다.

이 코드를 로컬에서 실행하려면 승인 사용자 인증 정보에 해당하는 YOUR_CLIENT_ID 및 YOUR_REDIRECT_URI 변수의 값을 설정해야 합니다. YOUR_REDIRECT_URI 변수는 페이지가 게재되는 URL과 동일한 URL로 설정해야 합니다. 이 값은 API Console Credentials page에서 구성한 OAuth 2.0 클라이언트에 승인된 리디렉션 URI 중 하나와 정확히 일치해야 합니다. 이 값이 승인된 URI와 일치하지 않으면 redirect_uri_mismatch 오류가 발생합니다. 또한 프로젝트에서 이 요청에 대해 적절한 API를 사용 설정해야 합니다.

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true&' +
          'access_token=' + params['access_token']);
      xhr.onreadystatechange = function (e) {
        if (xhr.readyState === 4 && xhr.status === 200) {
          console.log(xhr.response);
        } else if (xhr.readyState === 4 && xhr.status === 401) {
          // Token invalid, so prompt for user permission.
          oauth2SignIn();
        }
      };
      xhr.send(null);
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/youtube.force-ssl',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

OAuth 2.0 엔드포인트

이 예시에서 호출 애플리케이션은 사용자가 이미 애플리케이션에 부여한 다른 액세스 권한 외에도 사용자의 YouTube 애널리틱스 데이터를 검색하기 위한 액세스 권한을 요청합니다.

기존 액세스 토큰에 범위를 추가하려면 Google의 OAuth 2.0 서버에 대한 요청에 include_granted_scopes 매개변수를 포함합니다.

다음 코드 스니펫은 이 작업 방법을 보여줍니다. 이 스니펫은 액세스 토큰이 유효한 범위를 브라우저의 로컬 저장소에 저장했다고 가정합니다. (전체 예 코드는 브라우저의 로컬 스토리지에 oauth2-test-params.scope 속성을 설정하여 액세스 토큰이 유효한 범위 목록을 저장합니다.)

스니펫은 액세스 토큰이 유효한 범위를 특정 쿼리에 사용하려는 범위와 비교합니다. 액세스 토큰이 해당 범위를 포함하지 않는 경우 OAuth 2.0 흐름이 시작됩니다. 여기서 oauth2SignIn 함수는 2단계에서 제공된 함수와 동일하며 나중에 전체 예에서 제공됩니다.

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

OAuth 2.0 엔드포인트

토큰을 프로그래매틱 방식으로 취소하려면 애플리케이션에서 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가 오류 코드와 함께 반환됩니다.

다음 JavaScript 스니펫은 JavaScript용 Google API 클라이언트 라이브러리를 사용하지 않고 JavaScript에서 토큰을 취소하는 방법을 보여줍니다. 토큰을 취소하기 위한 Google의 OAuth 2.0 엔드포인트는 교차 출처 리소스 공유 (CORS)를 지원하지 않으므로 코드는 XMLHttpRequest() 메서드를 사용하여 요청을 게시하는 대신 양식을 만들고 양식을 엔드포인트에 제출합니다.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}