Trang này mô tả việc triển khai của Google với tư cách là một nhà cung cấp OpenID Connect và cung cấp thông tin tham chiếu kỹ thuật cho các điểm cuối OIDC của Google. Quy cách OpenID Connect (OIDC) Core 1.0 xác định giao thức để xác thực người dùng và lấy thông tin nhận dạng.
Tài liệu tham khảo này không nhằm mục đích cung cấp hướng dẫn từng bước về cách triển khai OIDC; để biết thông tin chi tiết về cách triển khai, hãy xem hướng dẫn về OpenID Connect.
Tài liệu khám phá
Tài liệu khám phá chứa siêu dữ liệu về cấu hình OpenID Connect của Google như được xác định trong quy cách OpenID Connect Discovery 1.0.
URL: https://accounts.google.com/.well-known/openid-configuration
Phương thức yêu cầu được hỗ trợ: GET
Nội dung phản hồi
Các trường phản hồi được trả về trong một đối tượng JSON trong nội dung của phản hồi HTTP cho yêu cầu GET của bên yêu cầu đến https://accounts.google.com/.well-known/openid-configuration.
| Trường | Loại | Mô tả |
|---|---|---|
issuer |
string |
Giá trị nhận dạng của nhà phát hành. URL phân biệt chữ hoa chữ thường bằng cách sử dụng lược đồ https. Giá trị hiện đại là https://accounts.google.com; tuy nhiên, accounts.google.com cũng được trả về cho các cách triển khai cũ. |
authorization_endpoint |
string |
URL của Điểm cuối uỷ quyền. |
device_authorization_endpoint |
string |
URL của Điểm cuối uỷ quyền thiết bị. |
token_endpoint |
string |
URL của Điểm cuối mã thông báo. |
userinfo_endpoint |
string |
URL của Điểm cuối UserInfo. |
revocation_endpoint |
string |
URL của Điểm cuối thu hồi. |
jwks_uri |
string |
URL của tài liệu JSON Web Key Set (JWKS). |
response_types_supported |
array |
Danh sách các giá trị response_type được hỗ trợ. |
response_modes_supported |
array |
Danh sách các giá trị response_mode được hỗ trợ. |
authorization_response_iss_parameter_supported |
boolean |
Giá trị boolean cho biết có hỗ trợ RFC 9207 hay không. |
subject_types_supported |
array |
Danh sách các loại mã nhận dạng chủ thể được hỗ trợ. |
id_token_signing_alg_values_supported |
array |
Danh sách các thuật toán được hỗ trợ để ký Mã thông báo nhận dạng. |
scopes_supported |
array |
Danh sách các giá trị phạm vi được hỗ trợ. |
claims_supported |
array |
Danh sách các thông báo xác nhận quyền sở hữu được hỗ trợ. |
token_endpoint_auth_methods_supported |
array |
Danh sách các phương thức xác thực được hỗ trợ cho Điểm cuối mã thông báo. |
code_challenge_methods_supported |
array |
Danh sách các phương thức thử thách mã được hỗ trợ cho PKCE. |
grant_types_supported |
array |
Danh sách các loại cấp quyền OAuth 2.0 được hỗ trợ. |
Mã nhận dạng (Thông báo xác nhận quyền sở hữu)
Giá trị id_token được trả về trong các phản hồi là một mã thông báo web theo chuẩn JSON (JWT) đã ký mà bạn phải xác minh bằng cách sử dụng tài liệu khoá thu được từ jwks_uri trong Tài liệu khám phá. Bảng sau đây mô tả nội dung của tải trọng Mã thông báo nhận dạng đã giải mã.
| Xác nhận quyền sở hữu | Loại | Mô tả |
|---|---|---|
iss |
string |
Bắt buộc. Giá trị nhận dạng tổ chức phát hành cho Tổ chức phát hành của phản hồi. Thông thường là https://accounts.google.com; tuy nhiên, accounts.google.com cũng được trả về cho các phương thức triển khai cũ. |
sub |
string |
Bắt buộc. Giá trị nhận dạng của người dùng, là giá trị duy nhất trong tất cả Tài khoản Google và không bao giờ được 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 có phân biệt chữ hoa chữ thường. |
azp |
string |
Giá trị nhận dạng ứng dụng của người trình bày được uỷ quyền, lấy từ bảng điều khiển Google Cloud. Bạn chỉ cần khai báo này 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. |
aud |
string |
Bắt buộc. Đối tượng mà Mã thông báo nhận dạng hướng đến. Đây là Mã nhận dạng ứng dụng khách của ứng dụng, được lấy từ Bảng điều khiển Google Cloud. |
iat |
integer |
Bắt buộc. Thời gian phát hành mã nhận dạng. Được biểu thị bằng thời gian bắt đầu của hệ thống Unix (số giây nguyên). |
exp |
integer |
Bắt buộc. Thời gian hết hạn mà sau thời gian này, Mã nhận dạng không được chấp nhận. Được biểu thị bằng thời gian bắt đầu của hệ thống Unix (số giây nguyên). |
nonce |
string |
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 bảo vệ khỏi các cuộc tấn công phát lại bằng cách chỉ trình bày giá trị này một lần. |
auth_time |
integer |
Thời gian xác thực người dùng diễn ra, một số JSON biểu thị số giây đã trôi qua kể từ thời gian bắt đầu của hệ thống Unix (00:00:00 ngày 1 tháng 1 năm 1970 theo giờ UTC). Được cung cấp khi auth_time tuyên bố được đưa vào tham số yêu cầu xác thực claims. |
at_hash |
string |
Giá trị băm của mã truy cập. Xác thực rằng Mã truy cập được liên kết với mã nhận dạng. Nếu Mã thông báo nhận dạng được phát hành với giá trị access_token trong luồng máy chủ, thì yêu cầu này luôn được đưa vào. |
email |
string |
Đị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 này có thể không phải là giá trị 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 bản ghi người dùng. Bạn cũng không thể dựa vào miền của yêu cầ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 yêu cầu hd. Cảnh báo: Đừng dùng địa chỉ email làm giá trị nhận dạng vì 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. Luôn sử dụng trường sub làm giá trị nhận dạng cho người dùng. |
email_verified |
boolean |
Giá trị là true nếu địa chỉ email của người dùng đã được xác minh; nếu không thì giá trị là false. |
name |
string |
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 profile hoặc Mã nhận dạng người dùng được trả về từ một yêu cầu làm mới mã thông báo. |
picture |
string |
URL của ảnh hồ sơ người dùng. Có thể được cung cấp khi phạm vi yêu cầu bao gồm chuỗi profile hoặc mã nhận dạng mã thông báo được trả về từ một mã thông báo làm mới. |
given_name |
string |
(Các) tên hoặc(các) tên thường gọi của người dùng. Có thể được cung cấp khi có yêu cầu bồi thường name. |
family_name |
string |
Họ của người dùng. Có thể được cung cấp khi có yêu cầu bồi thường name. |
hd |
string |
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 trên Google Cloud. Bạn phải kiểm tra yêu cầu này khi chỉ cho phép thành viên của một số miền truy cập vào tài nguyên. Việc thiếu 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 tên miền được lưu trữ do Google lưu trữ. |
Điểm cuối uỷ quyền
Điểm cuối uỷ quyền được dùng để xác thực người dùng và lấy Mã uỷ quyền hoặc mã thông báo.
URL: https://accounts.google.com/o/oauth2/v2/auth
Phương thức yêu cầu được hỗ trợ: GET, POST
Tham số yêu cầu
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
client_id |
string |
Bắt buộc | Chuỗi Mã nhận dạng ứng dụng khách mà bạn lấy từ bảng điều khiển Cloud. |
nonce |
string |
Không 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ệ chống phát lại. Chỉ bắt buộc nếu bạn yêu cầu Mã nhận dạng (khi response_type bao gồm id_token). |
response_type |
string |
Bắt buộc | Xác định luồng cần sử dụng. Nếu giá trị là code, sẽ khởi chạy một quy trình sử dụng mã uỷ quyền, yêu cầu POST đối với Điểm cuối mã thông báo để lấy mã thông báo. Nếu giá trị là token, id_token, token id_token hoặc id_token token, 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ừ phân đoạn URI. Bạn không nên sử dụng token dưới bất kỳ hình thức nào vì điều này sẽ làm lộ Mã truy cập trong URL; giá trị này bị cấm trong OAuth 2.1. |
response_mode |
string |
Không bắt buộc | Chỉ định cách gửi Phản hồi uỷ quyền. Nếu response_type là code, thì giá trị mặc định là query. Đối với các loại phản hồi khác, giá trị mặc định là fragment. Các giá trị được hỗ trợ: query, fragment, form_post. |
redirect_uri |
string |
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 Google Cloud Console (bao gồm cả lược đồ HTTP hoặc HTTPS, trường hợp và dấu "/" ở cuối, nếu có). URI chuyển hướng và nguồn gốc JavaScript được ủy quyền phải tuân thủ các quy tắc xác thực được nêu trong tài liệu Xác thực URI OAuth 2.0. |
scope |
string |
Bắt buộc | Danh sách các phạm vi không theo thứ tự, được phân tách bằng dấu cách. Danh sách phải có giá trị openid, sau đó có giá trị profile, giá trị email hoặc cả hai. Bạn cũng có thể thêm các phạm vi không phải OIDC. Nếu có giá trị phạm vi profile, Mã thông báo nhận dạng có thể (nhưng không đảm bảo) bao gồm các yêu cầu mặc định profile 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 xác nhận quyền sở hữu email và email_verified. Để biết thêm thông tin, hãy xem bài viết Phạm vi OAuth 2.0. |
state |
string |
Đề xuất | Một chuỗi không rõ ràng được truyền qua lại trong giao thức; tức là chuỗi này được trả về dưới dạng một tham số URI trong quy trình sử dụng mã uỷ quyền và trong đoạn URI trong luồng cấp quyền trực tiếp. state có thể hữu ích cho việc tương quan giữa các yêu cầu và phản hồi. Vì redirect_uri của bạn có thể bị đoán, nên việc sử dụng giá trị state có thể giúp bạn yên tâm hơn rằng một 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 khởi tạo. Điều này giúp bảo vệ chống lạ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 |
string |
Không bắt buộc | Các giá trị hợp lệ là offline và online. Nếu ứng dụng của bạn cần làm mới Mã truy cập khi người dùng không có mặt tại trình duyệt, hãy sử dụng offline. Bạn phải nhập giá trị này để nhận được Mã làm mới được trả về. |
hd |
string |
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 của tổ chức trên 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 cần được tối ưu hoá cho các tài khoản thuộc 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 của tổ chức trên Google Cloud, hãy đặt giá trị là dấu hoa thị (*): hd=*. |
login_hint |
string |
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 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 xuất hiện và điền sẵn vào hộp email trên biểu mẫu đăng nhập hoặc chọn phiên phù hợp. Đ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 tài khoản người dùng không chính xác. 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 |
string |
Không bắt buộc | Một 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. Các giá trị có thể là: none (không có giao diện người dùng), consent (nhắc nhở đồng ý), select_account (nhắc nhở chọn tài khoản). |
hl |
string |
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 đồng ý. Bạn không nên sử dụng tham số này vì các chế độ cài đặt của trình duyệt và lựa chọn ưu tiên trong Tài khoản Google thường là những chỉ báo chính xác hơn về lựa chọn ưu tiên ngôn ngữ của người dùng. |
include_granted_scopes |
boolean |
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ì yêu cầu uỷ quyền sẽ bao gồm mọi yêu cầu 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. |
claims |
object |
Không bắt buộc | Tham số claims được dùng để chỉ định một hoặc nhiều trường không bắt buộc cần đưa vào Phản hồi UserInfo hoặc Mã thông báo nhận dạng. Để yêu cầu khai báo auth_time, hãy sử dụng claims={\"id_token\":{\"auth_time\":{\"essential\":true}}}. |
Tham số phản hồi
Phản hồi uỷ quyền được gửi đến URI chuyển hướng của ứng dụng (redirect_uri) bằng lệnh chuyển hướng HTTP GET. Các tham số phản hồi được nối vào URI chuyển hướng trong chuỗi truy vấn hoặc phân mảnh của URL, tuỳ thuộc vào response_type và response_mode.
| Tham số | Loại | Mô tả |
|---|---|---|
iss |
string |
Giá trị nhận dạng của tổ chức phát hành. Theo RFC 9207, tham số này luôn được trả về và đặt thành https://accounts.google.com. |
code |
string |
Mã uỷ quyền có thể được trao đổi để lấy Mã truy cập và Mã nhận dạng. |
state |
string |
Giá trị giống với tham số state trong yêu cầu. |
id_token |
string |
Mã thông báo web JSON (JWT) chứa thông tin nhận dạng về người dùng. |
access_token |
string |
Mã truy cập có thể được gửi đến một API của Google. |
token_type |
string |
Loại mã thông báo được trả về. Luôn Bearer. |
expires_in |
integer |
Thời gian tồn tại của mã truy cập tính bằng giây, so với thời gian mã thông báo được phát hành. |
scope |
string |
Phạm vi truy cập do code hoặc access_token cấp, được thể hiện 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. |
error |
string |
Mã lỗi nếu yêu cầu không thành công. |
error_description |
string |
Nội dung mô tả lỗi nếu yêu cầu không thành công. |
Phản hồi lỗi
Đối với Điểm cuối uỷ quyền, lỗi sẽ được trả về cho redirect_uri của Máy khách dưới dạng các tham số trong chuỗi truy vấn hoặc phân mảnh của URL, hoặc được hiển thị cho người dùng dưới dạng trang lỗi do Google lưu trữ.
Lỗi chuyển hướng
Các mã lỗi sau đây có thể được trả về redirect_uri của bạn:
| Lỗi | Mô tả |
|---|---|
access_denied |
Người dùng hoặc Máy chủ uỷ quyền đã từ chối yêu cầu. |
invalid_request |
Yêu cầu thiếu một tham số bắt buộc, có giá trị tham số không hợp lệ, có một tham số nhiều lần hoặc có định dạng không chính xác. |
unauthorized_client |
Ứng dụng khách không được phép yêu cầu Mã uỷ quyền bằng phương thức này. |
unsupported_response_type |
Máy chủ uỷ quyền không hỗ trợ việc lấy Mã uỷ quyền bằng phương thức này. |
invalid_scope |
Phạm vi được yêu cầu không hợp lệ, không xác định hoặc sai định dạng. |
Lỗi dành cho người dùng
Trong một số trường hợp, chẳng hạn như khi client_id hoặc redirect_uri không hợp lệ, Máy chủ uỷ quyền không thể chuyển hướng người dùng một cách an toàn trở lại ứng dụng của bạn.
Trong những trường hợp này, người dùng sẽ thấy ngay một trang lỗi.
| Lỗi | Mô tả |
|---|---|
admin_policy_enforced |
Tài khoản Google không thể uỷ quyền cho một hoặc nhiều phạm vi được yêu cầu do chính sách của quản trị viên Google Workspace. Hãy xem bài viết trợ giúp dành cho Quản trị viên Google Workspace để biết thêm thông tin về cách quản trị viên có thể hạn chế quyền truy cập cho đến khi quyền truy cập được cấp rõ ràng cho Mã nhận dạng ứng dụng OAuth của bạn. |
disallowed_useragent |
Điểm cuối uỷ quyền xuất hiện trong một tác nhân người dùng được nhúng mà Chính sách về OAuth 2.0 của Google không cho phép. |
org_internal |
Giá trị nhận dạng ứng dụng OAuth trong yêu cầu thuộc một dự án giới hạn quyền truy cập vào Tài khoản Google trong một Tổ chức Google Cloud cụ thể. |
deleted_client |
Ứng dụng OAuth đang được dùng để đưa ra yêu cầu đã bị xoá. Bạn có thể xoá theo cách thủ công hoặc tự động trong trường hợp các ứng dụng không được dùng. |
invalid_grant |
Tham số code_challenge không hợp lệ hoặc bị thiếu khi sử dụng PKCE. Khi làm mới Mã truy cập hoặc sử dụng tính năng uỷ quyền gia tăng, mã thông báo có thể đã hết hạn, không hợp lệ hoặc tài khoản người dùng có thể đã bị xoá hoặc vô hiệu hoá. |
redirect_uri_mismatch |
redirect_uri được truyền trong yêu cầu không khớp với một URI chuyển hướng được uỷ quyền cho Mã nhận dạng ứng dụng. Xem xét các URI chuyển hướng được uỷ quyền trong Bảng điều khiển Cloud. Lỗi này cũng có thể xảy ra nếu yêu cầu sử dụng quy trình OAuth ngoài băng tần (OOB) không được dùng nữa. |
invalid_client |
Nguồn gốc mà từ đó yêu cầu được đưa ra không được phép cho ứng dụng này, cấu hình ứng dụng không chính xác hoặc OAuth Client Secret không chính xác. |
origin_mismatch |
Lược đồ, miền và/hoặc cổng của JavaScript bắt nguồn từ yêu cầu uỷ quyền không khớp với URI nguồn gốc JavaScript được uỷ quyền đã đăng ký cho Mã nhận dạng ứng dụng OAuth. Xem xét các nguồn gốc JavaScript được cho phép trong bảng điều khiển Cloud. |
invalid_request |
Đã xảy ra lỗi với yêu cầu. Nguyên nhân có thể là do yêu cầu không đúng định dạng, thiếu các tham số bắt buộc hoặc sử dụng một phương thức uỷ quyền mà Google không hỗ trợ. |
Điểm cuối mã thông báo
Điểm cuối mã thông báo được dùng để trao đổi Mã uỷ quyền để lấy Mã truy cập và Mã thông báo nhận dạng.
URL: https://oauth2.googleapis.com/token
Phương thức yêu cầu được hỗ trợ: POST
Tham số yêu cầu (Cấp mã uỷ quyền)
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
code |
string |
Bắt buộc | Mã uỷ quyền nhận được từ điểm cuối uỷ quyền. |
client_id |
string |
Bắt buộc | Mã nhận dạng ứng dụng khách cho ứng dụng của bạn, lấy từ bảng điều khiển Cloud của Google. |
client_secret |
string |
Bắt buộc | Khoá bí mật của ứng dụng khách cho ứng dụng của bạn, lấy từ Bảng điều khiển Google Cloud. |
redirect_uri |
string |
Bắt buộc | URI chuyển hướng được dùng trong yêu cầu uỷ quyền ban đầu. URI chuyển hướng và nguồn gốc JavaScript được ủy quyền phải tuân thủ các quy tắc xác thực được nêu trong tài liệu Xác thực URI OAuth 2.0. |
grant_type |
string |
Bắt buộc | Phải được đặt thành authorization_code. |
Tham số yêu cầu (Luồng thiết bị)
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
client_id |
string |
Bắt buộc | Mã nhận dạng ứng dụng khách cho ứng dụng của bạn, lấy từ bảng điều khiển Cloud của Google. |
client_secret |
string |
Bắt buộc | Khoá bí mật của ứng dụng khách cho ứng dụng của bạn, lấy từ Bảng điều khiển Google Cloud. |
device_code |
string |
Bắt buộc | device_code do điểm cuối uỷ quyền thiết bị trả về. |
grant_type |
string |
Bắt buộc | Phải được đặt thành urn:ietf:params:oauth:grant-type:device_code. |
Tham số yêu cầu (Làm mới mã truy cập)
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
client_id |
string |
Bắt buộc | Mã nhận dạng ứng dụng khách cho ứng dụng của bạn, lấy từ bảng điều khiển Cloud của Google. |
client_secret |
string |
Bắt buộc | Khoá bí mật của ứng dụng khách cho ứng dụng của bạn, lấy từ Bảng điều khiển Google Cloud. |
grant_type |
string |
Bắt buộc | Phải được đặt thành refresh_token như được xác định trong quy cách Mã làm mới OpenID Connect. |
refresh_token |
string |
Bắt buộc | Mã làm mới được trả về từ quá trình trao đổi Mã uỷ quyền. |
scope |
string |
Không bắt buộc | Danh sách các phạm vi được phân tách bằng dấu cách được yêu cầu cho Mã truy cập mới. Các phạm vi được yêu cầu phải là một tập hợp con của các phạm vi được cấp trong yêu cầu uỷ quyền ban đầu. |
Nội dung phản hồi
Các trường phản hồi được trả về trong một đối tượng JSON trong nội dung của phản hồi HTTP cho yêu cầu POST của bên yêu cầu đến https://oauth2.googleapis.com/token.
| Trường | Loại | Mô tả |
|---|---|---|
access_token |
string |
Mã truy cập có thể được gửi đến một API của Google. |
expires_in |
integer |
Thời gian tồn tại của Mã truy cập tính bằng giây, so với thời gian mã thông báo được phát hành. |
id_token |
string |
Mã thông báo web JSON (JWT) chứa thông tin nhận dạng về người dùng. Mã thông báo này được trả về trong quá trình trao đổi Mã uỷ quyền ban đầu và cũng có thể được trả về trong yêu cầu Mã làm mới nếu phạm vi openid được cấp. |
scope |
string |
Phạm vi truy cập do access_token cấp 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 |
string |
Loại mã thông báo được trả về. Luôn Bearer. |
refresh_token |
string |
(Không bắt buộc) Một mã thông báo có thể dùng để lấy Mã truy cập mới. Trường này chỉ được trả về trong lần trao đổi Mã uỷ quyền ban đầu nếu access_type=offline được yêu cầu. |
refresh_token_expires_in |
integer |
(Không bắt buộc) Thời gian còn lại của Mã làm mới tính bằng giây. Giá trị này chỉ được đặt khi người dùng cấp quyền truy cập dựa trên thời gian. |
Phản hồi lỗi
Nếu yêu cầu không thành công, Máy chủ uỷ quyền sẽ trả về một đối tượng JSON có các trường sau:
| Trường | Loại | Mô tả |
|---|---|---|
error |
string |
Mã lỗi. |
error_description |
string |
Nội dung mô tả lỗi nếu yêu cầu không thành công. |
Bảng sau đây mô tả các mã lỗi tiềm ẩn và mã trạng thái HTTP liên quan:
| Lỗi | Mã trạng thái HTTP | Mô tả |
|---|---|---|
invalid_request |
400 |
Yêu cầu thiếu một tham số bắt buộc, có giá trị tham số không hợp lệ hoặc có định dạng không chính xác. |
invalid_client |
401 |
Không xác thực được máy khách. Ví dụ: client_id hoặc client_secret không hợp lệ hoặc loại ứng dụng không chính xác. |
invalid_grant |
400 |
Mã uỷ quyền, mã làm mới hoặc mã thiết bị mà bạn cung cấp không hợp lệ, đã hết hạn, bị thu hồi hoặc không khớp với URI chuyển hướng được dùng trong yêu cầu uỷ quyền. |
unauthorized_client |
400 |
Ứng dụng khách đã xác thực không được phép sử dụng Loại cấp quyền uỷ quyền này. |
unsupported_grant_type |
400 |
Authorization Server không hỗ trợ Authorization Grant Type. |
invalid_scope |
400 |
Phạm vi được yêu cầu không hợp lệ, không xác định hoặc sai định dạng. |
authorization_pending |
428 |
(Luồng thiết bị) Người dùng chưa hoàn tất luồng uỷ quyền. |
slow_down |
429 |
(Luồng thiết bị) Thiết bị đang gửi yêu cầu thăm dò quá thường xuyên. |
access_denied |
403 |
(Luồng thiết bị) Người dùng từ chối cấp quyền truy cập vào thiết bị. |
expired_token |
400 |
(Luồng thiết bị) device_code đã hết hạn. |
admin_policy_enforced |
400 |
Người dùng không thể uỷ quyền cho các phạm vi được yêu cầu do các chính sách mà quản trị viên Google Workspace của họ thực thi. |
org_internal |
403 |
Giá trị nhận dạng ứng dụng là một phần của dự án giới hạn quyền truy cập vào một Tổ chức cụ thể trên Google Cloud. |
Điểm cuối uỷ quyền cho thiết bị
Điểm cuối uỷ quyền thiết bị được dùng trong Quy trình uỷ quyền thiết bị OAuth 2.0 để lấy Mã người dùng và URL xác minh cho các thiết bị có khả năng nhập liệu hạn chế.
URL: https://oauth2.googleapis.com/device/code
Phương thức yêu cầu được hỗ trợ: POST
Tham số yêu cầu
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
client_id |
string |
Bắt buộc | Mã nhận dạng ứng dụng khách cho ứng dụng của bạn, lấy từ bảng điều khiển Cloud của Google. |
scope |
string |
Bắt buộc | Một danh sách các phạm vi được phân tách bằng dấu cách, xác định những tài nguyên mà ứng dụng của bạn có thể truy cập thay cho người dùng. |
Nội dung phản hồi
Phản hồi là một đối tượng JSON chứa các trường sau:
| Trường | Loại | Mô tả |
|---|---|---|
device_code |
string |
Giá trị mà Google chỉ định riêng biệt để xác định thiết bị chạy ứng dụng yêu cầu uỷ quyền. |
user_code |
string |
Một giá trị phân biệt chữ hoa chữ thường để xác định cho Google các phạm vi mà ứng dụng đang yêu cầu quyền truy cập. Giao diện người dùng sẽ hướng dẫn người dùng nhập giá trị này trên một thiết bị riêng biệt có nhiều khả năng nhập liệu hơn. |
verification_url |
string |
Một URL mà người dùng phải chuyển đến trên một thiết bị riêng biệt để nhập user_code và cấp hoặc từ chối quyền truy cập vào ứng dụng của bạn. |
expires_in |
integer |
Khoảng thời gian (tính bằng giây) mà device_code và user_code có hiệu lực. |
interval |
integer |
Khoảng thời gian (tính bằng giây) mà thiết bị của bạn phải đợi giữa các yêu cầu thăm dò. |
Điểm cuối thu hồi
Điểm cuối thu hồi cho phép ứng dụng của bạn thu hồi Mã truy cập hoặc Mã làm mới.
URL: https://oauth2.googleapis.com/revoke
Phương thức yêu cầu được hỗ trợ: POST
Tham số yêu cầu
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
token |
string |
Bắt buộc | Mã truy cập hoặc Mã làm mới mà bạn muốn thu hồi. |
Nội dung phản hồi
Nếu thu hồi thành công, phản hồi sẽ là một HTTP 200 OK trống. Nếu lệnh thu hồi không thành công, thì một phản hồi lỗi sẽ được trả về trong một đối tượng JSON.
| Trường | Loại | Mô tả |
|---|---|---|
error |
string |
Mã lỗi nếu yêu cầu không thành công. |
error_description |
string |
Nội dung mô tả lỗi nếu yêu cầu không thành công. |
Bảng sau đây mô tả các mã lỗi có thể xảy ra:
| Lỗi | Mô tả |
|---|---|
invalid_token |
Mã thông báo được cung cấp trong yêu cầu đã hết hạn hoặc đã bị thu hồi. |
invalid_request |
Yêu cầu thiếu một tham số bắt buộc, có giá trị tham số không hợp lệ hoặc có định dạng không chính xác. |
Điểm cuối UserInfo
Điểm cuối UserInfo trả về thông tin hồ sơ về người dùng đã xác thực.
URL: https://openidconnect.googleapis.com/v1/userinfo
Phương thức yêu cầu được hỗ trợ: GET, POST
Tiêu đề của yêu cầu
| Tiêu đề | Mô tả |
|---|---|
Authorization |
Bắt buộc. Phải được đặt thành Bearer: access_token. |
Nội dung phản hồi
Các trường phản hồi được trả về trong một đối tượng JSON trong nội dung của phản hồi HTTP cho yêu cầu GET hoặc POST của bên yêu cầu đến https://openidconnect.googleapis.com/v1/userinfo.
| Trường | Loại | Mô tả |
|---|---|---|
sub |
string |
Bắt buộc. Giá trị nhận dạng của người dùng, là giá trị duy nhất trong tất cả Tài khoản Google và không bao giờ được dùng lại. Chuỗi phân biệt chữ hoa chữ thường và không vượt quá 255 ký tự. |
name |
string |
Tên đầy đủ của người dùng, ở dạng có thể hiển thị. |
given_name |
string |
(Các) tên hoặc(các) tên thường gọi của người dùng. |
family_name |
string |
Họ của người dùng. |
picture |
string |
URL của ảnh hồ sơ người dùng. |
email |
string |
Địa chỉ email của người dùng. |
email_verified |
boolean |
Địa chỉ email của người dùng đã được xác minh hay chưa. |
hd |
string |
Tên miền được lưu trữ liên kết với tổ chức Google Workspace hoặc Cloud của người dùng. |
Điểm cuối Tokeninfo
Điểm cuối tokeninfo là một phương thức triển khai dành riêng cho Google, được dùng để xác thực mã nhận dạng cho mục đích gỡ lỗi.
URL: https://oauth2.googleapis.com/tokeninfo
Phương thức yêu cầu được hỗ trợ: GET, POST
Tham số yêu cầu
| Tham số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
id_token |
string |
Bắt buộc | Mã thông báo nhận dạng cần xác thực. |
Nội dung phản hồi
Các trường phản hồi được trả về trong một đối tượng JSON trong nội dung của phản hồi HTTP cho yêu cầu GET hoặc POST của bên yêu cầu đến https://oauth2.googleapis.com/tokeninfo.
| Trường | Loại | Mô tả |
|---|---|---|
iss |
string |
Giá trị nhận dạng của tổ chức phát hành. Luôn https://accounts.google.com. |
sub |
string |
Giá trị nhận dạng của người dùng, là giá trị duy nhất trong tất cả Tài khoản Google và không bao giờ được dùng lại. |
aud |
string |
Đối tượng mà Mã thông báo nhận dạng hướng đến. Đây là Mã nhận dạng ứng dụng khách của ứng dụng, được lấy từ Bảng điều khiển Google Cloud. |
iat |
integer |
Thời gian phát hành JWT. Được biểu thị bằng số giây kể từ 1970-01-01T0:0:0Z theo giờ UTC. |
exp |
integer |
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 để xử lý. Được biểu thị bằng số giây kể từ 1970-01-01T0:0:0Z theo giờ UTC. |
email |
string |
Địa chỉ email của người dùng. |
email_verified |
string |
Địa chỉ email của người dùng đã được xác minh hay chưa. Giá trị là một chuỗi "true" hoặc "false". |
access_type |
string |
Loại quyền truy cập được yêu cầu trong yêu cầu uỷ quyền ban đầu. |
azp |
string |
Giá trị nhận dạng ứng dụng của người trình bày được uỷ quyền, lấy từ bảng điều khiển Google Cloud. |
scope |
string |
Danh sách phạm vi được phân tách bằng dấu cách được cấp cho mã thông báo. |
alg |
string |
Thuật toán dùng để ký Mã thông báo nhận dạng. |
kid |
string |
Mã khoá dùng để ký Mã nhận dạng người dùng. |
typ |
string |
Loại mã thông báo. Luôn JWT. |