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 của OpenID Connect và được OpenID chứng nhận. Tài liệu trong phần Sử dụng OAuth 2.0 để truy cập vào các API của Google cũng áp dụng cho dịch vụ này. Nếu bạn 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 nhập người dùng, bạn phải thiết lập một dự án trong Google Cloud 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 xin phép người dùng. Bạn cũng có thể sử dụng Cloud 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 nhiệm vụ khác. Để biết thêm thông tin, hãy xem phần Trợ giúp về Google Cloud Console.
Lấy thông tin đăng nhập 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à khoá bí mật của ứ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.
Để xem mã ứng dụng khách và khoá bí mật của ứng dụng khách cho một thông tin xác thực OAuth 2.0 nhất định, hãy nhấp vào văn bản sau: Chọn thông tin xác thực. Trong cửa sổ mở ra, hãy chọn dự án và thông tin xác thực bạn muốn, sau đó nhấp vào Xem.
Hoặc xem mã ứng dụng khách và khoá bí mật của ứng dụng khách trên trang Ứng dụng khách trong Cloud Console:
- Chuyển đến trang Ứng dụng.
- Nhấp vào tên khách hàng hoặc biểu tượng chỉnh sửa (create). Mã ứng dụng khách và mật khẩu ứng dụng khách của bạn nằm ở đầu trang.
Đặt URI chuyển hướng
URI chuyển hướng mà bạn đặt trong Cloud 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.
Để tạo, xem hoặc chỉnh sửa URI chuyển hướng cho một thông tin xác thực OAuth 2.0 nhất định, hãy làm như sau:
- Chuyển đến trang Ứng dụng.
- Nhấp vào khách hàng.
- Xem hoặc chỉnh sửa URI chuyển hướng.
Nếu không có ứng dụng nào được liệt kê trên trang Ứng dụng, thì dự án của bạn không có thông tin xác thực OAuth. Để tạo một khách hàng, hãy nhấp vào Tạo khách hàng.
Tuỳ chỉnh màn hình xin phép 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 xin phép mô tả thông tin mà người dùng đang cung cấp 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 cơ bản
về tài khoả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ể 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 xin phép người dùng cũng trình bà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 trang chủ. Bạn kiểm soát thông tin thương hiệu trong Cloud Console.
Cách bật màn hình xin phép cho dự án:
- Mở trang Thương hiệu trong Google Cloud Console.
- Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới.
- Điền thông tin vào biểu mẫu và nhấp vào mục Lưu.
Hộp thoại đồng ý sau đây cho thấy những gì người dùng sẽ thấy khi có sự kết hợp giữa OAuth 2.0 và phạm vi Google Drive trong yêu cầu. (Hộp thoại chung này được tạo bằng Google OAuth 2.0 Playground, nên không bao gồm thông tin thương hiệu sẽ được đặt trong Cloud Console.)
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ó quyền 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 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. Tài liệu này mô tả các luồng yêu cầu HTTP làm nền tảng cho 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 bao gồm việc lấy mã thông báo giá trị nhận dạng và xác thực mã đó. Mã thông báo giá trị nhận dạng là một tính năng được chuẩn hoá của OpenID Connect, được thiết kế để dùng trong việc chia sẻ các câu nhận định về danh tính trên Internet.
Các phương pháp thường dùng nhất để xác thực người dùng và lấy mã thông báo giá trị nhận dạng được gọi là quy trình "máy chủ" và quy trình "ngầm định". Quy trình 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 cấp quyền trực tiếp đượ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ì sử dụng máy chủ phụ trợ.
Tài liệu này mô tả cách thực hiện quy trình phía máy chủ để xác thực người dùng. Luồng cấp quyền trực tiếp phức tạp hơn đáng kể do 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 cấp quyền trực tiếp, bạn nên sử dụng Dịch vụ nhận dạng của Google.
Quy trình phía máy chủ
Hãy nhớ thiết lập ứng dụng của bạn trong Cloud 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 tìm cách đăng nhập bằng Google, bạn cần:
- Tạo mã thông báo trạng thái chống giả mạo
- Gửi yêu cầu xác thực đến Google
- Xác nhận mã thông báo trạng thái chống giả mạo
- Đổi
codelấy mã truy cập và mã nhận dạng - Lấy thông tin người dùng từ mã thông báo giá trị nhận dạng
- 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ệ 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ã phiên riêng biệt để lưu giữ trạng thái giữa ứng dụng của bạn và ứng dụng khách của người dùng. Sau đó, bạn so khớp mã phiên riêng biệt này với phản hồi xác thực do dịch vụ Đăng nhập bằng Google OAuth trả về để xác minh rằng người dùng đang đưa ra yêu cầu chứ không phải 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à hàm 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 trên phần phụ trợ của bạn.
Đoạn mã sau đây minh hoạ cách tạo mã thông báo phiên riêng biệt.
PHP
Bạn phải tải thư viện ứng dụng API của Google cho PHP để 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 Google API dành cho Java để 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 có các tham số URI thích hợp.
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 cách sử dụng giá trị siêu dữ liệu authorization_endpoint. Nội dung 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_idmà bạn lấy được từ trang Ứng dụng khách của Cloud Console.response_type, trong yêu cầu quy trình sử dụng mã uỷ quyền cơ bản, giá trị này phải làcode. (Đọc thêm tạiresponse_type.)scope, trong một yêu cầu cơ bản phải làopenid email. (Đọc thêm tạiscope.)redirect_uriphải là điểm cuối HTTP trên máy chủ của bạn, nơi sẽ 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 trang Thông tin xác thực của Cloud Console. Nếu giá trị này không khớp với một URI được uỷ quyền, thì yêu cầu sẽ không thành công và trả về lỗiredirect_uri_mismatch.statephả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 bối cảnh khi người dùng quay lại ứng dụng của bạn, ví dụ: URL bắt đầu. (Đọc thêm tạistate.)noncelà một giá trị ngẫu nhiên do ứng dụng của bạn tạo ra, giúp bảo vệ chống lại các cuộc tấn công lặp lại khi có mặt.login_hintcó thể là địa chỉ email của người dùng hoặc chuỗisub, 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ấplogin_hintvà người dùng đã đăng nhập, thì màn hình xin phép sẽ bao gồm yêu cầu phê duyệt để cung cấp địa chỉ email của người dùng cho ứng dụng của bạn. (Đọc thêm tạilogin_hint.)- Sử dụng tham số
hdđể tối ưu hoá quy trình OpenID 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 Workspace hoặc Cloud (đọc thêm tạihd).
Dưới đâ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//developers.google.com/oauthplayground& 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:
https://developers.google.com/oauthplayground?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
Theo RFC 6749, ứng dụng khách PHẢI bỏ qua các tham số phản hồi không nhận dạng được. 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ã phiên mà bạn đã tạo ở Bước 1. Quy trình xác minh khứ hồi này giúp xác minh rằng người dùng, chứ không phải tập lệnh độc hại, đang đưa ra yêu cầu.
Đoạn 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 để 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 Google API dành cho Java để 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. Đổi code lấy mã truy cập và mã 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 một yêu cầu HTTPS POST. Yêu cầu POST được gửi đến điểm cuối mã thông báo. Bạn nên truy xuất điểm cuối này từ Tài liệu khám phá bằng giá trị siêu dữ liệu token_endpoint. Nội dung 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 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 khách mà bạn nhận được từ trang Ứng dụng khách của Cloud Console, như mô tả trong phần Nhận thông tin xác thực OAuth 2.0. |
client_secret |
Khoá bí mật của ứng dụng khách mà bạn nhận được từ trang Ứng dụng khách của Cloud Console, 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
Trang ứng dụng của Cloud Console, 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 thông số kỹ thuật của 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//developers.google.com/oauthplayground& 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 tồn tại 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 được Google ký điện tử. |
scope |
Phạm vi truy cập được cấp bởi access_token được biểu thị dưới dạng danh sách các chuỗi phân biệt chữ hoa chữ thường, được phân tách bằng dấu cách. |
token_type |
Xác định loại mã thông báo được trả về. Hiện tại, trường này luôn có giá trị là Bearer.
|
refresh_token |
(không bắt buộc)
Trường này chỉ xuất hiện nếu tham số |
5. Lấy thông tin người dùng từ mã thông báo giá trị nhận dạng
Mã thông báo giá trị nhận dạng là một 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 mật mã. Thông thường, bạn cần phải xác thực mã thông báo giá trị 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 kênh HTTPS không có trung gian và sử dụng khoá bí mật của ứng dụng khách để xác thực với Google, nên bạn có thể tin tưởng 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 chuyển mã thông báo giá trị 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 đều 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 bên 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 tin xác nhận quyền sở hữu trong mã thông báo giá trị nhận dạng.
Trọng tải của mã thông báo nhận dạng
Mã thông báo giá trị 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ị. Dưới đâ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 (gọi là 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 nhận dạng này nhắ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 (số nguyên giây). |
iat |
mọi lúc | Thời điểm mã thông báo giá trị 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 phản hồi. Luôn
https://accounts.google.com hoặc accounts.google.com cho mã thông báo
mã nhận dạng của Google. |
sub |
mọi lúc | Giá trị nhận dạng cho người dùng, là giá trị duy nhất trong số 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 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 riêng biệ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. |
amr |
Một mảng chuỗi JSON xác định các phương pháp xác thực dùng để đăng nhập vào
Tài khoản Google. Nếu có, hãy thêm một hoặc nhiều giá trị có thể có sau đây của
[IANA.AMR]:
amr có trong
yêu cầu xác thực và được bật trong
phần cài đặt.
|
|
auth_time |
Thời điểm diễn ra quá trình xác thực người dùng, một số JSON biểu thị số giây đã trôi qua kể từ thời gian Unix (00:00:00 ngày 1 tháng 1 năm 1970 theo giờ UTC). Được cung cấp khi thông báo xác nhận quyền sở hữu auth_time có trong yêu cầu xác thực và được bật trong phần cài đặt.
|
|
at_hash |
Hàm băm mã truy cập. Xác thực rằng mã truy cập được liên kết với mã thông báo nhận dạng. Nếu mã thông báo giá trị nhận dạng được cấp kèm theo giá trị access_token trong quy trình phía máy chủ, thì thông báo xác nhận quyền sở hữu này luôn được đưa vào. Xác nhận quyền sở hữu này có thể được dùng làm cơ chế thay thế để bảo vệ 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, nhưng nếu bạn làm theo Bước 1 và Bước 3 thì không cần xác minh mã truy cập. |
|
azp |
client_id của người trình bày được uỷ quyền. Xác nhận quyền sở hữu này chỉ cần thiết khi bên yêu cầu mã thông báo nhận dạng không giống với đố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 của mình. Giá trị của thông tin xác nhận quyền sở hữu này có thể không phải là duy nhất đối với 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 hồ sơ 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 Google Workspace hoặc tổ chức trên Google Cloud; 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 |
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 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 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 trên Google Cloud. Bạn phải kiểm tra thông tin xác nhận quyền sở hữu này khi hạn chế quyền truy cập vào một tài nguyên chỉ cho thành viên của một số miền nhất định. Nếu không có thông báo này, tức là tài khoản không thuộc 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 |
Tên đầy đủ của người dùng, ở dạng có thể hiển thị. Có thể được cung cấp khi:
Khi có thông tin xác nhận quyền sở hữu |
|
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 ngăn chặn các cuộc tấn công phát lại bằng cách chỉ hiển thị giá trị này một lần. |
|
picture |
URL ảnh hồ sơ của người dùng. Có thể được cung cấp khi:
Khi có thông tin xác nhận quyền sở hữu |
|
profile |
URL của trang hồ sơ của người dùng. Có thể được cung cấp khi:
Khi có thông tin xác nhận quyền sở hữu |
6. Xác thực người dùng
Sau khi lấy được thông tin người dùng từ mã thông báo giá trị 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 tất cả yêu cầu đăng nhập đều được đáp ứng theo 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, 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 bạn nhận được từ Google hoặc ít nhất là bạn 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 giá trị nhận dạng, bạn có thể lấy 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ững 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 lợi ích 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 cấp quyền sử dụng các API khác của Google thay mặt cho người dùng (chẳng hạn như YouTube, Google Drive, Lịch hoặc Danh bạ) cùng lúc với khi bạn 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 cho 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 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 xin phép. Mã truy cập mà bạn nhận được từ Google sẽ cho phép ứng dụng của 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ã làm mới
Trong yêu cầu 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 giúp ứng dụng của bạn
liên tục truy cập 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 đặt tham số access_type thành 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ã làm mới một cách an toàn và vĩnh viễn, vì bạn chỉ có thể lấy mã 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ã làm mới được cấp: một giới hạn cho mỗi tổ hợp ứng dụng khách/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 khách. 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ể đạt đến các giới hạn này. Trong trường hợp đó, các mã làm mới cũ hơn 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ã truy cập (Xem không cần mạng).
Yêu cầu người dùng đồng ý lại
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 tham số prompt thành consent trong yêu cầu xác thực. Khi bạn thêm prompt=consent, màn hình xin phép sẽ xuất hiện mỗi khi ứng dụng của bạn yêu cầu uỷ quyền cho các phạm vi truy cập, ngay cả khi tất cả các phạm vi đã được cấp trước đó cho dự án API Google của bạn. Vì lý do này, chỉ thêm prompt=consent khi cần thiết.
Để biết thêm thông tin về tham số prompt, hãy xem prompt trong bảng Tham 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ố được API xác thực OAuth 2.0 của Google chấp nhận.
| Tham 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ừ trang Ứng dụng khách của Cloud Console, 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 bảo vệ chống phát lại. | ||||||
response_type |
(Bắt buộc) | Nếu giá trị là code, thì sẽ khởi chạy Quy trình sử dụ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, thì sẽ khởi chạy một
Luồng cấp quyền trực tiếp,
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 của URI. |
||||||
redirect_uri |
(Bắt buộc) | Xác định nơi gửi phản hồi. Giá trị của tham 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 trang Ứng dụng của Cloud Console (bao gồm cả giao thức HTTP hoặc HTTPS, chữ hoa/chữ thường và dấu gạch chéo "/" ở cuối, nếu có). | ||||||
scope |
(Bắt buộc) | Tham số phạm vi phải bắt đầu bằng giá trị Nếu có giá trị phạm vi Nếu có giá trị phạm vi 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 có quyền truy cập vào từng tệp trong Google Drive của người dùng, thì tham số phạm vi của bạn có thể là Để biết thông tin về các phạm vi hiện có, hãy xem phần 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 khứ hồi 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
|
||||||
access_type |
(Không bắt buộc) | Các giá trị được phép là offline và online. Hiệu ứng này được ghi lại trong phần Xem không cần mạng; nếu mã truy cập đang được yêu cầu, ứng dụng sẽ không nhận được mã làm mới trừ phi giá trị offline được chỉ định. |
||||||
claims |
(Không bắt buộc) |
Tham số xác nhận quyền sở hữu được dùng để chỉ định một hoặc nhiều trường không bắt buộc cần đưa vào
điểm cuối userinfo hoặc các loại phản hồi mã thông báo nhận dạng yêu cầu xác thực. Giá trị là một đối tượng JSON chứa loại phản hồi và thông tin xác nhận quyền sở hữu được yêu cầu. Máy chủ của Google chấp nhận các yêu cầu xác nhận quyền sở hữu sau:
|
||||||
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à được máy chủ của Google chấp nhận, nhưng không ảnh hưởng đến hành vi của luồng giao thức: 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 thuộc sở hữu của một tổ chức trên Google Cloud. Bằng cách
thê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 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 trên Google Cloud nói chung thay vì chỉ một miền tổ chức trên Google Cloud, hãy đặt giá trị là dấu hoa thị ( Đừ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ể được sửa đổi. Hãy nhớ xác thực rằng mã thông báo giá trị nhận dạng được trả về có giá trị xác nhận quyền sở hữu |
||||||
include_granted_scopes |
(Không bắt buộc) | Nếu tham số này được cung cấp cùng 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 hoạt động 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 uỷ quyền gia tăng bằng quy trình Ứng dụng cần cài đặt. |
||||||
login_hint |
(Không bắt buộc) | Khi biết người dùng mà ứng dụng đang cố gắng xác thực, ứng dụng có thể cung cấp tham số này dưới dạng gợi ý cho máy chủ xác thực. Việc truyền gợi ý này sẽ loại bỏ Trình chọn tài khoản và tự động điền trước 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 tài khoản), nhờ đó giúp bạn tránh được các vấn đề xảy ra nếu ứng dụng đăng nhập nhầm tài khoản người dùng.
Giá trị 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:
Nếu bạn không chỉ định giá trị và người dùng chưa cho phép truy cập trước đó, thì người dùng sẽ thấy màn hình xin phép. |
||||||
hl |
(Không bắt buộc) | Thẻ ngôn ngữ BCP 47 dùng để chỉ định ngôn ngữ hiển thị cho màn hình đăng nhập, màn hình chọn tài khoản và màn hình xin phép. Nếu bạn không cung cấp tham số này, thì ngôn ngữ sẽ được đặt mặc định theo Tài khoản Google hoặc chế độ cài đặt trình duyệt của người dùng. Ví dụ: để yêu cầu giao diện người dùng bằng tiếng Anh (Anh), hãy đặt tham số thành en-GB.
|
||||||
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 giá trị nhận dạng trên máy chủ của mình, trừ phi bạn biết rằng các mã thông báo đó đế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 giá trị nhận dạng mà máy chủ nhận được từ các ứ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 giá trị nhận dạng đến máy chủ của mình:
- Gửi mã thông báo giá trị nhận dạng cùng với các yêu cầu cần được xác thực. Mã thông báo giá trị nhận dạng cho bạn biết người dùng cụ thể đưa ra yêu cầu và mã thông báo giá trị nhận dạng đó được cấp cho ứng dụng nào.
Mã thông báo giá trị 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 chúng qua HTTPS và chỉ sử dụng 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 giá trị nhận dạng trên máy chủ, bạn cũng phải lưu trữ chúng một cách an toàn.
Một điều khiến mã thông báo giá trị nhận dạng trở nên hữu ích là bạn có thể truyền mã thông báo đó qua nhiều thành phần của ứng dụng. Các thành phần này có thể sử dụng mã thông báo giá trị nhận dạng làm 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 có thể sử dụng thông tin trong mã thông báo giá trị 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 đó.
Quá trình xác thực mã thông báo giá trị nhận dạng cần có một số bước:
- Xác minh rằng mã thông báo nhận dạng được người 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ỉ tìm thấy tại URI được chỉ định trong giá trị siêu dữ liệu
jwks_uricủa Tài liệu khám phá. - Xác minh rằng giá trị của thông báo xác nhận quyền sở hữu
isstrong mã thông báo giá trị nhận dạng bằnghttps://accounts.google.comhoặcaccounts.google.com. - Xác minh rằng giá trị của thông báo xác nhận quyền sở hữu
audtrong mã thông báo giá trị nhận dạng bằng với mã ứng dụng khách của ứng dụng. - Xác minh rằng thời gian hết hạn (Xác nhận quyền sở hữu
exp) của mã thông báo nhận dạng chưa qua. - 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 giá trị nhận dạng có thông báo xác nhận quyền sở hữu
hdkhớp với miền được chấp nhận liên kết với một tổ chức trên 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 nên chúng tôi sẽ không trình bày chi tiết ở đâ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á. Để 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ị mã thông báo 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 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 để phục vụ 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à thực hiện 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 đến điểm cuối gỡ lỗi có thể bị điều tiết hoặc có thể gặp lỗi gián đoạn.
Vì Google hiếm khi thay đổi khoá công khai, nên bạn có thể lưu khoá vào bộ nhớ đệm bằng cách sử dụng các lệnh lưu vào bộ nhớ đệm của phản hồi HTTP và trong phần lớn trường hợp, hãy thực hiện quy trình 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. Quá 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ật mã thích hợp để kiểm tra chữ ký. May mắn là có các thư viện đã được gỡ lỗi kỹ lưỡng bằng nhiều ngôn ngữ để thực hiện việc này (xem jwt.io).
Lấy 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ã truy cập (mà ứ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:
Để tuân thủ OpenID, bạn phải thêm các giá trị phạm vi
openid profilevà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ảprofilevàemail, bạn có thể thêm tham số sau vào URI yêu cầu xác thực:scope=openid%20profile%20email
- Thêm mã truy cập vào tiêu đề uỷ quyền và gửi yêu cầu HTTPS
GETđế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 giá trị siêu dữ liệuuserinfo_endpoint. Phản hồi userinfo bao gồm thông tin về người dùng, như mô tả trongOpenID Connect Standard Claimsvà giá trị siêu dữ liệuclaims_supportedcủ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 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 cả 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 tại một vị trí phổ biến 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 các đ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 dịch vụ OpenID Connect của Google, bạn nên cố định giá trị URI của tài liệu Khám phá (https://accounts.google.com/.well-known/openid-configuration) trong ứ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 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.
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 các trường). Các giá trị này hoàn toàn mang tính minh hoạ và có thể thay đổi, mặc dù chúng được sao chép từ một phiên bản gần đây của tài liệu Google Discovery 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 một lượt khứ hồi 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 tiêu chuẩn được sử dụng và cần được tuân thủ.
Thư viện ứng dụng
Các thư viện ứng dụng sau đây giúp đơn giản hoá việc triển khai OAuth 2.0 bằng cách tích hợp với các khung phổ biến:
- Thư viện ứng dụng Google API dành cho Java
- Thư viện ứng dụng API của Google cho Python
- Thư viện ứng dụng API của Google cho .NET
- Thư viện ứng dụng API của Google cho Ruby
- Thư viện ứng dụng API của Google cho PHP
- Thư viện OAuth 2.0 cho Google Web Toolkit
- Bộ điều khiển OAuth 2.0 của Google Toolbox cho Mac
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. Bất kỳ ứng dụng nào đượ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ừ Đối tượng yêu cầu OpenID).