Sử dụng OAuth 2.0 cho ứng dụng web JavaScript

Điểm cuối OAuth 2.0

Tạo URL để yêu cầu quyền truy cập từ điểm cuối OAuth 2.0 của Google tại https://accounts.google.com/o/oauth2/v2/auth. Bạn có thể truy cập điểm cuối này qua HTTPS; các kết nối HTTP thuần tuý sẽ bị từ chối.

Máy chủ uỷ quyền của Google hỗ trợ các tham số chuỗi truy vấn sau đây cho các ứng dụng máy chủ web:

Ví dụ về lệnh chuyển hướng đến máy chủ uỷ quyền của Google

URL mẫu bên dưới yêu cầu quyền truy cập ngoại tuyến (access_type=offline) vào một phạm vi cho phép truy cập để xem tài khoản YouTube của người dùng. Phương thức này sử dụng tính năng uỷ quyền gia tăng để đảm bảo mã truy cập mới bao gồm mọi phạm vi mà người dùng đã cấp quyền truy cập vào ứng dụng trước đó. URL cũng đặt giá trị cho các tham số redirect_uri, response_type và client_id bắt buộc cũng như cho tham số state. URL chứa dấu ngắt dòng và dấu cách để dễ đọc.

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

Sau khi bạn tạo URL yêu cầu, hãy chuyển hướng người dùng đến URL đó.

Mã mẫu JavaScript

Đoạn mã JavaScript sau đây cho biết cách bắt đầu quy trình uỷ quyền trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì điểm cuối OAuth 2.0 này không hỗ trợ tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên đoạn mã này sẽ tạo một biểu mẫu mở yêu cầu đến điểm cuối đó.

/*
 * 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();
}

Điểm cuối OAuth 2.0

Máy chủ OAuth 2.0 sẽ gửi phản hồi đến redirect_uri được chỉ định trong yêu cầu mã truy cập của bạn.

Nếu người dùng phê duyệt yêu cầu, thì phản hồi sẽ chứa mã truy cập. Nếu người dùng không phê duyệt yêu cầu, thì phản hồi sẽ chứa thông báo lỗi. Mã thông báo truy cập hoặc thông báo lỗi sẽ được trả về trên mảnh băm của URI chuyển hướng, như minh hoạ dưới đây:

• Phản hồi mã truy cập:

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

  Ngoài tham số access_token, chuỗi mảnh cũng chứa tham số token_type, luôn được đặt thành Bearer và tham số expires_in, chỉ định thời lượng của mã thông báo, tính bằng giây. Nếu bạn đã chỉ định tham số state trong yêu cầu mã truy cập, thì giá trị của tham số đó cũng sẽ được đưa vào phản hồi.

• Phản hồi lỗi:

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

Phản hồi mẫu của máy chủ OAuth 2.0

Bạn có thể kiểm thử quy trình này bằng cách nhấp vào URL mẫu sau đây. URL này yêu cầu quyền chỉ có thể đọc để xem siêu dữ liệu cho các tệp trong Google Drive và quyền chỉ có thể đọc để xem các sự kiện trong Lịch Google:

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

Sau khi hoàn tất quy trình OAuth 2.0, bạn sẽ được chuyển hướng đến http://localhost/oauth2callback. URL đó sẽ trả về lỗi 404 NOT FOUND trừ phi máy cục bộ của bạn tình cờ phân phát một tệp tại địa chỉ đó. Bước tiếp theo cung cấp thêm thông tin chi tiết về thông tin được trả về trong URI khi người dùng được chuyển hướng trở lại ứng dụng của bạn.

Điểm cuối OAuth 2.0

Để kiểm tra xem người dùng đã cấp cho ứng dụng quyền truy cập vào một phạm vi cụ thể hay chưa, hãy kiểm tra trường scope trong phản hồi mã thông báo truy cập. Phạm vi truy cập do access_token cấp được biểu thị dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.

Ví dụ: phản hồi mã thông báo truy cập mẫu sau đây cho biết rằng người dùng đã cấp cho ứng dụng của bạn quyền xem, chỉnh sửa và xoá vĩnh viễn các video, mức xếp hạng, bình luận và phụ đề của người dùng trên YouTube:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Điểm cuối OAuth 2.0

Sau khi ứng dụng của bạn nhận được mã thông báo truy cập, bạn có thể sử dụng mã thông báo đó để thay mặt một tài khoản người dùng nhất định thực hiện lệnh gọi đến API của Google nếu(các) phạm vi truy cập mà API yêu cầu đã được cấp. Để thực hiện việc này, hãy đưa mã truy cập vào yêu cầu gửi đến API bằng cách thêm tham số truy vấn access_token hoặc giá trị Bearer của tiêu đề HTTP Authorization. Khi có thể, bạn nên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường xuất hiện trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng thư viện ứng dụng để thiết lập các lệnh gọi đến API của Google (ví dụ: khi gọi API Dữ liệu YouTube).

Xin lưu ý rằng YouTube Data API chỉ hỗ trợ tài khoản dịch vụ cho những chủ sở hữu nội dung trên YouTube sở hữu và quản lý nhiều kênh YouTube, chẳng hạn như hãng thu âm và hãng phim.

Bạn có thể dùng thử tất cả API của Google và xem phạm vi của các API đó tại OAuth 2.0 Playground.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối youtube.channels (API Dữ liệu YouTube) bằng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. Xin lưu ý rằng bạn cần chỉ định mã truy cập của riêng mình:

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

Dưới đây là lệnh gọi đến cùng một API cho người dùng đã xác thực bằng cách sử dụng tham số chuỗi truy vấn access_token:

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

Ví dụ về curl

Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Dưới đây là ví dụ sử dụng tuỳ chọn tiêu đề HTTP (ưu tiên):

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

Hoặc tuỳ chọn tham số chuỗi truy vấn:

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

Mã mẫu JavaScript

Đoạn mã dưới đây minh hoạ cách sử dụng CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc) để gửi yêu cầu đến một API của Google. Ví dụ này không sử dụng Thư viện ứng dụng Google API cho JavaScript. Tuy nhiên, ngay cả khi bạn không sử dụng thư viện ứng dụng, hướng dẫn hỗ trợ CORS trong tài liệu của thư viện đó có thể giúp bạn hiểu rõ hơn về các yêu cầu này.

Trong đoạn mã này, biến access_token đại diện cho mã thông báo mà bạn đã nhận được để thay mặt người dùng được uỷ quyền gửi yêu cầu API. Ví dụ đầy đủ minh hoạ cách lưu trữ mã thông báo đó trong bộ nhớ cục bộ của trình duyệt và truy xuất mã thông báo đó khi đưa ra yêu cầu 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);

Điểm cuối OAuth 2.0

Mã mẫu này minh hoạ cách hoàn tất quy trình OAuth 2.0 trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Mã này dành cho một trang HTML hiển thị một nút để thử một yêu cầu API. Nếu bạn nhấp vào nút này, mã sẽ kiểm tra xem trang có lưu mã thông báo truy cập API trong bộ nhớ cục bộ của trình duyệt hay không. Nếu có, thì ứng dụng sẽ thực thi yêu cầu API. Nếu không, ứng dụng sẽ bắt đầu quy trình OAuth 2.0.

Đối với luồng OAuth 2.0, trang sẽ tuân theo các bước sau:

1. Phương thức này sẽ chuyển hướng người dùng đến máy chủ OAuth 2.0 của Google. Máy chủ này sẽ yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/youtube.force-ssl.
2. Sau khi cấp (hoặc từ chối) quyền truy cập vào một hoặc nhiều phạm vi được yêu cầu, người dùng sẽ được chuyển hướng đến trang ban đầu. Trang này sẽ phân tích cú pháp mã thông báo truy cập từ chuỗi giá trị nhận dạng mảnh.
3. Trang này kiểm tra xem người dùng đã cấp quyền truy cập vào những phạm vi nào cho ứng dụng.

4. Nếu người dùng đã cấp quyền truy cập vào các scope() được yêu cầu, thì trang sẽ sử dụng mã truy cập để tạo yêu cầu API mẫu.

   Yêu cầu API này gọi phương thức channels.list của YouTube Data API để truy xuất dữ liệu về kênh YouTube của người dùng được uỷ quyền.

5. Nếu yêu cầu thực thi thành công, phản hồi API sẽ được ghi lại trong bảng điều khiển gỡ lỗi của trình duyệt.

Bạn có thể thu hồi quyền truy cập vào ứng dụng thông qua trang Quyền cho Tài khoản Google của mình. Ứng dụng sẽ được liệt kê là OAuth 2.0 Demo for Google API Docs (Bản minh hoạ OAuth 2.0 cho Tài liệu API của Google).

Để chạy mã này trên máy, bạn cần đặt giá trị cho các biến YOUR_CLIENT_ID và YOUR_REDIRECT_URI tương ứng với thông tin xác thực uỷ quyền của bạn. Bạn nên đặt biến YOUR_REDIRECT_URI thành cùng một URL nơi trang đang được phân phát. Giá trị này phải khớp chính xác với một trong các URI chuyển hướng được uỷ quyền cho ứng dụng OAuth 2.0 mà bạn đã định cấu hình trong API Console Credentials page. Nếu giá trị này không khớp với URI được uỷ quyền, bạn sẽ gặp lỗi redirect_uri_mismatch. Dự án của bạn cũng phải bật API thích hợp cho yêu cầu này.

<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>

Điểm cuối OAuth 2.0

Trong ví dụ này, ứng dụng gọi yêu cầu quyền truy cập để truy xuất dữ liệu YouTube Analytics của người dùng, ngoài mọi quyền truy cập khác mà người dùng đã cấp cho ứng dụng.

Để thêm phạm vi vào mã truy cập hiện có, hãy thêm tham số include_granted_scopes vào yêu cầu gửi đến máy chủ OAuth 2.0 của Google.

Đoạn mã sau đây minh hoạ cách thực hiện việc đó. Đoạn mã giả định rằng bạn đã lưu trữ các phạm vi mà mã truy cập của bạn hợp lệ trong bộ nhớ cục bộ của trình duyệt. (Mã ví dụ đầy đủ lưu trữ danh sách các phạm vi mà mã thông báo truy cập hợp lệ bằng cách đặt thuộc tính oauth2-test-params.scope trong bộ nhớ cục bộ của trình duyệt.)

Đoạn mã này so sánh các phạm vi mà mã truy cập hợp lệ với phạm vi bạn muốn sử dụng cho một truy vấn cụ thể. Nếu mã truy cập không bao gồm phạm vi đó, quy trình OAuth 2.0 sẽ bắt đầu. Ở đây, hàm oauth2SignIn giống với hàm được cung cấp trong bước 2 (và hàm này được cung cấp sau trong ví dụ đầy đủ).

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.
}

Điểm cuối OAuth 2.0

Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng của bạn sẽ gửi yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo vào làm tham số:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Mã thông báo có thể là mã thông báo truy cập hoặc mã thông báo làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

Nếu quá trình thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, hệ thống sẽ trả về mã trạng thái HTTP 400 cùng với mã lỗi.

Đoạn mã JavaScript sau đây cho biết cách thu hồi mã thông báo trong JavaScript mà không cần sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì điểm cuối OAuth 2.0 của Google để thu hồi mã thông báo không hỗ trợ tính năng Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên mã sẽ tạo một biểu mẫu và gửi biểu mẫu đó đến điểm cuối thay vì sử dụng phương thức XMLHttpRequest() để đăng yêu cầu.

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();
}