OAuth 2.0 cho ứng dụng web phía máy khách

Điểm cuối OAuth 2.0

Tạo một 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. Có thể truy cập điểm cuối này qua HTTPS; các kết nối HTTP thuần tuý bị từ chối.

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

Mẫu chuyển hướng đến máy chủ uỷ quyền của Google

Dưới đây là một ví dụ về URL, với dấu ngắt dòng và khoảng trắng để bạn dễ đọc.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 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ợ Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), nên đoạn mã 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/drive.metadata.readonly',
                '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 chấp thuận yêu cầu thì phản hồi sẽ chứa mã truy cập. Nếu người dùng từ chối yêu cầu, thì phản hồi sẽ chứa thông báo lỗi. Mã truy cập hoặc thông báo lỗi đượ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 về 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òn chứa tham số token_type (luôn được đặt thành Bearer) và tham số expires_in (chỉ định thời gian tồn tại của mã thông báo) tính bằng giây. Nếu tham số state được chỉ định trong yêu cầu mã truy cập, thì giá trị của tham số đó cũng đượ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. 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 của bạn:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 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ẽ gây ra lỗi 404 NOT FOUND trừ phi máy cục bộ của bạn phân phát một tệp tại địa chỉ đó. Bước tiếp theo cung cấp thêm 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

Sau khi ứng dụng của bạn nhận được mã truy cập, bạn có thể sử dụng mã thông báo này để thay mặt một tài khoản người dùng cụ thể 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 một yêu cầu tới API bằng cách cung cấp tham số truy vấn access_token hoặc giá trị tiêu đề HTTP Authorization Bearer. Khi có thể, bạn nên sử dụng tiêu đề HTTP vì các 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 lệnh gọi đến API Google (chẳng hạn như khi gọi API Tệp Drive).

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

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối drive.files (API Drive Files) 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 /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Dưới đây là một lệnh gọi tới 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/drive/v2/files?access_token=access_token

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/drive/v2/files

Hoặc lựa chọn khác là tuỳ chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Mã mẫu JavaScript

Đoạn mã dưới đây minh hoạ cách sử dụng CORS (Chia sẻ tài nguyên nhiều nguồn gốc) để gửi yêu cầu tới một API của Google. Ví dụ này không sử dụng Thư viện ứng dụng API Google 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ợ về Cơ cấu tổ chức (Cor) trong tài liệu của thư viện đó có thể sẽ 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 bạn lấy được để thay mặt người dùng được uỷ quyền thực hiện các 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ã đó khi đưa ra yêu cầu API.

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    '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 trang HTML hiển thị nút để thử yêu cầu API. Nếu bạn nhấp vào nút đó, mã này sẽ kiểm tra xem trang đã lưu trữ mã truy cập API trong bộ nhớ cục bộ của trình duyệt hay chưa. Nếu có, lệnh này sẽ thực thi yêu cầu API. Nếu không, quá trình này sẽ bắt đầu quy trình OAuth 2.0.

Đối với quy trình OAuth 2.0, trang sẽ làm theo các bước sau:

1. Lệnh này chuyển người dùng đến máy chủ OAuth 2.0 của Google, máy chủ này yêu cầu quyền truy cập vào phạm vi https://www.googleapis.com/auth/drive.metadata.readonly.
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 yêu cầu, người dùng sẽ được chuyển hướng đến trang gốc để phân tích cú pháp mã truy cập từ chuỗi giá trị nhận dạng mảnh.

3. Trang sử dụng mã truy cập để gửi yêu cầu API mẫu.

   Yêu cầu API này sẽ gọi phương thức about.get của API Drive để truy xuất thông tin về tài khoản Google Drive của người dùng được uỷ quyền.

4. Nếu yêu cầu được thực thi thành công, thì phản hồi của 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 trong Tài khoản Google của mình. Ứng dụng sẽ được liệt kê là Bản minh họa OAuth 2.0 cho Google Tài liệu API.

Để chạy mã này cục bộ, 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. Bạn phải đặt biến YOUR_REDIRECT_URI thành chính 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 khách 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 một URI được uỷ quyền, thì 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';
  var fragmentString = location.hash.substring(1);

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

  // 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/drive/v3/about?fields=user&' +
          '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() {
    // 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/drive.metadata.readonly',
                  'state': 'try_sample_request',
                  '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

Để thêm phạm vi vào mã truy cập hiện có, hãy đưa tham số include_granted_scopes vào yêu cầu gửi tới 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ữ những 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 phạm vi mà mã 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 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 mà bạn đã cung cấp ở bước 2 (và hàm được cung cấp sau trong ví dụ đầy đủ).

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
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 sẽ gửi yêu cầu tới https://oauth2.googleapis.com/revoke và đưa mã thông báo vào dưới dạng 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 này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo này 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 quy 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, mã trạng thái HTTP 400 sẽ được trả về 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ợ 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();
}