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

Tài liệu này giải thích cách triển khai quy trình uỷ quyền OAuth 2.0 để truy cập vào các API của Google từ một ứng dụng web JavaScript. OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng trong khi vẫn giữ bí mật tên người dùng, mật khẩu và các thông tin khác. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để xin phép người dùng lưu trữ tệp trong Google Drive của họ.

Quy trình OAuth 2.0 này được gọi là quy trình cấp quyền ngầm ẩn. Loại này được thiết kế cho các ứng dụng chỉ truy cập vào API khi người dùng đang sử dụng ứng dụng. Các ứng dụng này không thể lưu trữ thông tin mật.

Trong quy trình này, ứng dụng của bạn sẽ mở một URL của Google sử dụng các tham số truy vấn để xác định ứng dụng của bạn và loại quyền truy cập API mà ứng dụng yêu cầu. Bạn có thể mở URL trong cửa sổ trình duyệt hiện tại hoặc hộp thoại. Người dùng có thể xác thực bằng Google và cấp các quyền được yêu cầu. Sau đó, Google sẽ chuyển hướng người dùng trở lại ứng dụng của bạn. Quá trình chuyển hướng này bao gồm một mã truy cập mà ứng dụng của bạn sẽ xác minh rồi dùng để đưa ra yêu cầu API.

Thư viện ứng dụng API của Google và Dịch vụ nhận dạng của Google

Nếu sử dụng thư viện ứng dụng API của Google cho JavaScript để thực hiện các lệnh gọi được uỷ quyền đến Google, bạn nên sử dụng thư viện JavaScript Dịch vụ nhận dạng của Google để xử lý quy trình uỷ quyền. Bạn nên sử dụng mô hình mã của Dịch vụ nhận dạng của Google. Mô hình này dựa trên quy trình sử dụng mã uỷ quyền an toàn hơn với PKCE.

Điều kiện tiên quyết

Bật API cho dự án của bạn

Mọi ứng dụng gọi API của Google đều cần bật các API đó trong Bảng điều khiển API.

Cách bật API cho dự án:

1. Mở Thư viện API trong Google API Console.
2. Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới.
3. Thư viện API liệt kê tất cả những API có sẵn, được nhóm theo nhóm sản phẩm và mức độ phổ biến. Nếu API bạn muốn chọn không hiển thị trong danh sách, hãy sử dụng chức năng tìm kiếm để tìm API đó hoặc nhấp vào Xem tất cả trong nhóm sản phẩm chứa API đó.
4. Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
5. Nếu bạn nhận được một lời nhắc, hãy bật tính năng thanh toán.
6. Nếu bạn nhận được lời nhắc, hãy đọc và chấp nhận Điều khoản dịch vụ của API.

Tạo thông tin uỷ quyền

Bất kỳ ứng dụng nào sử dụng OAuth 2.0 để truy cập vào API của Google đều phải có thông tin xác thực uỷ quyền để xác định ứng dụng đó với máy chủ OAuth 2.0 của Google. Các bước sau đây giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể sử dụng thông tin đăng nhập để truy cập vào các API mà bạn đã bật cho dự án đó.

1. Chuyển đến trang Ứng dụng.
2. Nhấp vào Create Client (Tạo ứng dụng).
3. Chọn loại ứng dụng Ứng dụng web.
4. Hoàn thành biểu mẫu. Các ứng dụng sử dụng JavaScript để gửi yêu cầu API Google được uỷ quyền phải chỉ định nguồn gốc JavaScript được uỷ quyền. Nguồn gốc xác định miền mà ứng dụng của bạn có thể gửi yêu cầu đến máy chủ OAuth 2.0. Những nguồn gốc này phải tuân thủ các quy tắc xác thực của Google.

Xác định phạm vi truy cập

Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào những tài nguyên cần thiết, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể có mối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai quy trình uỷ quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của bạn cần có quyền truy cập.

Tài liệu Phạm vi API OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google.

Lấy mã truy cập OAuth 2.0

Các bước sau đây cho thấy cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để nhận được sự đồng ý của người dùng nhằm thực hiện yêu cầu API thay mặt cho người dùng. Ứng dụng của bạn phải có sự đồng ý đó trước khi có thể thực thi yêu cầu API của Google cần có sự uỷ quyền của người dùng.

Bước 1: Chuyển hướng đến máy chủ OAuth 2.0 của Google

Để yêu cầu quyền truy cập vào dữ liệu của người dùng, hãy chuyển hướng người dùng đến máy chủ OAuth 2.0 của Google.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//developers.google.com/oauthplayground&
 client_id=client_id

/*
 * 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 https://www.googleapis.com/auth/calendar.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();
}

Bước 2: Google nhắc người dùng đồng ý

Trong bước này, người dùng quyết định xem có cấp cho ứng dụng của bạn quyền truy cập được yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ yêu cầu sự đồng ý, trong đó có tên ứng dụng của bạn và các dịch vụ API của Google mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực của người dùng, cũng như thông tin tóm tắt về phạm vi truy cập sẽ được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi mà ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu.

Ứng dụng của bạn không cần làm gì ở giai đoạn này vì ứng dụng đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu có quyền truy cập nào được cấp hay không. Phản hồi đó được giải thích trong bước tiếp theo.

Bước 3: Xử lý phản hồi của máy chủ OAuth 2.0

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//developers.google.com/oauthplayground&
 client_id=client_id

Bước 4: Kiểm tra xem người dùng đã cấp những phạm vi nào

Khi yêu cầu nhiều quyền (phạm vi), người dùng có thể không cấp cho ứng dụng của bạn quyền truy cập vào tất cả các quyền đó. Ứng dụng của bạn phải xác minh những phạm vi thực sự được cấp và xử lý linh hoạt các trường hợp một số quyền bị từ chối, thường là bằng cách tắt các tính năng dựa vào những phạm vi bị từ chối đó.

Tuy nhiên, vẫn có một số ngoại lệ. Các ứng dụng Google Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc các ứng dụng được đánh dấu là Đáng tin cậy sẽ bỏ qua màn hình xin phép cấp quyền truy cập chi tiết. Đối với những ứng dụng này, người dùng sẽ không thấy màn hình xin phép cấp quyền chi tiết. Thay vào đó, ứng dụng của bạn sẽ nhận được tất cả phạm vi được yêu cầu hoặc không nhận được phạm vi nào.

Để biết thêm thông tin chi tiết, hãy xem bài viết Cách xử lý các quyền truy cập chi tiết.

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Gọi API của Google

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

curl https://www.googleapis.com/drive/v2/files?access_token=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) {
  console.log(xhr.response);
};
xhr.send(null);

Ví dụ đầ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']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        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 {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } 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 https://www.googleapis.com/auth/calendar.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>

Quy tắc xác thực nguồn gốc JavaScript

Google áp dụng các quy tắc xác thực sau đây cho nguồn gốc JavaScript để giúp nhà phát triển bảo mật ứng dụng của họ. Nguồn gốc JavaScript của bạn phải tuân thủ các quy tắc này. Xem RFC 3986 mục 3 để biết định nghĩa về miền, máy chủ lưu trữ và lược đồ được dùng trong các quy tắc này.

Uỷ quyền gia tăng

Trong giao thức OAuth 2.0, ứng dụng của bạn yêu cầu uỷ quyền truy cập vào các tài nguyên được xác định theo phạm vi. Bạn nên yêu cầu cấp quyền truy cập vào tài nguyên tại thời điểm cần thiết để mang lại trải nghiệm tốt nhất cho người dùng. Để hỗ trợ phương pháp này, máy chủ uỷ quyền của Google hỗ trợ uỷ quyền gia tăng. Tính năng này cho phép bạn yêu cầu các phạm vi khi cần và nếu người dùng cấp quyền cho phạm vi mới, tính năng này sẽ trả về một mã uỷ quyền có thể được đổi lấy mã thông báo chứa tất cả các phạm vi mà người dùng đã cấp cho dự án.

Ví dụ: một ứng dụng cho phép mọi người lấy mẫu các bản nhạc và tạo bản phối có thể cần rất ít tài nguyên tại thời điểm đăng nhập, có thể chỉ cần tên của người đăng nhập. Tuy nhiên, để lưu bản phối hoàn chỉnh, ứng dụng cần có quyền truy cập vào Google Drive của họ. Hầu hết mọi người sẽ thấy tự nhiên nếu họ chỉ được yêu cầu cấp quyền truy cập vào Google Drive tại thời điểm ứng dụng thực sự cần đến.

Trong trường hợp này, tại thời điểm đăng nhập, ứng dụng có thể yêu cầu phạm vi openid và profile để thực hiện quy trình đăng nhập cơ bản, sau đó yêu cầu phạm vi https://www.googleapis.com/auth/drive.file tại thời điểm yêu cầu đầu tiên để lưu bản phối.

Các quy tắc sau đây áp dụng cho mã truy cập có được từ quy trình uỷ quyền gia tăng:

• Bạn có thể dùng mã thông báo này để truy cập vào các tài nguyên tương ứng với bất kỳ phạm vi nào được đưa vào quy trình uỷ quyền mới, kết hợp.
• Khi bạn sử dụng mã làm mới cho yêu cầu uỷ quyền kết hợp để lấy mã truy cập, mã truy cập này sẽ đại diện cho yêu cầu uỷ quyền kết hợp và có thể được dùng cho bất kỳ giá trị scope nào có trong phản hồi.
• Uỷ quyền kết hợp bao gồm tất cả các phạm vi mà người dùng đã cấp cho dự án API ngay cả khi các quyền được yêu cầu từ các ứng dụng khác nhau. Ví dụ: nếu người dùng cấp quyền truy cập vào một phạm vi bằng ứng dụng khách trên máy tính của một ứng dụng, sau đó cấp một phạm vi khác cho cùng một ứng dụng đó thông qua ứng dụng di động, thì thông tin uỷ quyền kết hợp sẽ bao gồm cả hai phạm vi.
• Nếu bạn thu hồi một mã thông báo đại diện cho một yêu cầu uỷ quyền kết hợp, thì quyền truy cập vào tất cả phạm vi của yêu cầu uỷ quyền đó thay mặt cho người dùng được liên kết sẽ bị thu hồi đồng thời.

Các mã mẫu dưới đây cho biết cách thêm phạm vi vào mã truy cập hiện có. Cách tiếp cận này giúp ứng dụng của bạn không phải quản lý nhiều mã truy cập.

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

Thu hồi mã thông báo

Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập của trang web hoặc ứng dụng trong tài liệu hỗ trợ Các trang web và ứng dụng bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.

Ứng dụng cũng có thể thu hồi quyền truy cập được cấp cho ứng dụng đó theo phương thức lập trình. Việc thu hồi theo chương trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá một ứng dụng hoặc tài nguyên API mà ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, một phần của quy trình xoá có thể bao gồm yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng sẽ bị xoá.

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

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