Trang này được dịch bởi Cloud Translation API.

Sử dụng mô hình mã

Thư viện Dịch vụ nhận dạng của Google cho phép người dùng yêu cầu mã uỷ quyền từ Google bằng cách sử dụng luồng UX dựa trên Cửa sổ bật lên hoặc Chuyển hướng của trình duyệt. Thao tác này bắt đầu một quy trình OAuth 2.0 an toàn và tạo ra một mã truy cập dùng để gọi các API của Google thay cho người dùng.

Tóm tắt quy trình sử dụng mã uỷ quyền OAuth 2.0:

Từ trình duyệt, bằng một cử chỉ (chẳng hạn như nhấp vào nút), chủ sở hữu Tài khoản Google sẽ yêu cầu Google cấp mã uỷ quyền.
Google phản hồi bằng cách gửi một mã uỷ quyền duy nhất đến một lệnh gọi lại trong ứng dụng web JavaScript đang chạy trong trình duyệt của người dùng hoặc trực tiếp gọi điểm cuối mã uỷ quyền của bạn bằng cách sử dụng lệnh chuyển hướng trình duyệt.
Nền tảng phụ trợ của bạn lưu trữ một điểm cuối mã uỷ quyền và nhận mã. Sau khi xác thực, mã này sẽ được trao đổi để lấy mã truy cập và mã làm mới cho mỗi người dùng bằng cách sử dụng một yêu cầu đến điểm cuối mã thông báo của Google.
Google xác thực mã uỷ quyền, xác nhận rằng yêu cầu bắt nguồn từ nền tảng bảo mật của bạn, cấp mã truy cập và mã làm mới, đồng thời trả về các mã này bằng cách gọi điểm cuối đăng nhập do nền tảng của bạn lưu trữ.
Điểm cuối đăng nhập của bạn nhận được mã truy cập và mã làm mới, đồng thời lưu trữ mã làm mới một cách an toàn để sử dụng sau này.

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

Làm theo các bước được mô tả trong phần Thiết lập để định cấu hình Màn hình đồng ý OAuth, lấy mã ứng dụng và tải thư viện ứng dụng.

Khởi chạy một Code Client

Phương thức google.accounts.oauth2.initCodeClient() khởi chạy một ứng dụng mã.

Chế độ Cửa sổ bật lên hoặc Chuyển hướng

Bạn có thể chọn chia sẻ mã uỷ quyền bằng quy trình người dùng ở chế độ Chuyển hướng hoặc Cửa sổ bật lên. Với chế độ Chuyển hướng, bạn sẽ lưu trữ một điểm cuối uỷ quyền OAuth2 trên máy chủ của mình và Google sẽ chuyển hướng tác nhân người dùng đến điểm cuối này, chia sẻ mã uỷ quyền dưới dạng một tham số URL. Đối với chế độ Cửa sổ bật lên, bạn xác định một trình xử lý lệnh gọi lại JavaScript, trình xử lý này sẽ gửi mã uỷ quyền đến máy chủ của bạn. Bạn có thể sử dụng chế độ cửa sổ bật lên để mang đến trải nghiệm liền mạch cho người dùng mà không cần khách truy cập phải rời khỏi trang web của bạn.

Cách khởi chạy một ứng dụng cho:

Chuyển hướng luồng trải nghiệm người dùng, đặt ux_mode thành redirect và giá trị của redirect_uri thành điểm cuối mã uỷ quyền của nền tảng. 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 Google Cloud Console. URI này cũng phải tuân thủ Các quy tắc xác thực URI chuyển hướng.
Quy trình trải nghiệm người dùng của cửa sổ bật lên, đặt ux_mode thành popup và giá trị của callback thành tên của hàm mà bạn sẽ dùng để gửi mã uỷ quyền đến nền tảng của mình. Giá trị của redirect_uri mặc định là nguồn gốc của trang gọi initCodeClient. Giá trị này sẽ được dùng sau trong quy trình khi mã uỷ quyền được trao đổi để lấy mã truy cập hoặc mã làm mới. Ví dụ: https://www.example.com/index.html gọi initCodeClient và nguồn gốc: https://www.example.com là giá trị của redirect_url.

Bảo vệ khỏi các cuộc tấn công CSRF

Để ngăn chặn các cuộc tấn công Giả mạo yêu cầu trên nhiều trang web (CSRF), các kỹ thuật hơi khác nhau được sử dụng cho các luồng trải nghiệm người dùng ở chế độ Chuyển hướng và Cửa sổ bật lên. Đối với chế độ Chuyển hướng, tham số state của OAuth 2.0 sẽ được dùng. Hãy xem RFC6749 phần 10.12 Giả mạo yêu cầu trên nhiều trang web để biết thêm thông tin về cách tạo và xác thực tham số state. Với chế độ Cửa sổ bật lên, bạn sẽ thêm một tiêu đề HTTP tuỳ chỉnh vào các yêu cầu của mình, sau đó xác nhận trên máy chủ rằng tiêu đề đó khớp với giá trị và nguồn gốc dự kiến.

Chọn một chế độ trải nghiệm người dùng để xem đoạn mã cho thấy mã uỷ quyền và cách xử lý CSRF:

Chế độ chuyển hướng

Khởi chạy một ứng dụng khách mà Google chuyển hướng trình duyệt của người dùng đến điểm cuối xác thực của bạn, chia sẻ mã uỷ quyền dưới dạng một tham số URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Khởi chạy một ứng dụng mà người dùng bắt đầu quy trình uỷ quyền trong hộp thoại bật lên. Sau khi có sự đồng ý, Google sẽ trả về mã uỷ quyền cho trình duyệt của người dùng bằng cách sử dụng một hàm gọi lại. Yêu cầu POST từ trình xử lý lệnh gọi lại JS sẽ gửi mã uỷ quyền đến một điểm cuối trên máy chủ phụ trợ. Tại đây, mã này sẽ được xác minh trước, sau đó hoàn tất phần còn lại của quy trình OAuth.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

Kích hoạt quy trình mã OAuth 2.0

Gọi phương thức requestCode() của ứng dụng khách mã để kích hoạt quy trình người dùng:

<button onclick="client.requestCode();">Authorize with Google</button>

Thao tác này sẽ yêu cầu người dùng đăng nhập vào Tài khoản Google và đồng ý chia sẻ từng phạm vi trước khi trả về mã uỷ quyền cho điểm cuối chuyển hướng hoặc trình xử lý lệnh gọi lại của bạn.

Xử lý mã xác thực

Google tạo một mã uỷ quyền riêng biệt cho mỗi người dùng mà bạn nhận được và xác minh trên máy chủ phụ trợ.

Đối với chế độ Cửa sổ bật lên, trình xử lý do callback chỉ định, chạy trong trình duyệt của người dùng, sẽ chuyển mã uỷ quyền đến một điểm cuối do nền tảng của bạn lưu trữ.

Đối với chế độ Chuyển hướng, một yêu cầu GET sẽ được gửi đến điểm cuối do redirect_uri chỉ định, chia sẻ mã uỷ quyền trong tham số code của URL. Cách nhận mã uỷ quyền:

Tạo một Điểm cuối uỷ quyền mới nếu bạn chưa triển khai, hoặc
Cập nhật điểm cuối hiện có để chấp nhận các yêu cầu GET và tham số URL. Trước đây, một yêu cầu PUT có giá trị mã uỷ quyền trong tải trọng đã được sử dụng.

Điểm cuối uỷ quyền

Điểm cuối mã uỷ quyền của bạn phải xử lý các yêu cầu GET bằng các tham số chuỗi truy vấn URL sau:

Tên	Giá trị
authuser	Yêu cầu xác thực quy trình đăng nhập của người dùng
mã	Mã uỷ quyền OAuth2 do Google tạo
hd	Miền được lưu trữ của tài khoản người dùng
prompt	Hộp thoại đồng ý của người dùng
phạm vi	Danh sách được phân tách bằng dấu cách gồm một hoặc nhiều phạm vi OAuth2 cần được uỷ quyền
tiểu bang	Biến trạng thái CRSF

Ví dụ về yêu cầu GET có tham số URL đến một điểm cuối có tên là auth-code và được lưu trữ bởi example.com:

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

Khi quy trình mã uỷ quyền được khởi tạo bằng các thư viện JavaScript cũ hơn hoặc bằng các lệnh gọi trực tiếp đến các điểm cuối OAuth 2.0 của Google, yêu cầu POST sẽ được sử dụng.

Ví dụ về yêu cầu POST chứa mã uỷ quyền dưới dạng tải trọng trong phần nội dung yêu cầu HTTP:

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

Xác thực yêu cầu

Trên máy chủ của bạn, hãy làm như sau để tránh các cuộc tấn công CSRF.

Kiểm tra giá trị của tham số state (trạng thái) cho chế độ chuyển hướng.

Xác nhận rằng tiêu đề X-Requested-With: XmlHttpRequest được đặt cho chế độ cửa sổ bật lên.

Sau đó, bạn chỉ nên tiếp tục lấy mã làm mới và mã truy cập từ Google nếu trước tiên bạn đã xác minh thành công yêu cầu mã uỷ quyền.

Nhận mã truy cập và mã làm mới

Sau khi nền tảng phụ trợ của bạn nhận được mã uỷ quyền từ Google và xác minh yêu cầu, hãy sử dụng mã uỷ quyền đó để lấy mã truy cập và mã làm mới từ Google để thực hiện các lệnh gọi API.

Làm theo hướng dẫn bắt đầu từ Bước 5: Đổi mã uỷ quyền để lấy mã làm mới và mã truy cập trong hướng dẫn Sử dụng OAuth 2.0 cho ứng dụng máy chủ web.

Quản lý mã thông báo

Nền tảng của bạn lưu trữ mã làm mới một cách an toàn. Xoá mã làm mới đã lưu trữ khi tài khoản người dùng bị xoá hoặc người dùng thu hồi sự đồng ý bằng google.accounts.oauth2.revoke hoặc trực tiếp từ https://myaccount.google.com/permissions.

Bạn có thể cân nhắc sử dụng RISC để bảo vệ tài khoản người dùng bằng tính năng Bảo vệ trên nhiều tài khoản.

Thông thường, nền tảng phụ trợ của bạn sẽ gọi các API của Google bằng mã truy cập. Nếu ứng dụng web của bạn cũng sẽ trực tiếp gọi API Google từ trình duyệt của người dùng, thì bạn phải triển khai một cách để chia sẻ mã truy cập với ứng dụng web của mình. Việc này nằm ngoài phạm vi của hướng dẫn này. Khi làm theo phương pháp này và sử dụng Thư viện ứng dụng API của Google cho JavaScript, hãy dùng gapi.client.SetToken() để tạm thời lưu trữ mã truy cập trong bộ nhớ trình duyệt và cho phép thư viện gọi API của Google.