Kết nối OpenID

endpoint OpenID Connect của Google là OpenID Certified.

API OAuth 2.0 của Google có thể được sử dụng cho cả xác thực và ủy quyền. Tài liệu này mô tả OAuth của chúng tôi thực hiện 2.0 để xác thực, mà phù hợp với OpenID Connect đặc điểm kỹ thuật, và là OpenID Certified . Các tài liệu được tìm thấy trong Sử dụng OAuth 2.0 để truy cập Google API 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 một cách tương tác, chúng tôi đề nghị Google OAuth 2.0 Sân chơi . Để được trợ giúp về Stack Overflow , thẻ câu hỏi của bạn với 'google-oauth'.

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 cho người dùng đăng nhập, bạn phải thiết lập một dự án trong Google API Console để có được OAuth 2.0 thông tin, thiết lập một chuyển hướng URI, và (tùy chọn) tùy chỉnh thông tin xây dựng thương hiệu mà người dùng của bạn nhìn thấy trên màn hình sử dụng đồng ý. Bạn cũng có thể sử dụng API Console để tạo ra một tài khoản dịch vụ, cho phép thanh toán, thiết lập lọc, và làm nhiệm vụ khác. Để biết thêm chi tiết, xem Google API ConsoleTrợ giúp .

Lấy chứng chỉ OAuth 2.0

Bạn cần OAuth 2.0 thông tin, trong đó có một ID khách hàng và khách hàng bí mật, để xác thực người sử dụng và khả năng tiếp cận các API của Google.

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

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

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

Đặt một chuyển hướng URI

Chuyển hướng URI mà bạn thiết lập trong API Console xác định nơi Google gửi trả lời cho bạn yêu cầu xác thực .

Để 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 .

Tùy chỉnh màn hình người sử dụng đồng ý

Đối với người dùng của bạn, kinh nghiệm xác thực OAuth 2.0 bao gồm một màn hình đồng ý rằng mô tả các 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 vào, họ có thể được yêu cầu cung cấp quyền truy cập ứng dụng của bạn đến địa chỉ email của họ và các thông tin tài khoản cơ bản. 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 scope tham số, mà ứng dụng của bạn bao gồm trong nó 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 API của Google khác.

Màn hình sử dụng đồng ý cũng trình bày xây dựng thương hiệu thông tin như tên sản phẩm, biểu trưng và URL trang chủ. Bạn kiểm soát các 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 .

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

Sự đồng ý của ảnh chụp màn hình trang

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 để chăm sóc nhiều chi tiết thi hành chứng thực người sử dụng và tiếp cận với Google APIs. Ví dụ như Google đăng nhập và các thư viện ứng dụng khách Google , trong đó có sẵn cho một loạt các nền tảng.

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

Chứng thực người dùng

Chứng thực người sử dụng liên quan đến việc thu thập một thẻ ID và xác nhận nó. Thẻ ID là một tính năng tiêu chuẩn của OpenID Connect được thiết kế để sử dụng trong việc chia sẻ khẳng định danh tính trên Internet.

Các phương pháp thường được sử dụng nhất để xác thực người dùng và có được một ID thẻ được gọi là "máy chủ" chảy và "ngầm" dòng chảy. Dòng máy chủ cho phép máy chủ back-end của một ứng dụng để xác minh danh tính của người sử dụng trình duyệt hoặc thiết bị di động. Dòng chảy ngầm được sử dụng khi một ứng dụng client-side (thường là một ứng dụng JavaScript chạy trong trình duyệt) cần phải API truy cập trực tiếp thay vì thông qua máy chủ back-end của nó.

Tài liệu này mô tả làm thế nào để thực hiện các dòng máy chủ để xác thực người dùng. Dòng chảy ngầm được đáng kể phức tạp hơn vì rủi ro bảo mật trong việc xử lý và sử dụng thẻ trên các mặt hàng. Nếu bạn cần phải thực hiện một dòng chảy ngầm, chúng tôi khuyên bạn nên sử dụng Google Sign-In .

dòng máy chủ

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

  1. Tạo một chất chống giả mạo thẻ nhà nước
  2. Gửi yêu cầu xác thực đến Google
  3. Xác nhận chống giả mạo thẻ nhà nước
  4. Trao đổi đang cho access code và ID thẻ
  5. Lấy thông tin người dùng từ các thẻ ID
  6. Xác thực người dùng

1. Tạo một chất chống giả mạo thẻ nhà nước

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

Một lựa chọn tốt cho một mã thông báo trạng thái là một chuỗi của 30 hoặc lâu hơn nhân vật được xây dựng bằng cách sử dụng máy phát điện ngẫu nhiên số chất lượng cao. Một là một hash được tạo ra bằng cách ký một số biến trạng thái phiên của bạn với một chìa khóa đó sẽ được giữ bí mật về bạn back-end.

Ví dụ dưới đây tạo session tokens độc đáo.

PHP

Bạn phải tải về thư viện ứng dụng khách Google API 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 về thư viện ứng dụng khách Google API 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);

mãng xà

Bạn phải tải về thư viện ứng dụng khách 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 thành một HTTPS GET yêu cầu với các thông 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 quá trình này; các kết nối HTTP được từ chối. Bạn nên lấy URI gốc từ tài liệu Discovery sử dụng authorization_endpoint giá trị siêu dữ liệu. Các cuộc thảo luận sau đây giả định cơ sở URI là https://accounts.google.com/o/oauth2/v2/auth .

Đối với yêu cầu cơ bản, xác định các thông số sau:

  • client_id , mà bạn có được từ API ConsoleCredentials page.
  • response_type , mà trong một yêu cầu dòng code uỷ quyền cơ bản nên đang . (Xem chi tiết tại response_type .)
  • scope , mà trong một yêu cầu cơ bản cần được openid email . (Xem chi tiết tại scope .)
  • redirect_uri nên là HTTP endpoint trên máy chủ của bạn sẽ nhận được phản hồi từ Google. Giá trị chính xác phải phù hợp với một trong những URI chuyển hướng có thẩm quyền cho khách hàng OAuth 2.0, mà bạn đã cấu hình trong API ConsoleCredentials page. Nếu giá trị này không phù hợp với một URI có thẩm quyền, yêu cầu sẽ thất bại với một redirect_uri_mismatch lỗi.
  • state nên bao gồm giá trị của chống giả mạo phiên duy nhất thẻ, cũng như bất kỳ các thông tin khác cần thiết để khôi phục lại bối cảnh khi dùng quay trở lại để ứng dụng của bạn, ví dụ, bắt đầu từ địa chỉ URL. (Xem chi tiết tại state .)
  • nonce là một giá trị ngẫu nhiên được tạo ra bởi ứng dụng của bạn cho phép bảo vệ phát lại khi xuất hiện.
  • login_hint có thể là địa chỉ email của người dùng hoặc các sub chuỗi, tương đương với Google ID của người dùng. Nếu bạn không cung cấp một login_hint và người sử dụng hiện đang đăng nhập, màn hình có sự đồng ý bao gồm một đề nghị phê duyệt để phát hành địa chỉ email của người dùng ứng dụng của bạn. (Xem chi tiết tại login_hint .)
  • Sử dụng các hd tham số để tối ưu hóa dòng chảy OpenID Connect cho người sử dụng một tên miền cụ thể liên quan đến một tổ chức đám mây của Google. (Xem chi tiết tại hd .)

Dưới đây là một ví dụ về một hoàn OpenID Connect xác thực URI, với ngắt dòng và không gian để có thể đọc:

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

Người dùng được yêu cầu để cung cấp cho sự đồng ý nếu ứng dụng của bạn yêu cầu bất kỳ thông tin mới về họ, hoặc nếu truy cập tài khoản yêu cầu ứng dụng của bạn rằng họ đã không được chấp thuận trước đó.

3. Xác nhận chống giả mạo thẻ nhà nước

Câu trả lời sẽ được gửi đến redirect_uri mà bạn chỉ định trong yêu cầu . Tất cả các phản ứng được trả về trong chuỗi truy vấn, như hình 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 phù hợp với phiên giao dịch thẻ mà bạn đã tạo ở Bước 1 . xác minh khứ hồi này giúp đảm bảo rằng người dùng, không phải là một kịch bản độc hại, được đưa ra yêu cầu.

Ví dụ dưới đây xác nhận phiên mã thông báo mà bạn đã tạo ở bước 1:

PHP

Bạn phải tải về thư viện ứng dụng khách Google API 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 về thư viện ứng dụng khách Google API 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.");
}

mãng xà

Bạn phải tải về thư viện ứng dụng khách 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 đang cho access code và ID thẻ

Câu trả lời bao gồm một đang tham số, code ủy quyền một lần mà máy chủ của bạn có thể trao đổi cho một access token và ID thẻ. Máy chủ của bạn làm cho trao đổi này bằng cách gửi một HTTPS POST yêu cầu. Các POST yêu cầu được gửi đến thiết bị đầu cuối thẻ, mà bạn nên lấy từ tài liệu Discovery sử dụng token_endpoint giá trị siêu dữ liệu. Các 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 POST cơ thể:

Lĩnh vực
code Mã ủy quyền được trả về từ yêu cầu ban đầu .
client_id Các khách hàng ID mà bạn có được từ API ConsoleCredentials page, như mô tả trong Lấy OAuth 2.0 credentials .
client_secret Bí mật của khách hàng mà bạn có được từ API ConsoleCredentials page, như mô tả trong Lấy OAuth 2.0 credentials .
redirect_uri Một chuyển hướng có thẩm quyền URI cho trao client_id quy định tại các API ConsoleCredentials page, như mô tả trong Set một chuyển hướng URI .
grant_type Trường này phải chứa một giá trị của authorization_code , như được định nghĩa trong 2.0 đặc điểm kỹ thuật OAuth .

Yêu cầu thực tế có thể trông giố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

Một phản ứng thành công để yêu cầu này bao gồm các lĩnh vực sau đây trong một mảng JSON:

Lĩnh vực
access_token Một dấu hiệu có thể được gửi đến một API của Google.
expires_in Tuổi thọ còn lại của access token trong vài giây.
id_token Một JWT có chứa thông tin nhận dạng về người dùng đó là kỹ thuật số có chữ ký của Google.
scope Phạm vi tiếp cận do access_token thể hiện dưới dạng một danh sách các không gian được phân định, case-sensitive chuỗi.
token_type Xác định các loại thẻ trả lại. Tại thời điểm này, lĩnh vực này luôn 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 access_type tham số được thiết lập để offline trong yêu cầu xác thực . Để biết chi tiết, xem thẻ Refresh .

5. Thu thập thông tin người dùng từ các thẻ ID

ID Mã là một JWT (JSON Web Token), có nghĩa là, một mã hóa ký Base64 mã hóa đối tượng JSON. Thông thường, điều quan trọng là bạn xác nhận một ID Mã thông báo trước khi bạn sử dụng nó, nhưng kể từ khi bạn đang giao tiếp trực tiếp với Google trên một kênh HTTPS miễn trung gian và sử dụng bí mật khách hàng của bạn để xác thực bạn với Google, bạn có thể tự tin rằng token bạn nhận thực sự đến từ Google và có giá trị. Nếu máy chủ của bạn vượt qua ID Mã thông báo với các thành phần khác của ứng dụng của bạn, nó là vô cùng quan trọng mà các thành phần khác xác nhận các dấu hiệu trước khi sử dụng nó.

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

tải trọng một ID thẻ của

Một thẻ ID 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ụ, định dạng để có thể đọ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"
}

Google ID Token có thể chứa các lĩnh vực sau đây (được gọi là tuyên bố ):

Yêu cầu Cung cấp Sự miêu tả
aud luôn Khán giả rằng thẻ ID này là để dành cho. Nó phải là một trong những OAuth 2.0 ID khách hàng của ứng dụng của bạn.
exp luôn thời gian hết hạn vào ngày hoặc sau đó thẻ ID phải không được chấp nhận. Đại diện trong Unix thời gian (số nguyên giây).
iat luôn Hiện token ID được phát hành. Đại diện trong Unix thời gian (số nguyên giây).
iss luôn Các nhà phát hành định danh cho các tổ chức phát hành của các phản ứng. Luôn https://accounts.google.com hoặc accounts.google.com cho Google ID mã thông báo.
sub luôn Một định danh cho người sử dụng, duy nhất trong số tất cả các tài khoản Google và không bao giờ tái sử dụng. Một tài khoản Google có thể có nhiều địa chỉ email tại các điểm khác nhau trong thời gian, nhưng các sub giá trị không bao giờ thay đổi. Sử dụng sub bên trong ứng dụng của bạn là chìa khóa độc đáo-identifier cho người dùng. Chiều dài tối đa 255 ký tự ASCII trường hợp nhạy cảm.
at_hash Truy cập băm token. Cung cấp xác nhận rằng thẻ truy cập được gắn với các dấu hiệu nhận dạng. Nếu mã thông báo ID được cấp một access_token giá trị trong dòng chảy máy chủ, tuyên bố này luôn được bao gồm. Tuyên bố này có thể được sử dụng như một cơ chế thay thế để bảo vệ chống lại các cuộc tấn công cross-site yêu cầu giả mạo, nhưng nếu bạn làm theo Bước 1Bước 3 nó không phải là cần thiết để xác minh chứng cứ truy cập.
azp Các client_id của người dẫn chương trình được ủy quyền. Tuyên bố này chỉ cần thiết khi bên yêu cầu token ID là không giống như khán giả của thẻ ID. Đây có thể là trường hợp của Google cho các ứng dụng lai, nơi một ứng dụng web và ứng dụng Android có một khác nhau OAuth 2.0 client_id nhưng chia sẻ dự án Google API tương tự.
email địa chỉ email của người dùng. Giá trị này có thể không phải là duy nhất cho người sử dụng này và không thích hợp để sử dụng như một chìa khóa chính. Cung cấp chỉ khi phạm vi của bạn bao gồm các email giá trị phạm vi.
email_verified Đúng nếu địa chỉ e-mail của người dùng đã được xác minh; ngược lại là sai.
family_name họ của người dùng (s) hoặc tên cuối cùng (s). Có thể được cung cấp khi một name tuyên bố là hiện tại.
given_name tên của người dùng nhất định (s) hoặc tên đầu tiên (s). Có thể được cung cấp khi một name tuyên bố là hiện tại.
hd Tên miền liên quan đến việc tổ chức đám mây của Google của người dùng. Cung cấp chỉ khi người dùng thuộc về một tổ chức đám mây của Google.
locale Locale của người dùng, đại diện bởi một BCP 47 thẻ ngôn ngữ. Có thể được cung cấp khi một name tuyên bố là hiện tại.
name tên đầy đủ của người dùng, trong một hình thứ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ơ"
  • Token ID được trả về từ một refresh thẻ

Khi name tuyên bố có mặt, bạn có thể sử dụng chúng để cập nhật hồ sơ người dùng của ứng dụng. Lưu ý rằng tuyên bố này không bao giờ được đảm bảo để có mặt.

nonce Giá trị của nonce được cung cấp bởi ứng dụng của bạn trong yêu cầu xác thực. Bạn nên thực thi bảo vệ chống lại cuộc tấn công replay bằng cách đảm bảo nó được trình bày chỉ một lần.
picture URL của hình ảnh cá nhân 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ơ"
  • Token ID được trả về từ một refresh thẻ

Khi picture tuyên bố có mặt, bạn có thể sử dụng chúng để cập nhật hồ sơ người dùng của ứng dụng. Lưu ý rằng tuyên bố này không bao giờ được đảm bảo để có mặt.

profile URL của trang hồ sơ cá nhân 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ơ"
  • Token ID được trả về từ một refresh thẻ

Khi profile yêu cầu có mặt, bạn có thể sử dụng chúng để cập nhật hồ sơ người dùng của ứng dụng. Lưu ý rằng tuyên bố này không bao giờ được đảm bảo để có mặt.

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

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

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 phần đăng ký mới sử dụng của bạn. Bạn có thể tự động đăng ký người sử dụng dựa trên các thông tin mà bạn nhận được từ Google, hoặc ít nhất bạn có thể trước các rất nhiều các lĩnh vực mà bạn yêu cầu vào mẫu đăng ký của bạn. Ngoài các thông tin trong thẻ ID, bạn có thể nhận được thêm thông tin hồ sơ người dùng tại các điểm cuối lý lịch thành viên của chúng tôi.

Chủ đê nâng cao

Các phần sau đây mô tả 2.0 API Google OAuth chi tiết hơn. Thông tin này dành cho các nhà phát triển với yêu cầu cao cấp xung quanh xác thực và ủy quyền.

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

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

tokens Refresh

Trong yêu cầu của bạn để truy cập API bạn có thể yêu cầu làm mới thẻ để được trả lại trong thời gian đang trao code . Một refresh thẻ cung cấp ứng dụng của bạn truy cập liên tục đến Google API trong khi người dùng không có mặt trong ứng dụng của bạn. Để yêu cầu một mã thông báo làm mới, hãy thêm thiết lập access_type tham số offline trong bạn yêu cầu xác thực .

Lưu ý:

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

Để biết thêm thông tin, xem Refreshing một access token (truy cập ẩn) .

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

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

thông số xác thực URI

Bảng dưới đây cung cấp cho giới thiệu đầy đủ hơn về các thông số chấp nhận bởi xác thực API OAuth 2.0 của Google.

Tham số Yêu cầu Sự miêu tả
client_id (Yêu cầu) Chuỗi ID khách hàng mà bạn có được từ API ConsoleCredentials page, như mô tả trong Lấy chứng chỉ OAuth 2.0 .
nonce (Yêu cầu) Một giá trị ngẫu nhiên được tạo ra bởi ứng dụng của bạn cho phép bảo vệ phát lại.
response_type (Yêu cầu) Nếu giá trị code đang , ra mắt một đang cho phép dòng chảy cơ bản , đòi hỏi một POST đến thiết bị đầu cuối thẻ để có được thẻ. Nếu giá trị là token id_token hoặc id_token token , ra mắt một dòng chảy ngầm , đòi hỏi việc sử dụng JavaScript tại chuyển hướng URI để lấy thẻ từ URI #fragment nhận dạng .
redirect_uri (Yêu cầu) Xác định nơi mà các câu trả lời được gửi đi. Giá trị của tham số này chính xác phải phù hợp với một trong những giá trị chuyển hướng có thẩm quyền mà bạn thiết lập trong API ConsoleCredentials page (bao gồm cả HTTP hoặc HTTPS chương trình, trường hợp, và dấu '/', nếu có).
scope (Yêu cầu)

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

Nếu profile giá trị phạm vi hiện diện, ID sức token (nhưng không đảm bảo) bao gồm mặc định của người dùng profile khiếu nại.

Nếu email giá trị phạm vi hiện diện, token ID bao gồm emailemail_verified khiếu nại.

Ngoài những phạm vi OpenID cụ thể, lập luận 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 không gian tách ra. Ví dụ, nếu bạn muốn mỗi tập tin truy cập vào 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ề phạm vi có sẵn, xem OAuth 2.0 Phạm vi cho Google API hoặc các tài liệu cho các API của Google mà bạn muốn sử dụng.

state (Không bắt buộc, nhưng khuyến khích mạnh mẽ)

Một chuỗi đục được tròn vấp trong giao thức; mà là để nói, nó được trả về như một tham số URI trong dòng chảy cơ bản, và trong URI #fragment nhận dạng trong dòng chảy ngầm.

Các state có thể hữu ích cho tương ứng các yêu cầu và trả lời. Bởi vì bạn redirect_uri có thể đoán, sử dụng một state giá trị có thể làm tăng sự đảm bảo bạn rằng một kết nối đến là kết quả của một yêu cầu xác thực khởi xướng bởi ứng dụng của bạn. Nếu bạn tạo ra một chuỗi ngẫu nhiên hoặc mã hóa các hash của một số trạng thái của khách hàng (ví dụ, một cookie) trong này state thay đổi, bạn có thể xác nhận các phản ứng để bổ sung đảm bảo rằng các yêu cầu và phản ứng có nguồn gốc trong cùng một trình duyệt. Điều này cung cấp bảo vệ chống lại các cuộc tấn công như cross-site yêu cầu giả mạo.

access_type (Không bắt buộc) Các giá trị cho phép là offlineonline . Hiệu quả được ghi lại trong cập Offline ; nếu một thẻ truy cập đang được yêu cầu, khách hàng không nhận được refresh mã thông báo nếu một giá trị của offline được xác định.
display (Không bắt buộc) Một ASCII chuỗi giá trị để chỉ định cách máy chủ uỷ quyền hiển thị xác thực và sự đồng ý của các trang giao diện người dùng. Các giá trị sau được quy định, và được chấp nhận bởi các máy chủ của Google, nhưng không có bất kỳ ảnh hưởng đến hành vi của nó: page , popup , touch , và wap .
hd (Không bắt buộc)

Đơn giản hóa quá trình đăng nhập cho các tài khoản thuộc sở hữu của một tổ chức đám mây của Google. Bằng cách bao gồm các miền Google Cloud tổ chức (ví dụ, mycollege.edu ), bạn có thể chỉ ra rằng việc lựa chọn giao diện người dùng tài khoản nên được tối ưu hóa cho các tài khoản tại tên miền đó. Để tối ưu hóa cho tổ chức đám mây của Google chiếm thường thay vì chỉ một Google miền tổ chức đám mây, thiết lập một giá trị của một dấu sao ( * ): hd=* .

Đừng dựa vào tối ưu hóa 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, như yêu cầu phía máy khách có thể được sửa đổi. Hãy chắc chắn để validate rằng ID trở lại thẻhd giá trị khẳng định rằng trận đấu những gì bạn mong đợi (ví dụ mycolledge.edu ). Không giống như các tham số yêu cầu, ID thẻ hd khẳng định được chứa trong một thẻ bảo mật từ Google, vì vậy giá trị 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 cấp phép được cấp, uỷ quyền sẽ bao gồm bất kỳ uỷ quyền trước cấp cho này kết hợp sử dụng / Đơn đề nghị phạm vi khác; thấy phép cộng dồn .

Lưu ý rằng bạn không thể làm phép cộng dồn với dòng chảy App cài đặt.

login_hint (Không bắt buộc) Khi ứng dụng của bạn biết mà sử dụng nó đang cố gắng để xác thực, nó có thể cung cấp tham số này như một gợi ý để máy chủ xác thực. Đi qua gợi ý này ngăn chặn tính năng chọn tài khoản và một trong hai trước lấp đầy hộp thư điện tử trên đăng nhập hình thức, hoặc chọn phiên thích hợp (nếu người dùng là sử dụng đăng nhập nhiều ), có thể giúp bạn tránh được những vấn đề xảy ra nếu ứng dụng của bạn các bản ghi trong tài khoản người dùng sai. Giá trị có thể là một địa chỉ email hoặc sub chuỗi, tương đương với Google ID của người dùng.
prompt (Không bắt buộc) Một danh sách không gian được phân định các giá trị chuỗi chỉ định liệu máy chủ uỷ quyền nhắc nhở người sử dụng cho xác nhận lại và đồng ý. Các giá trị có thể là:
  • none

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

  • consent

    Các máy chủ uỷ quyền nhắc nhở người dùng về sự đồng ý trước khi trở về thông tin cho khách hàng.

  • select_account

    Các máy chủ uỷ quyền nhắc nhở người dùng lựa 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 để lựa chọn giữa các nhiều tài khoản mà họ có thể có phiên hiện tại cho.

Nếu không có giá trị được chỉ định và người dùng đã không trước đây có thẩm quyền truy cập, sau đó người dùng được hiển thị một màn hình có sự đồng ý.

Members một thẻ ID

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

Sau đây là các tình huống phổ biến mà bạn có thể gửi thẻ ID để máy chủ của bạn:

  • Gửi thẻ ID với yêu cầu mà cần phải được chứng thực. Các thẻ ID cho bạn biết người dùng cụ thể đưa ra yêu cầu và cho khách hàng mà ID thẻ đã được cấp.

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

Một điều mà làm cho ID mã thông báo hữu ích là thực tế mà bạn có thể vượt qua chúng thành phần xung quanh khác nhau của ứng dụng của bạn. Các thành phần này có thể sử dụng một ID mã thông báo như một cơ chế xác thực nhẹ chứng thực ứng dụng và người dùng. Nhưng trước khi bạn có thể sử dụng các thông tin trong ID thẻ hoặc dựa vào nó như là một sự khẳng định rằng người dùng đã xác thực, bạn phải xác nhận nó.

Xác nhận của một thẻ ID đòi hỏi một vài bước sau:

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

Bước 2-5 liên quan đến chỉ chuỗi và ngày so sánh mà là khá đơn giản, vì vậy chúng tôi sẽ không chi tiết chúng ở đây.

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

Các tokeninfo endpoint là hữu ích để gỡ lỗi nhưng đối với mục đích sản xuất, lấy khóa công khai của Google từ khóa Endpoint và thực hiện việc xác nhận tại địa phương. Bạn nên lấy các phím URI từ tài liệu Discovery sử dụng jwks_uri giá trị siêu dữ liệu. Yêu cầu đến thiết bị đầu cuối gỡ lỗi có thể được tăng cường hoặc tùy thuộc vào lỗi liên tục.

Kể từ khi Google thay đổi khóa công khai của nó chỉ không thường xuyên, bạn có thể cache họ sử dụng các chỉ thị bộ nhớ cache của phản ứng HTTP, và trong phần lớn các trường hợp, thực hiện xác nhận địa phương hiệu quả hơn nhiều so với bằng tokeninfo endpoint. xác nhận điều này đòi hỏi lấy và phân tích chứng, và làm cho các cuộc gọi mã hóa thích hợp để kiểm tra chữ ký. Thư viện May mắn thay, có được hạnh sửa lỗi có sẵn trong một loạt các ngôn ngữ để thực hiện điều này (xem jwt.io ).

Thu thập thông tin lý lịch thành viên

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

  1. Để có OpenID-tuân thủ, bạn phải bao gồm openid profile giá trị phạm vi trong của bạn yêu cầu xác thực .

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

    scope=openid%20profile%20email
  2. Thêm truy cập của bạn token để tiêu đề uỷ quyền và thực hiện một HTTPS GET yêu cầu đến UserInfo endpoint, mà bạn nên lấy từ tài liệu Discovery sử dụng userinfo_endpoint giá trị siêu dữ liệu. Câu trả lời UserInfo bao gồm thông tin về người dùng, như mô tả trong OpenID Connect Standard Claimsclaims_supported giá trị siêu dữ liệu của tài liệu Discovery. Người dùng hoặc tổ chức của họ có thể chọn để cung cấp hoặc giữ lại các lĩnh vực nhất định, vì vậy bạn có thể không nhận được thông tin cho mọi lĩnh vực cho phạm vi được ủy quyền tiếp cận.

Các tài liệu Discovery

Giao thức OpenID Connect yêu cầu sử dụng nhiều thiết bị đầu cuối để xác thực người dùng, và yêu cầu nguồn lực bao gồm thẻ, thông tin người dùng, và các phím công cộng.

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

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

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

Dưới đây là một ví dụ của một tài liệu đó; tên trường là những quy định tại OpenID Connect Discovery 1.0 (tham khảo tài liệu đó cho ý nghĩa của chúng). Các giá trị này là hoàn toàn minh họa và có thể thay đổi, mặc dù họ đượ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 một HTTP khứ hồi bằng cách cache giá trị từ tài liệu Discovery. Chuẩn tiêu đề HTTP bộ nhớ đệm được sử dụng và cần được tôn trọng.

thư viện khách hàng

Các thư viện khách hàng sau đây làm cho việc thực hiện OAuth 2.0 đơn giản hơn bằng cách tích hợp với các khuôn khổ phổ biến:

OpenID Connect tuân thủ

Hệ thống xác thực OAuth 2.0 của Google hỗ trợ các tính năng cần thiết của OpenID Connect Lõi đặc điểm kỹ thuật. Bất kỳ khách hàng được thiết kế để làm việc với OpenID Connect nên tương thích với dịch vụ này (với ngoại lệ của các yêu cầu đối tượng OpenID ).