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 vào điểm cuối này qua HTTPS; các kết nối HTTP đơn thuần 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 cho web ứng dụng máy chủ:

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

Dưới đây là ví dụ về URL, có ngắt dòng và khoảng trắng để 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 sử dụng Thư viện ứng dụng API của Google cho JavaScript. Vì OAuth này Điểm cuối 2.0 không hỗ trợ Chia sẻ tài nguyên trên nhiều nguồn gốc (CORS), đoạn mã sẽ tạo một biểu mẫu này 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 gửi phản hồi tới redirect_uri được chỉ định trong yêu cầu mã truy cập.

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, phản hồi có chứa thông báo lỗi. Mã 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 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ũng chứa tham số token_type, luôn được đặt thành Bearer và tham số expires_in chỉ định vòng đờ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 mã đó 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 tra 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 truy cập chỉ đọc để xem siêu dữ liệu cho 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ẽ mang lại 404 NOT FOUND lỗi trừ phi máy cục bộ của bạn tình cờ phân phá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 quay 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ã này để thực hiện lệnh gọi đến Google thay mặt cho một tài khoản người dùng nếu(các) phạm vi quyền truy cập mà API yêu cầu đã được cấp. Để thực hiện việc này, hãy thêm mã truy cập trong yêu cầu gửi đến API bằng cách bao gồm truy vấn access_token hoặc một giá trị Bearer của tiêu đề HTTP Authorization. Nếu có thể, nên ưu tiên sử dụng tiêu đề HTTP vì chuỗi truy vấn thường hiển thị trong nhật ký máy chủ. Trong hầu hết bạn có thể sử dụng thư viện ứng dụng để thiết lập lệnh gọi đến các API của Google (ví dụ: khi gọi API Tệp Drive).

Bạn có thể dùng thử tất cả API của Google và xem phạm vi của chúng ở Nền tảng OAuth 2.0.

Ví dụ về HTTP GET

Lệnh gọi đến drive.files điểm cuối (API Tệp Drive) bằng 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à lệnh gọi đến cùng một API cho người dùng đã được xác thực bằng access_token tham số chuỗi truy vấn:

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. Sau đây là một 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, một cách 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 trên nhiều nguồn gốc) để gửi đến một API của Google. Ví dụ này không sử dụng Thư viện ứng dụng API của Google cho JavaScript. Tuy nhiên, ngay cả khi bạn không dùng thư viện ứng dụng, Hướng dẫn Hỗ trợ về CORS (Chia sẻ tài nguyên giữa nhiều nguồn gốc) trong tài liệu của thư viện đó có thể sẽ giúp ích cho 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 có thu được để gửi yêu cầu API thay mặt cho người dùng được uỷ quyền. Các tính năng hoàn chỉnh ví dụ 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 dành cho JavaScript. Mã này dành cho trang HTML hiển thị nút để hãy 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 liệu trang đã lưu trữ Mã truy cập API trong bộ nhớ cục bộ của trình duyệt. Nếu có thì lệnh này sẽ thực thi yêu cầu API. Nếu không, nó 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. URL này hướng 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 được yêu cầu, người dùng đượ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 để tạo yêu cầu API mẫu.

   Yêu cầu API 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 vào phần gỡ lỗi của trình duyệt Google Play.

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

Để chạy mã này cục bộ, bạn cần đặt giá trị cho YOUR_CLIENT_ID và biến YOUR_REDIRECT_URI tương ứng với uỷ quyền thông tin xác thực. Biến YOUR_REDIRECT_URI phải được đặt 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 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ẽ nhận được redirect_uri_mismatch . Dự án của bạn cũng phải có đã 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/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() {
    // 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/drive.metadata.readonly',
                  '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

Để thêm phạm vi vào một mã truy cập hiện có, hãy thêm include_granted_scopes trong 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 này. Đoạn mã giả định rằng bạn đã lưu trữ 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. (Các mã ví dụ hoàn chỉnh lưu trữ danh sách các 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 tập dữ liệu cục bộ của trình duyệt storage.)

Đ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 đó, thì 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à được cung cấp sau trong phần hoàn chỉnh ví dụ).

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 cách lập trình, ứng dụng sẽ đưa ra yêu cầu https://oauth2.googleapis.com/revoke và bao gồm mã thông bá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ã này có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo là một 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 việc 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 có 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 dành 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), mã sẽ tạo 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 của bạn.

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