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 uỷ quyền từ Google bằng cách sử dụng luồng Trải nghiệm người dùng bật lên hoặc chuyển hướng dựa trên trình duyệt. Chiến dịch này bắt đầu một quy trình OAuth 2.0 bảo mật và dẫn đến một mã truy cập dùng để gọi API của Google thay mặt người dùng.

Tóm tắt quy trình mã uỷ quyền OAuth 2.0:

• Từ một trình duyệt, bằng một cử chỉ như nhấp vào nút, Tài khoản Google chủ sở hữu yêu cầu Google gửi mã uỷ quyền.
• Google phản hồi, gửi một mã uỷ quyền duy nhất tới cuộc 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 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 của mã uỷ quyền và nhận . Sau khi xác thực, mã này được đổi lấy theo quyền truy cập của người dùng và làm mới mã thông báo bằng cách yêu cầu đ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 yêu cầu đã được gửi từ nền tảng bảo mật của mình, cấp mã truy cập và mã làm mới, đồng thời trả về mã thông báo 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, lưu trữ an toàn mã làm mới để sử dụng sau này.

Khởi chạy Ứng dụng mã

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 cách sử dụng nút Chuyển hướng hoặc Luồng người dùng ở chế độ Cửa sổ bật lên. Với chế độ Chuyển hướng, bạn lưu trữ yêu cầu uỷ quyền OAuth2 điểm cuối trên máy chủ của bạn và Google sẽ chuyển hướng tác nhân người dùng đến điểm cuối này, dùng chung mã uỷ quyền dưới dạng tham số URL. Đối với chế độ Cửa sổ bật lên, bạn xác định JavaScript trình xử lý gọi lại để gửi mã uỷ quyền đến máy chủ của bạn. Chế độ cửa sổ bật lên có thể được dùng để cung cấp trải nghiệm người dùng liền mạch mà không cần khách truy cập rời khỏi trang web của bạn.

Để khởi chạy ứ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 đến điểm cuối mã uỷ quyền của nền tảng. Giá trị phải khớp chính xác với một trong các URI chuyển hướng được phép cho OAuth 2.0 mà bạn đã định cấu hình trong Bảng điều khiển API. Chính sách này cũng phải tuân thủ Quy tắc xác thực URI chuyển hướng.

• Luồng bật lên trải nghiệm người dùng, đặt ux_mode thành popup và giá trị của callback thành tên của chức năng mà bạn sẽ sử dụng để gửi mã uỷ quyền đến chủ.

Ngăn chặn các cuộc tấn công CSRF

Để giúp ngăn chặn các cuộc tấn công giả mạo trên nhiều trang web (CSRF) có đôi chút khác biệt các kỹ thuật đượ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. Để chuyển hướng thì tham số state của OAuth 2.0 sẽ được sử dụng. Xem phần 10.12 RFC6749 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 thông số state. Với chế độ Cửa sổ bật lên, bạn thêm một tiêu đề HTTP tùy chỉnh vào yêu cầu của mình, rồi sau đó máy chủ xác nhận giá trị đó khớp với giá trị và nguồn gốc dự kiến.

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

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: "https://your.domain/code_callback_endpoint",
  state: "YOUR_BINDING_VALUE"
});

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', code_receiver_uri, 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 luồng mã OAuth 2.0

Gọi phương thức requestCode() của ứng dụng mã để kích hoạt luồng 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ẻ các phạm vi riêng lẻ trước khi trả lại mã uỷ quyền cho chuyển hướng điểm cuối hoặc trình xử lý gọi lại.

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

Google tạo một mã uỷ quyền duy nhấ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 của trình duyệt, sẽ chuyển tiếp mã uỷ quyền đó đến điểm cuối do nền tảng của bạn lưu trữ.

Đối với chế độ Chuyển hướng, yêu cầu GET được gửi đến điểm cuối được chỉ định bởi redirect_url, chia sẻ mã uỷ quyền trong tham số mã URL. Người nhận nhận mã uỷ quyền:

• Tạo Điểm cuối ủy quyền mới nếu bạn chưa có triển khai, hoặc

• Cập nhật điểm cuối hiện có để chấp nhận yêu cầu GET và URL tham số. Trước đây, 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 truy vấn URL này tham số chuỗi:

Ví dụ về yêu cầu GET có các tham số URL đến điểm cuối có tên 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 bắt đầu bởi các thư viện JavaScript trước đó, hoặc bằng các lệnh gọi trực tiếp đến các điểm cuối của Google OAuth 2.0, thì 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 một tải trọng trong 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 để giúp tránh các cuộc tấn công CSRF.

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

Xác nhận tiêu đề X-Requested-With: XmlHttpRequest được đặt cho chế độ bật lên.

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

Nhận mã truy cập và 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, sử dụng mã xác thực để lấy mã truy cập và làm mới từ Google để thực hiện lệnh gọi API.

Làm theo hướng dẫn bắt đầu ở Bước 5: Mã ủy quyền trao đổi cho làm mới và truy cập mã thông báo của phần Sử dụng OAuth 2.0 cho Máy chủ web Hướng dẫn về ứng dụng.

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

Nền tảng của bạn sẽ 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 thu hồi sự đồng ý của người dùng trước google.accounts.oauth2.revoke hoặc trực tiếp từ https://myaccount.google.com/permissions.

Nếu muốn, 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 Nhiều tài khoản Khả năng bảo vệ.

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