Sử dụng tính năng Liên kết Tài khoản Google với OAuth (Luồng ngầm định – Đã lưu trữ)

Để hỗ trợ quy trình ngầm định OAuth 2.0, dịch vụ của bạn cung cấp một điểm cuối uỷ quyền bằng HTTPS. Điểm cuối này chịu trách nhiệm xác thực và lấy sự đồng ý của người dùng đối với quyền truy cập dữ liệu. Điểm cuối uỷ quyền sẽ trình bày một giao diện người dùng đăng nhập cho những người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập được yêu cầu.

Khi một ứng dụng của Google cần gọi một trong các API được uỷ quyền của dịch vụ, Google sẽ dùng điểm cuối này để xin phép người dùng của bạn gọi các API này thay cho họ.

Liên kết tài khoản Google: Quy trình OAuth ngầm định

Sơ đồ trình tự sau đây trình bày chi tiết các hoạt động tương tác giữa Người dùng, Google và các điểm cuối của dịch vụ.

Người dùng Ứng dụng Google / Trình duyệt Điểm cuối xác thực 1. Người dùng bắt đầu liên kết 2. Chuyển hướng đến Điểm cuối uỷ quyền (GET) client_id, redirect_uri, state, scope 3. Hiển thị màn hình đăng nhập và màn hình đồng ý 4. Người dùng xác thực và cấp sự đồng ý 5. Chuyển hướng trở lại Google bằng mã thông báo (GET) access_token, state 6. Lưu trữ mã thông báo người dùng 7. Truy cập vào tài nguyên của người dùng
Hình 1. Trình tự các sự kiện trong luồng cấp quyền trực tiếp OAuth 2.0 để liên kết Tài khoản Google.

Vai trò và trách nhiệm

Bảng sau đây xác định vai trò và trách nhiệm của các tác nhân trong luồng cấp quyền trực tiếp OAuth của tính năng liên kết Tài khoản Google (GAL). Xin lưu ý rằng trong GAL, Google đóng vai trò là Ứng dụng OAuth, trong khi dịch vụ của bạn đóng vai trò là Nhà cung cấp dịch vụ/danh tính.

Người thực hiện / Thành phần Vai trò GAL Yêu cầu của công việc
Ứng dụng / Máy chủ của Google Ứng dụng OAuth Khởi tạo quy trình, nhận mã truy cập bằng cách sử dụng lệnh chuyển hướng của trình duyệt và lưu trữ mã này một cách an toàn để truy cập vào các API của dịch vụ.
Điểm cuối uỷ quyền của bạn Máy chủ uỷ quyền Xác thực người dùng, xin sự đồng ý của họ và cấp mã truy cập có thời hạn sử dụng lâu dài trực tiếp cho Google.
URI chuyển hướng của Google Điểm cuối gọi lại Nhận lệnh chuyển hướng người dùng từ dịch vụ uỷ quyền của bạn với các giá trị access_token và state trong đoạn URL.

Một phiên quy trình ngầm định OAuth 2.0 điển hình do Google khởi tạo có quy trình như sau:

  1. Google sẽ mở điểm cuối uỷ quyền của bạn trong trình duyệt của người dùng. Người dùng đăng nhập (nếu chưa đăng nhập) và cấp cho Google quyền truy cập vào dữ liệu của họ bằng API của bạn (nếu họ chưa cấp quyền).
  2. Dịch vụ của bạn tạo một mã truy cập và trả mã này về cho Google. Để làm như vậy, hãy chuyển hướng trình duyệt của người dùng trở lại Google bằng mã truy cập được đính kèm vào yêu cầu.
  3. Google gọi các API của dịch vụ và đính kèm mã truy cập với từng yêu cầu. Dịch vụ của bạn xác minh rằng mã truy cập cấp cho Google quyền truy cập vào API, sau đó hoàn tất lệnh gọi API.

Công thức triển khai

Hãy làm theo các bước sau để triển khai luồng cấp quyền trực tiếp.

Bước 1: Xử lý yêu cầu uỷ quyền

Khi Google bắt đầu liên kết tài khoản, Google sẽ chuyển hướng người dùng đến điểm cuối uỷ quyền của bạn. Để biết các hợp đồng giao thức và yêu cầu về tham số chi tiết, hãy xem Điểm cuối uỷ quyền.

Để xử lý yêu cầu, hãy thực hiện các thao tác sau:

  1. Xác thực yêu cầu:

    • Xác nhận rằng client_id khớp với Mã ứng dụng khách được chỉ định cho Google.
    • Xác nhận rằng redirect_uri khớp với URL chuyển hướng dự kiến của Google: none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
    • Xác minh rằng response_type là token.

  2. Xác thực người dùng:

    • Kiểm tra xem người dùng đã đăng nhập vào dịch vụ của bạn hay chưa.
    • Nếu người dùng chưa đăng nhập, hãy nhắc họ hoàn tất quy trình đăng nhập hoặc đăng ký của bạn.

  3. Tạo mã truy cập:

    • Tạo mã truy cập duy nhất, không đoán được, được liên kết với người dùng và ứng dụng.

  4. Chuyển hướng trở lại Google:

    • Chuyển hướng trình duyệt đến URL được cung cấp trong redirect_uri.
    • Thêm các tham số sau vào phân mảnh của URL (dấu băm):
      • access_token: Mã truy cập mà bạn đã tạo.
      • token_type: Phải là bearer.
      • state: Giá trị trạng thái chưa được sửa đổi nhận được từ Google.
Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.