Kết nối OpenID

API OAuth 2.0 của Google có thể được dùng 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 của chúng tôi để xác thực, tuân theo thông số kỹ thuật OpenID Connect và Được chứng nhận OpenID. Tài liệu trong phần Sử dụng OAuth 2.0 để truy cập 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 dùng Google OAuth 2.0 Playground. Để được trợ giúp về Stack Overflow, hãy gắn thẻ câu hỏi của bạn bằng "google-OAuth".

Lưu ý: Nếu muốn cung cấp nút "Đăng nhập bằng Google" cho trang web hoặc ứng dụng của mình, bạn nên sử dụng Dịch vụ nhận dạng của Google, thư viện ứng dụng đăng nhập của chúng tôi được xây dựng dựa trên giao thức OpenID Connect và cung cấp Mã thông báo nhận dạng Định dạng Connect.

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 nhập người dùng, bạn phải thiết lập một dự án trong Google API Console để có được thông tin xác thực OAuth 2.0, đặt URI chuyển hướng và tùy chỉnh (không bắt buộc) thông tin thương hiệu mà người dùng của bạn nhìn thấy trên màn hình xin phép người dùng. Bạn cũng có thể 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 bộ lọc và thực hiện các thao tác khác. Để biết thêm thông tin, hãy xem phần Trợ giúpGoogle API Console.

Nhận 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 khách và mật khẩu ứng dụng khách, để xác thực người dùng và có quyền truy cập vào các API của Google.

要查看给定OAuth 2.0凭据的客户端ID和客户端密钥，请单击以下文本： 选择凭据 。在打开的窗口中，选择您的项目和所需的凭证，然后单击“ 查看” 。

或者，从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥：

1. Go to the Credentials page.
2. 单击您的凭证名称或铅笔（ ）图标。您的客户ID和密码位于页面顶部。

Đặt URI chuyển hướng

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

Để tạo, xem hoặc chỉnh sửa các URI chuyển hướng cho thông tin xác thực OAuth 2.0, hãy làm như sau:

1. Go to the Credentials page.
2. Trong phần ID khách hàng OAuth 2.0 của trang, nhấp vào thông tin xác thực.
3. Xem hoặc chỉnh sửa các URI chuyển hướng.

Nếu không có phần ID khách OAuth 2.0 trên trang Thông tin xác thực, thì dự án của bạn không có thông tin xác thực OAuth. Để tạo một, bấm Tạo thông tin đăng nhập .

Tuỳ chỉnh màn hình xin phép người dùng

Đối với người dùng của bạn, trải nghiệm xác thực OAuth 2.0 sẽ bao gồm màn hình đồng ý mô tả thông tin mà người dùng đang phát hành và các điều khoản áp dụng. Ví dụ: khi người dùng đăng nhập, họ 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 tham 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ể dùng các 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 xin phép người dùng cũng cho thấy thông tin thương hiệu, chẳng hạn như tên sản phẩm, biểu trưng và URL của trang chủ. Bạn kiểm soát thông tin xây dựng thương hiệu trong API Console.

Để bật màn hình đồng ý của dự án của bạn:

1. Mở Consent Screen page trong Google API Console .
2. If prompted, select a project, or create a new one.
3. Điền vào biểu mẫu và nhấp vào Lưu .

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

Truy cập dịch vụ

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

Lưu ý: Do các hệ quả bảo mật của việc triển khai đúng cách, bạn nên tận dụng một thư viện hoặc dịch vụ viết sẵn. Việc xác thực người dùng một cách phù hợp là rất quan trọng đối với sự an toàn và bảo mật của họ. Do đó, bạn nên sử dụng mã được gỡ lỗi kỹ lưỡng do người khác viết. Để biết thêm thông tin, hãy xem phần Thư viện ứng dụ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 chứa bên trong các thư viện có sẵn.

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

Việc xác thực người dùng liên quan đến việc lấy một mã thông báo mã nhận dạng và xác thực mã đó. Mã nhận dạng là một tính năng tiêu chuẩn của OpenID Connect được thiết kế để chia sẻ các câu nhận định nhận dạng trên Internet.

Các phương pháp phổ biến nhất để 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 này bằng trình duyệt hoặc thiết bị di động. Quy trình ngầm ẩn được dùng khi một ứng dụng phía máy khách (thường là một ứ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 máy chủ để xác thực người dùng. Quy trình ngầm ẩn phức tạp hơn đáng kể vì có nhiều rủi ro về bảo mật trong quá trình xử lý và sử dụng mã thông báo phía máy khách. Nếu cần triển khai một quy trình 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 của bạn. Khi người dùng tìm cách đăng nhập bằng Google, bạn cần:

1. Tạo mã thông báo trạng thái 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 về trạng thái giả mạo
4. Trao đổi code để lấy mã truy cập và mã thông báo
5. Lấy thông tin người dùng từ mã thông báo mã 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 giả mạo

Bạn phải bảo vệ tính bảo mật 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 để 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 OAuth của Google trả về để xác minh rằng người dùng đang đưa ra yêu cầu và không phải là kẻ tấn công ác ý. Các mã thông báo này thường được gọi là mã thông bá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 ví dụ khác là hàm băm được tạo bằng cách ký một số biến trạng thái phiên của bạn với một khoá được giữ bí mật trong 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 Java của Google API 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 Google API cho Python để 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 HTTPS GET với các tham số URI phù hợp. Hãy lưu ý rằng bạn phải sử dụng HTTPS thay vì HTTP trong tất cả các bước của quy trình này; 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 cách sử dụng giá trị siêu dữ liệu authorization_endpoint. Cuộc thảo luận sau đây giả định 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 luồng mã uỷ quyền cơ bản phải là code. (Đọc thêm tại response_type.)
• scope, trong 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 và nhận được 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 một URI được ủy quyền, thì yêu cầu sẽ không thành công kèm theo 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 giả mạo cũng như mọi thông tin cần thiết khác để 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 bảo vệ việc phát lại khi có mặt.
• 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ã 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 đang đăng nhập, thì màn hình xin phép sẽ có 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.)
• Dùng tham số hd để tối ưu hoá quy trình Orkut Connect cho người dùng của một miền cụ thể liên kết với một tổ chức Google Cloud. (Đọc thêm tại hd.)

Lưu ý: Chỉ những thông số thường dùng nhất mới được liệt kê ở trên. Để xem danh sách đầy đủ, cùng với thông tin chi tiết khác về tất cả các thông số, hãy xem Thông số URI xác thực.

Sau đây là ví dụ về URI xác thực hoàn chỉnh của Connect Connect, với dấu ngắt dòng và khoảng trắng để 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=[e-mail]&
 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 thông tin mới về họ, hoặc nếu ứng dụng yêu cầu quyền truy cập vào tài khoản mà họ chưa phê duyệt trước đó.

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

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

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 bạn đã tạo ở Bước 1. Việc xác minh khứ hồi này giúp đảm bảo rằng người dùng (không phải tập lệnh độc hại) đang đưa ra yêu cầu.

Mã sau đây minh hoạ việc 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 Java của Google API 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 Google API cho Python để 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ã truy cập và mã nhận dạng

Phản hồi bao gồm thông số code, 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ã thông báo. Máy chủ của bạn sẽ thực hiện việc trao đổi này bằng cách gửi một 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. Cuộc 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 thông số sau trong phần thân POST:

Các trường
code	Mã uỷ quyền được trả về từ yêu cầu ban đầu.
client_id	Mã ứng dụng khách mà bạn nhận được từ API Console Credentials page, như mô tả trong bài viết Lấy thông tin xác thực OAuth 2.0.
client_secret	Mật khẩu ứng dụng khách mà bạn nhận được từ API Console Credentials page, như mô tả trong bài viết Lấy thông tin xác thực OAuth 2.0.
redirect_uri	Một URI chuyển hướng được ủy quyền cho client_id nhất định đượ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ư đã xác định trong thông số kỹ thuật 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 yêu cầu này chứa các trường sau đây trong một mảng JSON:

Các trường
access_token	Một mã thông báo có thể gửi đến API của Google.
expires_in	Thời gian tồn tạ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 mà Google đã ký số.
scope	Phạm vi truy cập mà access_token cấp được biểu thị dưới dạng danh sách các chuỗi được 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ề. Lúc 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 thông 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 bài viết Làm mới mã thông báo.

Lưu ý: Giới hạn về số lượng mã thông báo của mỗi tài khoản người dùng Google và mọi yêu cầu xác thực vượt quá giới hạn này đều có thể vô hiệu hoá mã thông báo làm mới chưa xử lý. Để biết thông tin chi tiết, hãy xem phần Mã thông báo hết hạn.

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

Mã thông báo mã nhận dạng là một JWT (Mã thông báo web JSON), là một đối tượng JSON được mã hoá bằng Base64 được mã hoá. Thông thường, bạn nên xác thực mã thông báo mã nhận dạng trước khi sử dụng. Tuy nhiên, do bạn đang giao tiếp trực tiếp với Google qua một kênh HTTPS không tính trung gian và sử dụng mã bí mật của ứng dụng để xác thực bản thân 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ự là của Google. Nếu máy chủ chuyển mã thông báo mã nhận dạng đến các thành phần khác của ứng dụng, thì 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.

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

Tải trọng của mã thông báo ID

Mã thông báo mã 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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

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

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 ID này dành cho. Đó 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 vào hoặc sau ngày mà mã thông báo mã nhận dạng không được chấp nhận. Được biểu thị theo thời gian Unix (giây số nguyên).
iat	mọi lúc	Thời gian mã thông báo ID được phát hành. Được biểu thị theo thời gian Unix (giây số nguyên).
iss	mọi lúc	Giá trị nhận dạng của nhà phát hành phản hồi. Luôn https://accounts.google.com hoặc accounts.google.com đối với mã thông báo của Google.
sub	mọi lúc	Giá trị nhận dạng người dùng, duy nhất trong tất 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 nhiều thời điểm, nhưng giá trị sub sẽ không bao giờ thay đổi. Sử dụng sub trong ứng dụng của bạn làm khoá nhận dạng duy nhất cho người dùng. Có độ dài tối đa là 255 ký tự ASCII phân biệt chữ hoa chữ thường.
at_hash		Hàm băm mã thông báo truy cập. Cung cấp thông tin xác thực rằng mã truy cập được liên kết với mã xác minh danh tính. Nếu mã thông báo mã nhận dạng được phát hành với giá trị access_token trong luồng máy chủ, thì thông báo xác nhận quyền sở hữu này luôn đi kèm. Tuyên bố này có thể được dùng làm cơ chế thay thế để chống lại các cuộc tấn công giả mạo yêu cầu trên nhiều trang web. Tuy nhiên, nếu làm theo Bước 1 và Bước 3 thì bạn không cần phải xác minh mã truy cập.
azp		client_id của người trình bày được uỷ quyền. Chỉ cần xác nhận quyền sở hữu này khi bên yêu cầu mã thông báo mã nhận dạng không giống với đối tượng của mã thông báo mã nhận dạng. Đây có thể là trường hợp của 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 nhưng dùng chung một dự án API của Google.
email		Địa chỉ email của người dùng. Giá trị này có thể không phải là duy nhất đối với người dùng này và không phù hợp để dùng làm khoá chính. Chỉ được cung cấp nếu phạm vi của bạn bao gồm giá trị phạm vi email.
email_verified		Đúng nếu địa chỉ email của người dùng đã được xác minh; nếu không thì là sai.
family_name		Họ hoặc (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		Tên hoặc (các) tên 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 liên kết với tổ chức Google Cloud của người dùng. Chỉ được cung cấp nếu người dùng thuộc tổ chức Google Cloud.
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		Tên đầy đủ 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 mã nhận dạng được trả về từ một lần làm mới mã thông báo Khi 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 hồ sơ 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 bao giờ đảm bảo sẽ có mặt.
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 trình duyệt chỉ được hiển thị một lần.
picture		URL ả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 mã nhận dạng được trả về từ một lần làm mới mã thông báo Khi 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 hồ sơ 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 bao giờ đảm bảo sẽ có mặt.
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 mã nhận dạng được trả về từ một lần làm mới mã thông báo Khi 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 hồ sơ 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 bao giờ đảm bảo sẽ có mặt.

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

Sau khi nhận được thông tin người dùng từ mã thông báo ID, 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 đó đã có trong cơ sở dữ liệu của bạn, bạn nên bắt đầu một phiên đăng ký cho người dùng đó nếu tất cả yêu cầu đăng nhập đều được phản hồi của API Google.

Nếu người dùng không tồn tại trong cơ sở dữ liệu người dùng của bạn, bạn nên chuyển hướng người dùng đến quy trình đăng ký của người dùng mới. Bạn có thể tự động đăng ký cho người dùng dựa trên thông tin bạn 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 mã nhận dạng, bạn có thể nhận thêm thông tin về 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 các nhà phát triển có yêu cầu nâng cao về việc xác thực và uỷ quyền.

Truy cập vào các API khác của Google

Một trong những ưu điểm của việc sử dụng OAuth 2.0 để xác thực là ứng dụng của bạn có thể có quyền sử dụng các API khác của Google thay mặt người dùng (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. Để làm điều này, hãy đưa vào những phạm vi khác mà bạn cần trong yêu cầu xác thực mà bạn gửi tới 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 một tham số phạm vi là openid email https://www.googleapis.com/auth/profile.agerange.read. Người dùng sẽ nhận được lời nhắc phù hợp trên màn hình yêu cầu sự đồ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.

Lưu ý: Nếu ứng dụng của bạn yêu cầu nhiều phạm vi, màn hình xin phép sẽ chứa nhiều dòng văn bản. Ứng dụng của bạn càng yêu cầu nhiều phạm vi thì người dùng càng có ít khả năng đồng ý. Vì vậy, ứng dụng của bạn chỉ nên yêu cầu xem trong phạm vi nào.

Làm mới mã thông báo

Trong yêu cầu quyền truy cập API, bạn có thể yêu cầu trả về mã làm mới trong quá trình trao đổi code. Mã 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 khi người dùng không có mặt trong ứng dụng. Để yêu cầu mã làm mới, hãy thêm thông số access_type vào offline trong yêu cầu xác thực của bạn.

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

• Hãy nhớ lưu trữ mã 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ã làm mới vào 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 khách hàng/người dùng và một giới hạn cho mỗi người dùng trên tất cả khách hàng. Nếu ứng dụng của bạn yêu cầu quá nhiều mã 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 đó, mã làm mới cũ sẽ ngừng hoạt động.

Để biết thêm thông tin, hãy xem bài viết Làm mới mã thông báo truy cập (truy cập ngoại tuyến).

Nhắc lại sự đồng ý

Bạn có thể nhắc người dùng ủy quyền lại ứng dụng 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 xin phép sẽ hiển thị mỗi khi ứng dụng của bạn yêu cầu uỷ quyền các phạm vi quyền truy cập, ngay cả khi tất cả các phạm vi đã được cấp cho dự án API của Google trước đó. Vì lý do này, chỉ bao gồm prompt=consent khi cần thiết.

Để biết thêm về thông số prompt, hãy xem phần 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 thông tin mô tả đầy đủ hơn về các thông 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ừ Credentials page API Console, như mô tả trong bài viết Lấy 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 để cho phép bảo vệ việc phát lại.
response_type	(Bắt buộc)	Nếu giá trị là code, hãy khởi chạy Luồng 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 quy trình 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 #fragment URI.
redirect_uri	(Bắt buộc)	Xác định nơi phản hồi được gửi đ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 lược đồ API Console Credentials page (bao gồm giao thức HTTP hoặc HTTPS và cuối cùng là '/', nếu có).
scope	(Bắt buộc)	Thông 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 mã nhận dạng có thể (nhưng không đảm bảo sẽ) 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, mã thông báo mã sẽ bao gồm các thông báo xác nhận quyền sở hữu email và email_verified. Ngoài các phạm vi dành riêng cho WHOIS 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ả cá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 truy cập vào mỗi tệp trên Google Drive của người dùng, thông 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 có sẵn, hãy xem phần Phạm vi OAuth 2.0 cho API Google hoặc tài liệu về API 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 cuộn xung quanh trong giao thức; nghĩa 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 cho việc tương ứng và yêu cầu. Vì redirect_uri của bạn có thể được dự đoán, nên việc sử dụng giá trị state có thể giúp đảm bảo rằng kết nối đến là kết quả của yêu cầu xác thực do ứng dụng của bạn tạo. Nếu tạo một chuỗi ngẫu nhiên hoặc mã hoá dữ liệu băm của một số trạng thái ứng dụng (ví dụ: cookie) trong biến state, bạn có thể xác thực phản hồi để đảm bảo rằng yêu cầu và phản hồi bắt nguồn từ cùng một trình duyệt. Phương thức này giúp bảo vệ 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)	Giá trị được phép là offline và online. Hiệu ứng này được ghi lại trong Quyền truy cập ngoại tuyến. Nếu bạn yêu cầu mã truy cập, ứng dụng sẽ không nhận được mã làm mới trừ phi bạn chỉ định giá trị offline.
display	(Không bắt buộc)	Một giá trị chuỗi ASCII để chỉ định cách máy chủ uỷ quyền hiển thị trang giao diện người dùng xác thực và đồng ý. Các giá trị sau đây được chỉ định và được các máy chủ của Google chấp nhận, nhưng không ảnh hưởng đến hành vi của những giá trị này: page, popup, touch và wap.
hd	(Không bắt buộc)	Đơn giản hoá quy trình đăng nhập cho các tài khoản do một tổ chức Google Cloud sở hữu. Bằng cách bao gồm 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 chọn tài khoản sẽ được tối ưu hóa 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 của tổ chức Google Cloud, hãy thiết lập giá trị của 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ể sửa đổi được. Hãy nhớ xác thực rằng mã thông báo mã nhận dạng được trả về có giá trị xác nhận quyền sở hữu hd khớp với giá trị mà bạn mong đợi (ví dụ: mycolledge.edu). Không giống như thông số yêu cầu, thông báo xác nhận quyền sở hữu mã thông báo hd chứa trong mã thông báo bảo mật của Google, vì vậy giá trị này có thể được tin cậy.
include_granted_scopes	(Không bắt buộc)	Nếu tham số này được cung cấp với giá trị true và yêu cầu uỷ quyền được cấp, thì việc uỷ quyền sẽ bao gồm mọi uỷ quyền trước đã cấp cho tổ hợp người dùng/ứng dụng này đối với các phạm vi khác; xem mục Ủy quyền gia tăng. Lưu ý rằng bạn không thể ủy quyền gia tăng bằng luồng Ứng dụng đã cài đặt.
login_hint	(Không bắt buộc)	Khi biết được người dùng đang cố xác thực, ứng dụng của bạn có thể đưa ra thông số này như một gợi ý cho máy chủ xác thực. Việc chuyể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 phù hợp (nếu người dùng đang sử dụng tính năng đăng nhập nhiều tài khoản), điều này có thể giúp bạn tránh các vấn đề xảy ra nếu ứng dụng của bạn đăng nhập vào nhầm 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 giá trị chuỗi được phân tách bằng dấu cách chỉ định liệu máy chủ uỷ quyền có nhắc người dùng xác thực lại và lấy sự đồng ý hay không. Các giá trị có thể sử dụng là: 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 xin phép người dùng; máy chủ 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 chế độ đồng ý cho các phạm vi 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 tại. consent Máy chủ uỷ quyền sẽ nhắc người dùng đồng ý trước khi trả về thông tin cho khách hàng. select_account Máy chủ uỷ quyền sẽ 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ó các phiên hiện tại. Nếu bạn không chỉ định giá trị nào và người dùng chưa từng cho phép truy cập, thì họ sẽ thấy một màn hình xin phép.

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

Bạn cần phải xác thực tất cả mã thông báo mã nhận dạng trên máy chủ của mình, trừ khi 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 rằng mọi mã thông báo mã nhận dạng xác thực mà ứng dụng đó nhận được từ ứng dụng khách của bạn.

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

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

Mã thông báo mã nhận dạng 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 đề của yêu cầu. Nếu lưu trữ mã thông báo mã nhận dạng trên máy chủ, bạn cũng phải lưu trữ các mã đó một cách an toàn.

Một điều giúp mã thông báo mã nhận dạng trở nên hữu ích là bạn có thể truyền mã thông báo đó xung quanh 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 mã nhận dạng như một cơ chế xác thực gọn nhẹ xác thực ứng dụng và người dùng. Tuy nhiên, trước khi bạn có thể sử dụng thông tin trong mã thông báo mã nhận dạng hoặc dựa vào thông tin đó để xác nhận 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 mã nhận dạng yêu cầu nhiều bước:

1. Xác minh rằng mã thông báo mã nhận dạng được nhà phát hành ký chính xác. Mã thông báo do Google cấp được ký bằng một trong các chứng chỉ 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 sở hữu iss trong mã thông báo mã nhận dạng bằng với 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 sở hữu aud trong mã thông báo mã nhận dạng bằng với mã ứng dụng khách của ứng dụng.
4. Kiểm tra để đảm bảo rằng thời gian hết hạn (thông báo xác nhận quyền sở hữu exp) chưa kết thúc.
5. Nếu bạn đã chỉ định một giá trị tham số hd trong yêu cầu, hãy xác minh rằng mã thông báo ID có hd xác nhận quyền sở hữu khớp với 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ỉ bao gồm việc so sánh chuỗi và ngày khá đơn giản. Vì vậy, chúng tôi sẽ không trình bày chi tiết những bước này tại đây.

Bước đầu tiên phức tạp hơn và phải kiểm tra chữ ký mật mã. Để 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ộ đã 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 mã nhận dạng của bạn là XYZ123. Sau đó, bạn sẽ tham chiếu URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Nếu chữ ký mã thông báo là hợp lệ, thì phản hồi sẽ là trọng tải JWT ở dạng đối tượng JSON được giải mã.

Điểm cuối tokeninfo hữu ích cho việc gỡ lỗi, nhưng để phục vụ mục đích sản xuất, hãy truy xuất các khoá công khai của Google từ điểm cuối của khoá và thực hiện việc 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 cách sử dụng giá trị siêu dữ liệu jwks_uri. Các yêu cầu gửi đến điểm cuối gỡ lỗi có thể bị điều tiết hoặc có thể bị lỗi.

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

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

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

1. Để tuân thủ tình trạng tuân thủ WHOIS, bạn phải bao gồm các giá trị phạm vi openid profile trong 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 giá trị phạm vi bổ sung là email. Để chỉ định cả profile và email, 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 của bạn vào tiêu đề ủy quyền và tạo yêu cầu GET HTTPS đến điểm cuối userinfo. Bạn sẽ 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 thông tin người dùng bao gồm thông tin về người dùng, như được 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, có thể bạn sẽ không nhận được thông tin của từng trường trong phạm vi truy cập được cho phép.

Tài liệu Khám phá

Giao thức WHOIS 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à khóa công khai.

Để đơn giản hoá việc triển khai và tăng tính linh hoạt, WHOIS Connect cho phép bạn sử dụng "Tài liệu khám phá", một tài liệu JSON được tìm thấy tại 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 dịch vụ Connect Connect, bao gồm cả các URI của mã lệnh uỷ quyền, mã thông báo, thu hồi, thông tin người dùng và khoá công khai. Tài liệu Khám phá cho dịch vụ WHOIS Connect của Google có thể được truy xuất từ:

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

Để sử dụng dịch vụ WHOIS 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 các URI điểm cuối từ tài liệu đó khi 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) dưới dạng URI cơ sở cho yêu cầu xác thực được gửi đến Google.

Sau đâ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 chúng). Các giá trị này chỉ mang tính chất minh hoạ và có thể thay đổi, mặc dù các giá trị này được sao chép từ một phiên bản gần đây của tài liệu Google Khám phá thực tế:

{
  "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 vòng khứ hồi HTTP bằng cách lưu vào bộ nhớ đệm các giá trị từ tài liệu Khám phá. Tiêu đề bộ nhớ đệm HTTP tiêu 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 giúp việc triển khai OAuth 2.0 trở nên đơn giản hơn bằng cách tích hợp với các khung phổ biến:

• Thư viện ứng dụng Java cho API của Google
• Thư viện ứng dụng Python cho API của Google
• Thư viện ứng dụng .NET cho API của Google
• Thư viện ứng dụng API của Google cho Ruby
• Thư viện ứng dụng API cho Google
• Thư viện OAuth 2.0 cho Bộ công cụ web của Google
• Hộp công cụ của Google dành cho Bộ điều khiển Mac OAuth 2.0

Tuân thủ Connect 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 thông số kỹ thuật OpenID Connect Core. Bất kỳ ứng dụng nào được thiết kế để hoạt động với ACL Connect đều phải tương tác với dịch vụ này (ngoại trừ Đối tượng yêu cầu OpenID).