Kết nối mở

Bạn có thể sử dụng API OAuth 2.0 của Google cho cả việc xác thực và uỷ quyền. Tài liệu này mô tả cách triển khai OAuth 2.0 để xác thực, tuân thủ quy cách OpenID Connect và được Chứng nhận OpenID. Tài liệu trong bài viết Sử dụng OAuth 2.0 để truy cập vào API của Google cũng áp dụng cho dịch vụ này. Nếu muốn khám phá giao thức này theo cách tương tác, bạn nên sử dụng Google OAuth 2.0 Playground. Để được trợ giúp trên Stack Overflow, hãy gắn thẻ "google-oauth" cho câu hỏi của bạn.

Thiết lập OAuth 2.0

Trước khi ứng dụng của bạn có thể sử dụng hệ thống xác thực OAuth 2.0 của Google để người dùng đăng nhập, bạn phải thiết lập một dự án trong Google API Console để lấy thông tin xác thực OAuth 2.0, đặt URI chuyển hướng và (không bắt buộc) tuỳ chỉnh thông tin thương hiệu mà người dùng nhìn thấy trên màn hình yêu cầu người dùng đồng ý. Bạn cũng có thể sử dụng API Console để tạo tài khoản dịch vụ, bật tính năng thanh toán, thiết lập tính năng lọc và thực hiện các tác vụ khác. Để biết thêm thông tin, hãy xem nội dung Trợ giúp vềGoogle API Console.

Lấy thông tin xác thực OAuth 2.0

Bạn cần có thông tin xác thực OAuth 2.0, bao gồm mã ứng dụng và khoá bí mật của ứng dụng, để xác thực người dùng và có quyền truy cập vào các API của Google.

Để xem ID khách hàng và bí mật của máy khách đối với thông tin xác thực OAuth 2.0, nhấp vào văn bản sau: Chọn thông tin xác thực . Trong cửa sổ mở ra, chọn dự án của bạn và thông tin đăng nhập bạn muốn, sau đó bấm Xem .

Hoặc, xem ID khách hàng và bí mật khách hàng của bạn từ trang Thông tin xác thực trong API Console :

  1. Go to the Credentials page.
  2. Nhấp vào tên của thông tin đăng nhập của bạn hoặc biểu tượng bút chì ( ). ID khách hàng và bí mật của bạn nằm ở đầu trang.

Đặt URI chuyển hướng

URI chuyển hướng mà bạn đặt trong API Console xác định nơi Google gửi phản hồi cho yêu cầu xác thực của bạn.

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

  1. Go to the Credentials page.
  2. In the OAuth 2.0 client IDs section of the page, click a credential.
  3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Tuỳ chỉnh màn hình yêu cầu đồng ý của người dùng

Đối với người dùng, trải nghiệm xác thực OAuth 2.0 bao gồm một màn hình đồng ý mô tả thông tin mà người dùng đang tiết lộ và các điều khoản áp dụng. Ví dụ: khi đăng nhập, người dùng có thể được yêu cầu cấp cho ứng dụng của bạn quyền truy cập vào địa chỉ email và thông tin tài khoản cơ bản của họ. Bạn yêu cầu quyền truy cập vào thông tin này bằng cách sử dụng thông số scope mà ứng dụng của bạn đưa vào yêu cầu xác thực. Bạn cũng có thể sử dụng phạm vi để yêu cầu quyền truy cập vào các API khác của Google.

Màn hình yêu cầu người dùng đồng ý cũng trình bày thông tin thương hiệu như tên sản phẩm, biểu trưng và URL trang chủ. Bạn kiểm soát thông tin thương hiệu trong API Console.

To enable your project's consent screen:

  1. Open the Consent Screen page in the Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Fill out the form and click Save.

Hộp thoại đồng ý sau đây cho biết nội dung mà người dùng sẽ thấy khi yêu cầu có cả phạm vi OAuth 2.0 và Google Drive. (Hộp thoại chung này được tạo bằng Google OAuth 2.0 Playground, vì vậy, hộp thoại này không bao gồm thông tin thương hiệu sẽ được đặt trong API Console.)

Ảnh chụp màn hình trang đồng ý

Truy cập vào dịch vụ

Google và các bên thứ ba cung cấp các thư viện mà bạn có thể sử dụng để xử lý nhiều thông tin chi tiết về việc triển khai xác thực người dùng và cấp quyền truy cập vào các API của Google. Ví dụ bao gồm Dịch vụ nhận dạng của Googlethư viện ứng dụng của Google, được cung cấp cho nhiều nền tảng.

Nếu bạn chọn không sử dụng thư viện, hãy làm theo hướng dẫn trong phần còn lại của tài liệu này. Phần này mô tả các luồng yêu cầu HTTP cơ bản của các thư viện hiện có.

Xác thực người dùng

Quá trình xác thực người dùng bao gồm việc lấy mã thông báo nhận dạng và xác thực mã đó. Mã thông báo nhận dạng là một tính năng được chuẩn hoá của OpenID Connect, được thiết kế để sử dụng trong việc chia sẻ thông tin xác nhận danh tính trên Internet.

Các phương pháp phổ biến nhất dùng để xác thực người dùng và lấy mã thông báo nhận dạng được gọi là luồng "máy chủ" và luồng "ngầm ẩn". Luồng máy chủ cho phép máy chủ phụ trợ của một ứng dụng xác minh danh tính của người dùng bằng trình duyệt hoặc thiết bị di động. Luồng ngầm ẩn được dùng khi một ứng dụng phía máy khách (thường là ứng dụng JavaScript chạy trong trình duyệt) cần truy cập trực tiếp vào các API thay vì thông qua máy chủ phụ trợ.

Tài liệu này mô tả cách thực hiện quy trình xác thực người dùng phía máy chủ. Quy trình ngầm ẩn phức tạp hơn đáng kể do các rủi ro bảo mật trong việc xử lý và sử dụng mã thông báo ở phía máy khách. Nếu cần triển khai luồng ngầm ẩn, bạn nên sử dụng Dịch vụ nhận dạng của Google.

Luồng máy chủ

Hãy nhớ thiết lập ứng dụng của bạn trong API Console để cho phép ứng dụng sử dụng các giao thức này và xác thực người dùng. Khi người dùng cố gắng đăng nhập bằng Google, bạn cần:

  1. Tạo mã thông báo trạng thái chống giả mạo
  2. Gửi yêu cầu xác thực đến Google
  3. Xác nhận mã thông báo trạng thái chống giả mạo
  4. Trao đổi code để lấy mã truy cập và mã nhận dạng
  5. Lấy thông tin người dùng từ mã thông báo nhận dạng
  6. Xác thực người dùng

1. Tạo mã thông báo trạng thái chống giả mạo

Bạn phải bảo vệ sự an toàn của người dùng bằng cách ngăn chặn các cuộc tấn công giả mạo yêu cầu. Bước đầu tiên là tạo một mã thông báo phiên duy nhất lưu giữ trạng thái giữa ứng dụng và ứng dụng của người dùng. Sau đó, bạn sẽ so khớp mã thông báo phiên duy nhất này với phản hồi xác thực do dịch vụ Đăng nhập bằng OAuth của Google trả về để xác minh rằng người dùng đang đưa ra yêu cầu chứ không phải là kẻ tấn công độc hại. Những mã thông báo này thường được gọi là mã thông báo giả mạo yêu cầu trên nhiều trang web (CSRF).

Một lựa chọn phù hợp cho mã thông báo trạng thái là một chuỗi gồm khoảng 30 ký tự được tạo bằng trình tạo số ngẫu nhiên chất lượng cao. Một cách khác là băm được tạo bằng cách ký một số biến trạng thái phiên bằng khoá được giữ bí mật ở phần phụ trợ.

Mã sau đây minh hoạ cách tạo mã thông báo phiên duy nhất.

PHP

Bạn phải tải thư viện ứng dụng API của Google cho PHP xuống để sử dụng mẫu này.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Bạn phải tải thư viện ứng dụng API của Google dành cho Java xuống để sử dụng mẫu này.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Bạn phải tải thư viện ứng dụng API của Google cho Python xuống để sử dụng mẫu này.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Gửi yêu cầu xác thực đến Google

Bước tiếp theo là tạo một yêu cầu GET HTTPS bằng các tham số URI thích hợp. Xin lưu ý việc sử dụng HTTPS thay vì HTTP trong tất cả các bước của quy trình này; các kết nối HTTP sẽ bị từ chối. Bạn nên truy xuất URI cơ sở từ tài liệu Khám phá bằng giá trị siêu dữ liệu authorization_endpoint. Phần thảo luận sau đây giả định rằng URI cơ sở là https://accounts.google.com/o/oauth2/v2/auth.

Đối với yêu cầu cơ bản, hãy chỉ định các tham số sau:

  • client_id mà bạn nhận được từ API Console Credentials page.
  • response_type, trong yêu cầu quy trình sử dụng mã uỷ quyền cơ bản phải là code. (Đọc thêm tại response_type.)
  • scope, trong một yêu cầu cơ bản phải là openid email. (Đọc thêm tại scope.)
  • redirect_uri phải là điểm cuối HTTP trên máy chủ của bạn để nhận phản hồi từ Google. 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 API Console Credentials page. Nếu giá trị này không khớp với URI được uỷ quyền, yêu cầu sẽ không thành công và báo lỗi redirect_uri_mismatch.
  • state phải bao gồm giá trị của mã thông báo phiên duy nhất chống giả mạo, cũng như mọi thông tin khác cần thiết để khôi phục ngữ cảnh khi người dùng quay lại ứng dụng, ví dụ: URL bắt đầu. (Đọc thêm tại state.)
  • nonce là một giá trị ngẫu nhiên do ứng dụng của bạn tạo ra, cho phép tính năng chống phát lại khi có.
  • login_hint có thể là địa chỉ email của người dùng hoặc chuỗi sub, tương đương với mã nhận dạng Google của người dùng. Nếu bạn không cung cấp login_hint và người dùng hiện đã đăng nhập, thì màn hình đồng ý sẽ bao gồm một yêu cầu phê duyệt để phát hành địa chỉ email của người dùng cho ứng dụng của bạn. (Đọc thêm tại login_hint.)
  • Sử dụng thông số hd để tối ưu hoá quy trình OpenID Connect cho người dùng của một miền cụ thể được liên kết với một tổ chức Google Workspace hoặc Cloud (đọc thêm tại hd).

Sau đây là ví dụ về một URI xác thực OpenID Connect hoàn chỉnh, có dấu ngắt dòng và dấu cách để dễ đọc:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Người dùng phải đồng ý nếu ứng dụng của bạn yêu cầu bất kỳ thông tin mới nào về họ hoặc nếu ứng dụng của bạn yêu cầu quyền truy cập vào tài khoản mà trước đó họ chưa phê duyệt.

3. Xác nhận mã thông báo trạng thái chống giả mạo

Phản hồi được gửi đến redirect_uri mà bạn đã chỉ định trong yêu cầu. Tất cả phản hồi đều được trả về trong chuỗi truy vấn, như minh hoạ bên dưới:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Trên máy chủ, bạn phải xác nhận rằng state nhận được từ Google khớp với mã thông báo phiên mà bạn đã tạo ở Bước 1. Quy trình xác minh khứ hồi này giúp đảm bảo rằng người dùng, chứ không phải một tập lệnh độc hại, đang đưa ra yêu cầu.

Mã sau đây minh hoạ cách xác nhận mã thông báo phiên mà bạn đã tạo ở Bước 1:

PHP

Bạn phải tải thư viện ứng dụng API của Google cho PHP xuống để sử dụng mẫu này.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Bạn phải tải thư viện ứng dụng API của Google dành cho Java xuống để sử dụng mẫu này.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Bạn phải tải thư viện ứng dụng API của Google cho Python xuống để sử dụng mẫu này.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Trao đổi code để lấy mã thông báo truy cập và mã thông báo nhận dạng

Phản hồi bao gồm một tham số code, một mã uỷ quyền một lần mà máy chủ của bạn có thể trao đổi lấy mã truy cập và mã nhận dạng. Máy chủ của bạn thực hiện việc trao đổi này bằng cách gửi yêu cầu POST HTTPS. Yêu cầu POST được gửi đến điểm cuối mã thông báo mà bạn nên truy xuất từ tài liệu Khám phá bằng cách sử dụng giá trị siêu dữ liệu token_endpoint. Phần thảo luận sau đây giả định điểm cuối là https://oauth2.googleapis.com/token. Yêu cầu phải bao gồm các tham số sau trong phần nội dung POST:

Trường
code Mã uỷ quyền được trả về từ yêu cầu ban đầu.
client_id Mã ứng dụng mà bạn nhận được từ API Console Credentials page, như mô tả trong phần Nhận thông tin xác thực OAuth 2.0.
client_secret Khoá bí mật ứng dụng mà bạn nhận được từ API Console Credentials page, như mô tả trong phần Nhận thông tin xác thực OAuth 2.0.
redirect_uri URI chuyển hướng được uỷ quyền cho client_id đã cho được chỉ định trong API Console Credentials page, như mô tả trong phần Đặt URI chuyển hướng.
grant_type Trường này phải chứa giá trị authorization_code, như được xác định trong quy cách OAuth 2.0.

Yêu cầu thực tế có thể có dạng như ví dụ sau:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Phản hồi thành công cho yêu cầu này chứa các trường sau trong một mảng JSON:

Trường
access_token Mã thông báo có thể được gửi đến một API của Google.
expires_in Thời gian còn lại của mã truy cập tính bằng giây.
id_token JWT chứa thông tin nhận dạng về người dùng do Google ký bằng chữ ký số.
scope Phạm vi truy cập do access_token cấp được biểu thị dưới dạng danh sách các chuỗi phân tách bằng dấu cách, phân biệt chữ hoa chữ thường.
token_type Xác định loại mã thông báo được trả về. Tại thời điểm này, trường này luôn có giá trị Bearer.
refresh_token (không bắt buộc)

Trường này chỉ xuất hiện nếu tham số access_type được đặt thành offline trong yêu cầu xác thực. Để biết thông tin chi tiết, hãy xem phần Mã thông báo làm mới.

5. Lấy thông tin người dùng từ mã thông báo nhận dạng

Mã thông báo nhận dạng là JWT (Mã thông báo web JSON), tức là một đối tượng JSON được mã hoá Base64 và được ký bằng phương thức mã hoá. Thông thường, bạn cần xác thực mã thông báo nhận dạng trước khi sử dụng, nhưng vì bạn đang giao tiếp trực tiếp với Google qua một kênh HTTPS không có trung gian và sử dụng khoá bí mật ứng dụng để xác thực chính mình với Google, nên bạn có thể yên tâm rằng mã thông báo bạn nhận được thực sự đến từ Google và hợp lệ. Nếu máy chủ của bạn truyền mã thông báo nhận dạng đến các thành phần khác của ứng dụng, thì điều cực kỳ quan trọng là các thành phần khác phải xác thực mã thông báo trước khi sử dụng.

Vì hầu hết các thư viện API kết hợp việc xác thực với việc giải mã các giá trị được mã hoá base64url và phân tích cú pháp JSON trong đó, nên có thể bạn sẽ xác thực mã thông báo khi truy cập vào các thông báo xác nhận trong mã thông báo nhận dạng.

Trọng tải của mã thông báo nhận dạng

Mã thông báo nhận dạng là một đối tượng JSON chứa một tập hợp các cặp tên/giá trị. Sau đây là một ví dụ, được định dạng để dễ đọc:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Mã thông báo nhận dạng của Google có thể chứa các trường sau (còn gọi là thông báo xác nhận quyền):

Xác nhận quyền sở hữu Đã cung cấp Mô tả
aud mọi lúc Đối tượng mà mã thông báo nhận dạng này dành cho. Mã này phải là một trong các mã ứng dụng khách OAuth 2.0 của ứng dụng.
exp mọi lúc Thời gian hết hạn mà sau đó mã thông báo nhận dạng không được chấp nhận. Được biểu thị bằng thời gian Unix (giây số nguyên).
iat mọi lúc Thời gian mã thông báo nhận dạng được phát hành. Được biểu thị theo thời gian Unix (số nguyên giây).
iss mọi lúc Giá trị nhận dạng của tổ chức phát hành cho Tổ chức phát hành của nội dung phản hồi. Luôn là https://accounts.google.com hoặc accounts.google.com đối với mã thông báo nhận dạng của Google.
sub mọi lúc Giá trị nhận dạng cho người dùng, duy nhất trong tất cả các Tài khoản Google và không bao giờ được sử dụng lại. Một Tài khoản Google có thể có nhiều địa chỉ email tại các thời điểm khác nhau, nhưng giá trị sub không bao giờ thay đổi. Sử dụng sub trong ứng dụng của bạn làm khoá giá trị nhận dạng duy nhất cho người dùng. Độ dài tối đa là 255 ký tự ASCII phân biệt chữ hoa chữ thường.
at_hash Giá trị băm mã truy cập. Cung cấp thông tin xác thực rằng mã thông báo truy cập được liên kết với mã thông báo danh tính. Nếu mã thông báo nhận dạng được phát hành bằng giá trị access_token trong luồng máy chủ, thì thông báo xác nhận này sẽ luôn được đưa vào. Bạn có thể sử dụng thông báo xác nhận này làm cơ chế thay thế để bảo vệ khỏi các cuộc tấn công giả mạo yêu cầu trên nhiều trang web, nhưng nếu làm theo Bước 1Bước 3 thì bạn không cần xác minh mã thông báo truy cập.
azp client_id của người trình bày được uỷ quyền. Bạn chỉ cần thông báo xác nhận này khi bên yêu cầu mã thông báo nhận dạng không phải là đối tượng của mã thông báo nhận dạng. Đây có thể là trường hợp tại Google đối với các ứng dụng kết hợp, trong đó ứng dụng web và ứng dụng Android có client_id OAuth 2.0 khác nhau nhưng dùng chung một dự án API của Google.
email Địa chỉ email của người dùng. Chỉ được cung cấp nếu bạn đưa phạm vi email vào yêu cầu. Giá trị của thông báo xác nhận quyền sở hữu này có thể không dành riêng cho tài khoản này và có thể thay đổi theo thời gian, do đó, bạn không nên sử dụng giá trị này làm giá trị nhận dạng chính để liên kết với bản ghi người dùng của mình. Bạn cũng không thể dựa vào miền của thông báo xác nhận quyền sở hữu email để xác định người dùng của các tổ chức Google Workspace hoặc Cloud; thay vào đó, hãy sử dụng thông báo xác nhận quyền sở hữu hd.
email_verified Đúng nếu địa chỉ email của người dùng đã được xác minh; nếu không thì sai.
family_name (Các) họ của người dùng. Có thể được cung cấp khi có thông báo xác nhận quyền sở hữu name.
given_name (Các) tên hoặc tên đệm của người dùng. Có thể được cung cấp khi có thông báo xác nhận quyền sở hữu name.
hd Miền được liên kết với tổ chức Google Workspace hoặc Cloud của người dùng. Chỉ được cung cấp nếu người dùng thuộc một tổ chức Google Cloud. Bạn phải chọn thông báo xác nhận quyền sở hữu này khi chỉ cho phép thành viên của một số miền nhất định truy cập vào tài nguyên. Việc không có thông báo xác nhận quyền sở hữu này cho biết rằng tài khoản không thuộc về một miền do Google lưu trữ.
locale Ngôn ngữ của người dùng, được biểu thị bằng thẻ ngôn ngữ BCP 47. Có thể được cung cấp khi có thông báo xác nhận quyền sở hữu name.
name Họ và tên của người dùng, ở dạng có thể hiển thị. Có thể được cung cấp khi:
  • Phạm vi yêu cầu bao gồm chuỗi "hồ sơ"
  • Mã thông báo nhận dạng được trả về từ một lượt làm mới mã thông báo

Khi có các thông báo xác nhận quyền sở hữu name, bạn có thể sử dụng các thông báo này để cập nhật bản ghi người dùng của ứng dụng. Xin lưu ý rằng thông báo xác nhận quyền sở hữu này không phải lúc nào cũng xuất hiện.

nonce Giá trị của nonce do ứng dụng của bạn cung cấp trong yêu cầu xác thực. Bạn nên thực thi biện pháp bảo vệ chống lại các cuộc tấn công phát lại bằng cách đảm bảo rằng biện pháp này chỉ được hiển thị một lần.
picture URL của ảnh hồ sơ của người dùng. Có thể được cung cấp khi:
  • Phạm vi yêu cầu bao gồm chuỗi "hồ sơ"
  • Mã thông báo nhận dạng được trả về từ một lượt làm mới mã thông báo

Khi có các thông báo xác nhận quyền sở hữu picture, bạn có thể sử dụng các thông báo này để cập nhật bản ghi người dùng của ứng dụng. Xin lưu ý rằng thông báo xác nhận quyền sở hữu này không phải lúc nào cũng xuất hiện.

profile URL của trang hồ sơ của người dùng. Có thể được cung cấp khi:
  • Phạm vi yêu cầu bao gồm chuỗi "hồ sơ"
  • Mã thông báo nhận dạng được trả về từ một lượt làm mới mã thông báo

Khi có các thông báo xác nhận quyền sở hữu profile, bạn có thể sử dụng các thông báo này để cập nhật bản ghi người dùng của ứng dụng. Xin lưu ý rằng thông báo xác nhận quyền sở hữu này không phải lúc nào cũng xuất hiện.

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

Sau khi lấy thông tin người dùng từ mã thông báo nhận dạng, bạn nên truy vấn cơ sở dữ liệu người dùng của ứng dụng. Nếu người dùng đã tồn tại trong cơ sở dữ liệu, bạn nên bắt đầu một phiên ứng dụng cho người dùng đó nếu phản hồi API của Google đáp ứng tất cả các yêu cầu đăng nhập.

Nếu người dùng không tồn tại trong cơ sở dữ liệu người dùng, bạn nên chuyển hướng người dùng đến quy trình đăng ký người dùng mới. Bạn có thể tự động đăng ký người dùng dựa trên thông tin nhận được từ Google, hoặc ít nhất là có thể điền sẵn nhiều trường mà bạn yêu cầu trên biểu mẫu đăng ký. Ngoài thông tin trong mã thông báo nhận dạng, bạn có thể nhận thêm thông tin hồ sơ người dùng tại các điểm cuối hồ sơ người dùng của chúng tôi.

Chủ đề nâng cao

Các phần sau đây mô tả chi tiết hơn về API Google OAuth 2.0. Thông tin này dành cho nhà phát triển có các yêu cầu nâng cao về việc xác thực và uỷ quyền.

Quyền truy cập vào các API khác của Google

Một trong những lợi thế của việc sử dụng OAuth 2.0 để xác thực là ứng dụng của bạn có thể nhận quyền thay mặt người dùng sử dụng các API khác của Google (chẳng hạn như YouTube, Google Drive, Lịch hoặc Danh bạ) cùng lúc với việc xác thực người dùng. Để thực hiện việc này, hãy thêm các phạm vi khác mà bạn cần vào yêu cầu xác thực mà bạn gửi đến Google. Ví dụ: để thêm nhóm tuổi của người dùng vào yêu cầu xác thực, hãy truyền tham số phạm vi của openid email https://www.googleapis.com/auth/profile.agerange.read. Người dùng được nhắc một cách phù hợp trên màn hình yêu cầu đồng ý. Mã truy cập mà bạn nhận được từ Google cho phép bạn truy cập vào tất cả các API liên quan đến phạm vi truy cập mà bạn đã yêu cầu và được cấp.

Mã thông báo làm mới

Trong yêu cầu truy cập API, bạn có thể yêu cầu mã thông báo làm mới được trả về trong quá trình giao dịch code. Mã thông báo làm mới cung cấp cho ứng dụng của bạn quyền truy cập liên tục vào các API của Google trong khi người dùng không có mặt trong ứng dụng. Để yêu cầu mã thông báo làm mới, hãy thêm tham số access_type vào offline trong yêu cầu xác thực.

Những điều cần lưu ý:

  • Hãy nhớ lưu trữ mã thông báo làm mới một cách an toàn và vĩnh viễn, vì bạn chỉ có thể nhận được mã thông báo làm mới trong lần đầu tiên thực hiện quy trình trao đổi mã.
  • Có giới hạn về số lượng mã thông báo làm mới được phát hành: một giới hạn cho mỗi tổ hợp ứng dụng/người dùng và một giới hạn khác cho mỗi người dùng trên tất cả ứng dụng. Nếu ứng dụng của bạn yêu cầu quá nhiều mã thông báo làm mới, thì ứng dụng có thể gặp phải các giới hạn này. Trong trường hợp đó, các mã thông báo làm mới cũ sẽ ngừng hoạt động.

Để biết thêm thông tin, hãy xem phần Làm mới mã truy cập (quyền truy cập ngoại tuyến).

Bạn có thể nhắc người dùng uỷ quyền lại cho ứng dụng của mình bằng cách đặt thông số prompt thành consent trong yêu cầu xác thực. Khi prompt=consent được đưa vào, màn hình yêu cầu sự đồng ý sẽ xuất hiện mỗi khi ứng dụng của bạn yêu cầu cấp quyền truy cập vào các phạm vi, ngay cả khi tất cả các phạm vi trước đó đã được cấp cho dự án API của Google. Vì lý do này, chỉ đưa prompt=consent vào khi cần thiết.

Để biết thêm về tham số prompt, hãy xem prompt trong bảng Thông số URI xác thực.

Tham số URI xác thực

Bảng sau đây cung cấp nội dung mô tả đầy đủ hơn về các tham số mà API xác thực OAuth 2.0 của Google chấp nhận.

Thông số Bắt buộc Mô tả
client_id (Bắt buộc) Chuỗi mã ứng dụng khách mà bạn nhận được từ API Console Credentials page, như mô tả trong phần Nhận thông tin xác thực OAuth 2.0.
nonce (Bắt buộc) Một giá trị ngẫu nhiên do ứng dụng của bạn tạo ra để bật tính năng chống phát lại.
response_type (Bắt buộc) Nếu giá trị là code, hãy chạy quy trình mã uỷ quyền cơ bản, yêu cầu POST đến điểm cuối mã thông báo để lấy mã thông báo. Nếu giá trị là token id_token hoặc id_token token, hãy chạy một luồng ngầm ẩn, yêu cầu sử dụng JavaScript tại URI chuyển hướng để truy xuất mã thông báo từ giá trị nhận dạng URI #fragment.
redirect_uri (Bắt buộc) Xác định nơi gửi phản hồi. Giá trị của thông số này phải khớp chính xác với một trong các giá trị chuyển hướng được uỷ quyền mà bạn đặt trong API Console Credentials page (bao gồm cả giao thức HTTP hoặc HTTPS, trường hợp và dấu "/" ở cuối, nếu có).
scope (Bắt buộc)

Tham số phạm vi phải bắt đầu bằng giá trị openid, sau đó bao gồm giá trị profile, giá trị email hoặc cả hai.

Nếu có giá trị phạm vi profile, thì mã thông báo nhận dạng có thể (nhưng không được đảm bảo) bao gồm các thông báo xác nhận quyền sở hữu profile mặc định của người dùng.

Nếu có giá trị phạm vi email, thì mã thông báo nhận dạng sẽ bao gồm các thông báo xác nhận quyền emailemail_verified.

Ngoài các phạm vi dành riêng cho OpenID này, đối số phạm vi của bạn cũng có thể bao gồm các giá trị phạm vi khác. Tất cả giá trị phạm vi phải được phân tách bằng dấu cách. Ví dụ: nếu bạn muốn quyền truy cập theo tệp vào Google Drive của người dùng, tham số phạm vi của bạn có thể là openid profile email https://www.googleapis.com/auth/drive.file.

Để biết thông tin về các phạm vi hiện có, hãy xem nội dung Phạm vi OAuth 2.0 cho các API của Google hoặc tài liệu về API của Google mà bạn muốn sử dụng.

state (Không bắt buộc nhưng bạn nên thực hiện)

Một chuỗi mờ được trả về trong giao thức; tức là chuỗi này được trả về dưới dạng tham số URI trong luồng Cơ bản và trong giá trị nhận dạng URI #fragment trong luồng Ngầm ẩn.

state có thể hữu ích để liên kết các yêu cầu và phản hồi. Vì redirect_uri của bạn có thể bị đoán được, nên việc sử dụng giá trị state có thể giúp bạn tăng độ tin cậy rằng một kết nối đến là kết quả của một yêu cầu xác thực do ứng dụng của bạn khởi tạo. Nếu tạo một chuỗi ngẫu nhiên hoặc mã hoá hàm băm của một số trạng thái ứng dụng (ví dụ: cookie) trong biến state này, bạn có thể xác thực phản hồi để đảm bảo thêm rằng yêu cầu và phản hồi bắt nguồn từ cùng một trình duyệt. Điều này giúp bảo vệ khỏi các cuộc tấn công như giả mạo yêu cầu trên nhiều trang web.

access_type (Không bắt buộc) Các giá trị được phép là offlineonline. Hiệu ứng này được ghi lại trong phần Truy cập ngoại tuyến; nếu một mã truy cập đang được yêu cầu, thì ứng dụng sẽ không nhận được mã làm mới trừ khi bạn chỉ định giá trị offline.
display (Không bắt buộc) Giá trị chuỗi ASCII để chỉ định cách máy chủ uỷ quyền hiển thị các trang giao diện người dùng xác thực và đồng ý. Các giá trị sau đây được chỉ định và máy chủ của Google chấp nhận, nhưng không ảnh hưởng đến hành vi của máy chủ: page, popup, touchwap.
hd (Không bắt buộc)

Đơn giản hoá quy trình đăng nhập cho các tài khoản thuộc sở hữu của một tổ chức Google Cloud. Bằng cách đưa vào miền tổ chức Google Cloud (ví dụ: mycollege.edu), bạn có thể cho biết rằng giao diện người dùng lựa chọn tài khoản phải được tối ưu hoá cho các tài khoản tại miền đó. Để tối ưu hoá cho các tài khoản tổ chức Google Cloud nói chung thay vì chỉ một miền tổ chức Google Cloud, hãy đặt giá trị là dấu hoa thị (*): hd=*.

Đừng dựa vào tính năng tối ưu hoá giao diện người dùng này để kiểm soát những người có thể truy cập vào ứng dụng của bạn, vì các yêu cầu phía máy khách có thể bị sửa đổi. Hãy nhớ xác thực rằng mã thông báo nhận dạng được trả về có giá trị xác nhận hd khớp với giá trị mà bạn mong đợi (ví dụ: mycolledge.edu). Không giống như tham số yêu cầu, thông báo xác nhận hd của mã thông báo nhận dạng nằm trong mã bảo mật của Google, vì vậy, bạn có thể tin tưởng giá trị này.

include_granted_scopes (Không bắt buộc) Nếu thông số này được cung cấp với giá trị true và yêu cầu uỷ quyền được cấp, thì uỷ quyền sẽ bao gồm mọi uỷ quyền trước đó được cấp cho tổ hợp người dùng/ứng dụng này cho các phạm vi khác; hãy xem phần Uỷ quyền gia tăng.

Xin lưu ý rằng bạn không thể thực hiện việc uỷ quyền gia tăng bằng quy trình Ứng dụng đã cài đặt.

login_hint (Không bắt buộc) Khi biết người dùng nào mà ứng dụng đang cố xác thực, ứng dụng có thể cung cấp tham số này làm gợi ý cho máy chủ xác thực. Việc truyền gợi ý này sẽ ngăn trình chọn tài khoản và điền sẵn hộp email trên biểu mẫu đăng nhập hoặc chọn phiên thích hợp (nếu người dùng đang sử dụng tính năng đăng nhập nhiều lần). Điều này có thể giúp bạn tránh các sự cố xảy ra nếu ứng dụng đăng nhập vào sai tài khoản người dùng. Giá trị này có thể là địa chỉ email hoặc chuỗi sub, tương đương với mã nhận dạng Google của người dùng.
prompt (Không bắt buộc) Danh sách các giá trị chuỗi được phân tách bằng dấu cách, chỉ định xem máy chủ uỷ quyền có nhắc người dùng xác thực lại và đồng ý hay không. Bạn có thể sử dụng các giá trị sau:
  • none

    Máy chủ uỷ quyền không hiển thị màn hình xác thực hoặc màn hình đồng ý của người dùng; máy chủ này sẽ trả về lỗi nếu người dùng chưa được xác thực và chưa định cấu hình trước sự đồng ý cho các phạm vi được yêu cầu. Bạn có thể sử dụng none để kiểm tra trạng thái xác thực và/hoặc sự đồng ý hiện có.

  • consent

    Máy chủ uỷ quyền sẽ nhắc người dùng đồng ý trước khi trả về thông tin cho ứng dụng.

  • select_account

    Máy chủ uỷ quyền nhắc người dùng chọn một tài khoản người dùng. Điều này cho phép người dùng có nhiều tài khoản tại máy chủ uỷ quyền chọn trong số nhiều tài khoản mà họ có thể có phiên hiện tại.

Nếu không có giá trị nào được chỉ định và người dùng chưa từng cho phép truy cập, thì người dùng sẽ thấy một màn hình yêu cầu đồng ý.

Xác thực mã thông báo nhận dạng

Bạn cần xác thực tất cả mã thông báo nhận dạng trên máy chủ của mình, trừ phi bạn biết rằng các mã đó đến trực tiếp từ Google. Ví dụ: máy chủ của bạn phải xác minh tính xác thực của mọi mã thông báo nhận dạng mà máy chủ nhận được từ ứng dụng khách.

Sau đây là những trường hợp phổ biến mà bạn có thể gửi mã thông báo nhận dạng đến máy chủ:

  • Gửi mã thông báo nhận dạng kèm theo các yêu cầu cần xác thực. Mã thông báo nhận dạng cho bạn biết người dùng cụ thể đưa ra yêu cầu và ứng dụng được cấp mã thông báo nhận dạng đó.

Mã thông báo nhận dạng là thông tin nhạy cảm và có thể bị sử dụng sai mục đích nếu bị chặn. Bạn phải đảm bảo rằng các mã thông báo này được xử lý một cách an toàn bằng cách chỉ truyền các mã thông báo đó qua HTTPS và chỉ qua dữ liệu POST hoặc trong tiêu đề yêu cầu. Nếu lưu trữ mã thông báo nhận dạng trên máy chủ, bạn cũng phải lưu trữ mã thông báo đó một cách an toàn.

Một điều khiến mã thông báo nhận dạng trở nên hữu ích là bạn có thể truyền mã thông báo nhận dạng giữa các thành phần khác nhau của ứng dụng. Các thành phần này có thể sử dụng mã thông báo nhận dạng làm cơ chế xác thực nhẹ để xác thực ứng dụng và người dùng. Tuy nhiên, trước khi có thể sử dụng thông tin trong mã thông báo nhận dạng hoặc dựa vào thông tin đó làm câu nhận định rằng người dùng đã xác thực, bạn phải xác thực thông tin đó.

Quy trình xác thực mã thông báo nhận dạng cần thực hiện một số bước:

  1. Xác minh rằng mã thông báo nhận dạng được bên phát hành ký đúng cách. Mã thông báo do Google phát hành được ký bằng một trong các chứng chỉ có tại URI được chỉ định trong giá trị siêu dữ liệu jwks_uri của tài liệu Khám phá.
  2. Xác minh rằng giá trị của thông báo xác nhận quyền iss trong mã thông báo nhận dạng bằng https://accounts.google.com hoặc accounts.google.com.
  3. Xác minh rằng giá trị của thông báo xác nhận quyền aud trong mã thông báo nhận dạng bằng với mã ứng dụng khách của ứng dụng.
  4. Xác minh rằng thời gian hết hạn (yêu cầu exp) của mã thông báo nhận dạng chưa qua.
  5. Nếu bạn đã chỉ định giá trị tham số hd trong yêu cầu, hãy xác minh rằng mã thông báo nhận dạng có thông báo xác nhận quyền hd khớp với một miền được chấp nhận liên kết với một tổ chức Google Cloud.

Các bước từ 2 đến 5 chỉ liên quan đến việc so sánh chuỗi và ngày khá đơn giản, vì vậy chúng ta sẽ không trình bày chi tiết các bước này tại đây.

Bước đầu tiên phức tạp hơn và liên quan đến việc kiểm tra chữ ký mã hoá. Đối với mục đích gỡ lỗi, bạn có thể sử dụng điểm cuối tokeninfo của Google để so sánh với quá trình xử lý cục bộ được triển khai trên máy chủ hoặc thiết bị của bạn. Giả sử giá trị của mã thông báo nhận dạng là XYZ123. Sau đó, bạn sẽ huỷ tham chiếu URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Nếu chữ ký mã thông báo hợp lệ, thì phản hồi sẽ là tải trọng JWT ở dạng đối tượng JSON đã giải mã.

Điểm cuối tokeninfo rất hữu ích cho việc gỡ lỗi, nhưng đối với mục đích phát hành công khai, hãy truy xuất khoá công khai của Google từ điểm cuối khoá và xác thực cục bộ. Bạn nên truy xuất URI khoá từ tài liệu Khám phá bằng giá trị siêu dữ liệu jwks_uri. Các yêu cầu đến điểm cuối gỡ lỗi có thể bị điều tiết hoặc gặp lỗi không liên tục.

Vì Google chỉ thay đổi các khoá công khai của mình không thường xuyên, nên bạn có thể lưu các khoá đó vào bộ nhớ đệm bằng cách sử dụng lệnh bộ nhớ đệm của phản hồi HTTP và trong hầu hết các trường hợp, bạn có thể xác thực cục bộ hiệu quả hơn nhiều so với việc sử dụng điểm cuối tokeninfo. Quy trình xác thực này yêu cầu truy xuất và phân tích cú pháp chứng chỉ, đồng thời thực hiện các lệnh gọi mã hoá thích hợp để kiểm tra chữ ký. May mắn là có các thư viện được gỡ lỗi kỹ bằng nhiều ngôn ngữ để thực hiện việc này (xem jwt.io).

Thu thập thông tin hồ sơ người dùng

Để lấy thêm thông tin hồ sơ về người dùng, bạn có thể sử dụng mã thông báo truy cập (mà ứng dụng của bạn nhận được trong luồng xác thực) và tiêu chuẩn OpenID Connect:

  1. Để tuân thủ OpenID, bạn phải thêm các giá trị phạm vi openid profile vào yêu cầu xác thực.

    Nếu muốn thêm địa chỉ email của người dùng, bạn có thể chỉ định một giá trị phạm vi bổ sung là email. Để chỉ định cả profileemail, bạn có thể đưa tham số sau vào URI yêu cầu xác thực:

    scope=openid%20profile%20email
  2. Thêm mã truy cập vào tiêu đề uỷ quyền và tạo yêu cầu GET HTTPS đến điểm cuối userinfo. Bạn nên truy xuất điểm cuối này từ tài liệu Khám phá bằng cách sử dụng giá trị siêu dữ liệu userinfo_endpoint. Phản hồi userinfo bao gồm thông tin về người dùng, như mô tả trong OpenID Connect Standard Claims và giá trị siêu dữ liệu claims_supported của tài liệu Khám phá. Người dùng hoặc tổ chức của họ có thể chọn cung cấp hoặc giữ lại một số trường nhất định, vì vậy, bạn có thể không nhận được thông tin cho mọi trường trong phạm vi truy cập được uỷ quyền.

Tài liệu về tính năng Khám phá

Giao thức OpenID Connect yêu cầu sử dụng nhiều điểm cuối để xác thực người dùng và để yêu cầu tài nguyên, bao gồm mã thông báo, thông tin người dùng và khoá công khai.

Để đơn giản hoá việc triển khai và tăng tính linh hoạt, OpenID Connect cho phép sử dụng "Tài liệu khám phá", một tài liệu JSON được tìm thấy ở một vị trí nổi tiếng chứa các cặp khoá-giá trị cung cấp thông tin chi tiết về cấu hình của nhà cung cấp OpenID Connect, bao gồm cả URI của điểm cuối uỷ quyền, mã thông báo, thu hồi, thông tin người dùng và khoá công khai. Bạn có thể truy xuất tài liệu Khám phá cho dịch vụ OpenID Connect của Google từ:

https://accounts.google.com/.well-known/openid-configuration

Để sử dụng các dịch vụ OpenID Connect của Google, bạn nên mã hoá cứng URI tài liệu Khám phá (https://accounts.google.com/.well-known/openid-configuration) vào ứng dụng của mình. Ứng dụng của bạn tìm nạp tài liệu, áp dụng các quy tắc lưu vào bộ nhớ đệm trong phản hồi, sau đó truy xuất URI điểm cuối từ tài liệu đó nếu cần. Ví dụ: để xác thực người dùng, mã của bạn sẽ truy xuất giá trị siêu dữ liệu authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth trong ví dụ bên dưới) làm URI cơ sở cho các yêu cầu xác thực được gửi đến Google.

Dưới đây là ví dụ về một tài liệu như vậy; tên trường là những tên được chỉ định trong OpenID Connect Discovery 1.0 (tham khảo tài liệu đó để biết ý nghĩa của các tên trường). Các giá trị này chỉ mang tính minh hoạ và có thể thay đổi, mặc dù chúng được sao chép từ phiên bản gần đây của tài liệu thực tế về Google Khám phá:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Bạn có thể tránh được một vòng lặp HTTP bằng cách lưu các giá trị từ tài liệu Khám phá vào bộ nhớ đệm. Các tiêu đề lưu vào bộ nhớ đệm HTTP chuẩn được sử dụng và phải được tuân thủ.

Thư viện ứng dụng

Các thư viện ứng dụng sau đây giúp triển khai OAuth 2.0 đơn giản hơn bằng cách tích hợp với các khung phổ biến:

Tuân thủ OpenID Connect

Hệ thống xác thực OAuth 2.0 của Google hỗ trợ các tính năng bắt buộc của quy cách OpenID Connect Core. Mọi ứng dụng được thiết kế để hoạt động với OpenID Connect đều phải tương tác với dịch vụ này (ngoại trừ OpenID Request Object).