Google cam kết nâng cao công bằng chủng tộc cho các cộng đồng Da đen. Xem làm thế nào.

Sử dụng OAuth 2.0 cho các ứng dụng Máy chủ đến Máy chủ

Hệ thống Google OAuth 2.0 hỗ trợ các tương tác giữa máy chủ với máy chủ, chẳng hạn như tương tác giữa ứng dụng web và dịch vụ của Google. Đối với kịch bản này, bạn cần có một tài khoản dịch vụ, đó là một tài khoản đó thuộc về ứng dụng của bạn thay vì để một người dùng cuối cá nhân. Ứng dụng của bạn gọi các API của Google thay mặt cho tài khoản dịch vụ, vì vậy người dùng không trực tiếp tham gia. Trường hợp này đôi khi được gọi là "OAuth hai chân" hoặc "2LO". (Thuật ngữ liên quan "OAuth ba bên" đề cập đến các tình huống trong đó ứng dụng của bạn thay mặt người dùng cuối gọi các API của Google và trong đó đôi khi cần phải có sự đồng ý của người dùng.)

Thông thường, một ứng dụng sử dụng tài khoản dịch vụ khi ứng dụng sử dụng các API của Google để làm việc với dữ liệu của chính nó thay vì dữ liệu của người dùng. Ví dụ: một ứng dụng sử dụng Google Cloud Datastore để duy trì dữ liệu sẽ sử dụng tài khoản dịch vụ để xác thực các lệnh gọi của nó tới API Google Cloud Datastore.

Google Workspace quản trị viên miền cũng có thể cấp dịch vụ chiếm quyền miền rộng đến dữ liệu người dùng truy cập trên danh nghĩa của người dùng trong miền.

Tài liệu này mô tả cách ứng dụng có thể hoàn thành luồng OAuth 2.0 từ máy chủ đến máy chủ bằng cách sử dụng thư viện ứng dụng khách API của Google (được khuyến nghị) hoặc HTTP.

Tổng quat

Để hỗ trợ máy chủ đến máy chủ tương tác, đầu tiên tạo ra một tài khoản dịch vụ cho dự án của bạn trong API Console. Nếu bạn muốn truy cập dữ liệu người dùng cho những người dùng trong tài khoản Google Workspace của mình, thì hãy ủy quyền quyền truy cập trên toàn miền cho tài khoản dịch vụ.

Sau đó, ứng dụng của bạn chuẩn bị thực hiện các lệnh gọi API được ủy quyền bằng cách sử dụng thông tin đăng nhập của tài khoản dịch vụ để yêu cầu mã thông báo truy cập từ máy chủ xác thực OAuth 2.0.

Cuối cùng, ứng dụng của bạn có thể sử dụng mã thông báo truy cập để gọi các API của Google.

Tạo tài khoản dịch vụ

Thông tin đăng nhập của tài khoản dịch vụ bao gồm địa chỉ email được tạo là duy nhất và ít nhất một cặp khóa công khai / riêng tư. Nếu ủy quyền trên toàn miền được bật, thì ID khách hàng cũng là một phần của thông tin đăng nhập của tài khoản dịch vụ.

Nếu ứng dụng của bạn chạy trên Google App Engine, tài khoản dịch vụ sẽ tự động được thiết lập khi bạn tạo dự án của mình.

Nếu ứng dụng của bạn chạy trên Google Compute Engine, tài khoản dịch vụ cũng được thiết lập tự động khi bạn tạo dự án của mình, nhưng bạn phải chỉ định phạm vi mà ứng dụng của bạn cần truy cập khi bạn tạo một phiên bản Google Compute Engine. Để biết thêm thông tin, xem Chuẩn bị một thể hiện các tài khoản sử dụng dịch vụ .

Nếu ứng dụng của bạn không chạy trên Google App Engine hoặc Google Compute Engine, bạn phải có được những thông tin quan trọng trong Google API Console. Để tạo thông tin đăng nhập tài khoản dịch vụ hoặc để xem thông tin đăng nhập công khai mà bạn đã tạo, hãy làm như sau:

  1. Mở Service accounts page .
  2. If prompted, select a project, or create a new one.
  3. Nhấp vào Tạo tài khoản dịch vụ .
  4. Trong Chi tiết tài khoản dịch vụ , nhập tên, ID và mô tả cho tài khoản dịch vụ, sau đó bấm Tạo .
  5. Tùy chọn: Trong quyền Tài khoản dịch vụ , chọn vai trò IAM để cấp cho tài khoản dịch vụ, sau đó nhấp vào Tiếp tục .
  6. Tùy chọn: Trong Cấp cho người dùng quyền truy cập vào tài khoản dịch vụ này , hãy thêm người dùng hoặc nhóm được phép sử dụng và quản lý tài khoản dịch vụ.
  7. Bấm khóa Tạo , sau đó bấm Tạo .

Cặp khóa công khai / riêng mới của bạn được tạo và tải xuống máy của bạn; nó phục vụ như là bản sao duy nhất của khóa riêng. Bạn có trách nhiệm lưu trữ nó một cách an toàn. Nếu bạn mất cặp khóa này, bạn sẽ cần tạo một cặp mới.

Nếu bạn cần cấp quyền toàn bộ tên miền G Suite cho tài khoản dịch vụ, hãy nhấp vào địa chỉ email của tài khoản dịch vụ mà bạn đã tạo, sau đó sao chép giá trị từ hộp ID duy nhất .

Để ủy quyền cho tài khoản dịch vụ, hãy sử dụng giá trị bạn đã sao chép làm ID khách hàng.

Bạn có thể quay trở lại API Console bất cứ lúc nào để xem địa chỉ email, dấu vân tay khóa công khai, và các thông tin khác, hoặc để tạo thêm công / tư nhân cặp khóa. Để biết thêm chi tiết về thông tin tài khoản dịch vụ trong API Console, xem chiếm Dịch vụ trong API Consoletập tin trợ giúp.

Ghi lại địa chỉ email của tài khoản dịch vụ và lưu trữ tệp khóa cá nhân của tài khoản dịch vụ ở một vị trí mà ứng dụng của bạn có thể truy cập được. Ứng dụng của bạn cần chúng để thực hiện các lệnh gọi API được ủy quyền.

Ủy quyền trên toàn miền cho tài khoản dịch vụ

Nếu bạn có tài khoản Google Workspace, quản trị viên của tổ chức có thể ủy quyền cho ứng dụng truy cập dữ liệu người dùng thay mặt cho người dùng trong miền Google Workspace. Ví dụ: một ứng dụng sử dụng API Lịch Google để thêm sự kiện vào lịch của tất cả người dùng trong miền Google Workspace sẽ sử dụng tài khoản dịch vụ để truy cập API Lịch Google thay mặt cho người dùng. Việc ủy ​​quyền tài khoản dịch vụ thay mặt người dùng trong miền truy cập dữ liệu đôi khi được gọi là "ủy quyền trên toàn miền" cho tài khoản dịch vụ.

Để uỷ quyền miền rộng đến một tài khoản dịch vụ, đầu tiên cho phép phái đoàn miền toàn cho tài khoản dịch vụ hiện có trong Service accounts page hoặc tạo một tài khoản dịch vụ mới với phái đoàn miền toàn được kích hoạt.

Sau đó, quản trị viên cấp cao của miền Google Workspace phải hoàn thành các bước sau:

  1. Từ miền Google Workspace của bạn giao diện điều khiển quản trị , vào Menu chính > Bảo mật> API Controls.
  2. Trong cửa sổ đoàn rộng Domain, chọn Manage miền Phái đoàn Wide.
  3. Bấm Thêm mới.
  4. Trong lĩnh vực Client ID, nhập ID ứng dụng các tài khoản dịch vụ. Bạn có thể tìm ID khách hàng tài khoản dịch vụ của bạn trong Service accounts page.
  5. Trong phạm vi OAuth trường (dấu phẩy phân cách), nhập danh sách các phạm vi ứng dụng của bạn cần được cấp quyền truy cập vào. Ví dụ, nếu ứng dụng của bạn cần truy cập miền toàn đầy đủ để các API của Google Drive và API Lịch Google, hãy nhập: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth / lịch.
  6. Nhấn vào Authorize.

Ứng dụng của bạn hiện có quyền thực hiện lệnh gọi API với tư cách là người dùng trong miền của bạn (để "mạo danh" người dùng). Khi bạn chuẩn bị thực hiện các lệnh gọi API được ủy quyền, bạn chỉ định người dùng mạo danh.

Chuẩn bị thực hiện lệnh gọi API được ủy quyền

Java

Sau khi bạn có được địa chỉ email của khách hàng và khóa bí mật từ API Console, sử dụng thư viện của Google API Client for Java để tạo ra một GoogleCredential đối tượng từ thông tin tài khoản dịch vụ và phạm vi ứng dụng của bạn cần truy cập vào. Ví dụ:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Nếu bạn đang phát triển một ứng dụng trên Google Cloud Platform, bạn có thể sử dụng thông tin ứng dụng mặc định thay vào đó, có thể đơn giản hóa quá trình này.

Ủy quyền trên toàn miền

Nếu bạn đã ủy quyền truy cập miền toàn cho tài khoản dịch vụ và bạn muốn mạo danh một tài khoản người dùng, ghi rõ địa chỉ email của tài khoản người dùng với createDelegated phương pháp của GoogleCredential đối tượng. Ví dụ:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("user@example.com");

Sử dụng các GoogleCredential đối tượng để gọi Google API trong ứng dụng của bạn.

Python

Sau khi bạn có được địa chỉ email của khách hàng và khóa bí mật từ API Console, sử dụng thư viện của Google API Client for Python để hoàn thành các bước sau:

  1. Tạo một Credentials đối tượng từ thông tin tài khoản dịch vụ và phạm vi ứng dụng của bạn cần truy cập vào. Ví dụ:
    from google.oauth2 import service_account
    
    SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
    SERVICE_ACCOUNT_FILE = '/path/to/service.json'
    
    credentials = service_account.Credentials.from_service_account_file(
            SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    Nếu bạn đang phát triển một ứng dụng trên Google Cloud Platform, bạn có thể sử dụng thông tin ứng dụng mặc định thay vào đó, có thể đơn giản hóa quá trình này.

  2. Ủy quyền trên toàn miền

    Nếu bạn đã ủy quyền truy cập miền toàn cho tài khoản dịch vụ và bạn muốn mạo danh một tài khoản người dùng, sử dụng with_subject phương pháp của một hiện ServiceAccountCredentials đối tượng. Ví dụ:

    delegated_credentials = credentials.with_subject('user@example.org')

Sử dụng đối tượng Thông tin đăng nhập để gọi API Google trong ứng dụng của bạn.

HTTP / REST

Sau khi bạn có được ID của khách hàng và khóa bí mật từ API Console, ứng dụng của bạn cần phải hoàn tất các bước sau:

  1. Tạo Mã thông báo web JSON (JWT, phát âm là "jot") bao gồm tiêu đề, tập hợp xác nhận quyền sở hữu và chữ ký.
  2. Yêu cầu mã thông báo truy cập từ Máy chủ ủy quyền Google OAuth 2.0.
  3. Xử lý phản hồi JSON mà Máy chủ ủy quyền trả về.

Các phần tiếp theo mô tả cách hoàn thành các bước này.

Nếu câu trả lời bao gồm một thẻ truy cập, bạn có thể sử dụng access token để gọi một API của Google . (Nếu phản hồi không bao gồm mã thông báo truy cập, yêu cầu JWT và mã thông báo của bạn có thể không được tạo đúng cách hoặc tài khoản dịch vụ có thể không có quyền truy cập vào phạm vi được yêu cầu.)

Khi thẻ truy cập hết hạn , ứng dụng của bạn tạo ra một JWT, dấu hiệu đó, và yêu cầu một thẻ truy cập.

Ứng dụng máy chủ của bạn sử dụng JWT để yêu cầu mã thông báo từ Máy chủ ủy quyền của Google, sau đó sử dụng mã thông báo này để gọi điểm cuối API Google. Không có người dùng cuối nào tham gia.

Phần còn lại của phần này mô tả các chi tiết cụ thể của việc tạo JWT, ký JWT, hình thành yêu cầu mã thông báo truy cập và xử lý phản hồi.

Tạo JWT

JWT bao gồm ba phần: tiêu đề, tập hợp xác nhận quyền sở hữu và chữ ký. Tiêu đề và tập hợp xác nhận quyền sở hữu là các đối tượng JSON. Các đối tượng JSON này được tuần tự hóa thành UTF-8 byte, sau đó được mã hóa bằng cách sử dụng mã hóa Base64url. Mã hóa này cung cấp khả năng phục hồi chống lại các thay đổi mã hóa do các hoạt động mã hóa lặp lại. Các tiêu đề, bộ khiếu nại, và chữ ký được nối với nhau bằng một dấu chấm ( . ) Nhân vật.

JWT được cấu tạo như sau:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

Chuỗi cơ sở cho chữ ký như sau:

{Base64url encoded header}.{Base64url encoded claim set}
Hình thành tiêu đề JWT

Tiêu đề bao gồm hai trường cho biết thuật toán ký và định dạng của xác nhận. Cả hai trường đều là bắt buộc và mỗi trường chỉ có một giá trị. Khi các thuật toán và định dạng bổ sung được giới thiệu, tiêu đề này sẽ thay đổi theo.

Tài khoản dịch vụ dựa trên thuật toán RSA SHA-256 và định dạng mã thông báo JWT. Kết quả là, biểu diễn JSON của tiêu đề như sau:

{"alg":"RS256","typ":"JWT"}

Biểu diễn Base64url của điều này như sau:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Hình thành bộ yêu cầu JWT

Bộ xác nhận quyền sở hữu JWT chứa thông tin về JWT, bao gồm các quyền được yêu cầu (phạm vi), mục tiêu của mã thông báo, tổ chức phát hành, thời gian mã thông báo được phát hành và thời gian tồn tại của mã thông báo. Hầu hết các trường là bắt buộc. Giống như tiêu đề JWT, tập hợp xác nhận quyền sở hữu JWT là một đối tượng JSON và được sử dụng để tính toán chữ ký.

Yêu cầu bắt buộc

Các yêu cầu bắt buộc trong bộ yêu cầu JWT được hiển thị bên dưới. Chúng có thể xuất hiện theo bất kỳ thứ tự nào trong bộ xác nhận quyền sở hữu.

Tên Sự miêu tả
iss Địa chỉ email của tài khoản dịch vụ.
scope Danh sách được phân cách bằng dấu cách gồm các quyền mà ứng dụng yêu cầu.
aud Một mô tả về mục tiêu dự kiến ​​của khẳng định. Khi đưa ra một yêu cầu truy cập thẻ giá trị này luôn là https://oauth2.googleapis.com/token .
exp Thời gian hết hạn của xác nhận, được chỉ định bằng giây kể từ 00:00:00 UTC, ngày 1 tháng 1 năm 1970. Giá trị này có tối đa 1 giờ sau thời gian ban hành.
iat Thời gian xác nhận được đưa ra, được chỉ định bằng giây kể từ 00:00:00 UTC, ngày 1 tháng 1 năm 1970.

Trình bày JSON của các trường bắt buộc trong tập hợp xác nhận quyền sở hữu JWT được hiển thị bên dưới:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Yêu cầu bổ sung

Trong một số trường hợp doanh nghiệp, một ứng dụng có thể sử dụng ủy quyền trên toàn miền để thay mặt cho một người dùng cụ thể trong một tổ chức. Quyền thực hiện kiểu mạo danh này phải được cấp trước khi ứng dụng có thể mạo danh người dùng và thường do quản trị viên cấp cao xử lý. Để biết thêm thông tin, xem Kiểm soát truy cập API với đoàn đại biểu miền toàn .

Để có được một access token rằng tài trợ một ứng dụng phân quyền truy cập vào một tài nguyên, bao gồm địa chỉ email của người dùng trong tập khẳng định JWT như giá trị của các sub lĩnh vực.

Tên Sự miêu tả
sub Địa chỉ email của người dùng mà ứng dụng đang yêu cầu quyền truy cập được ủy quyền.

Nếu một ứng dụng không được phép để mạo danh một người sử dụng, đáp ứng một yêu cầu truy cập token bao gồm các sub lĩnh vực sẽ là một lỗi .

Một ví dụ về yêu cầu bồi thường bộ JWT bao gồm các sub lĩnh vực được hiển thị dưới đây:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Mã hóa bộ yêu cầu JWT

Giống như tiêu đề JWT, tập hợp xác nhận quyền sở hữu JWT phải được tuần tự hóa thành mã hóa UTF-8 và Base64url an toàn. Dưới đây là ví dụ về biểu diễn JSON của tập hợp Yêu cầu bồi thường JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Tính toán chữ ký

JSON Web Chữ ký (JWS) là đặc điểm kỹ thuật mà hướng dẫn các cơ chế tạo chữ ký cho JWT. Đầu vào cho chữ ký là mảng byte có nội dung sau:

{Base64url encoded header}.{Base64url encoded claim set}

Thuật toán ký trong tiêu đề JWT phải được sử dụng khi tính toán chữ ký. Thuật toán ký duy nhất được Máy chủ ủy quyền Google OAuth 2.0 hỗ trợ là RSA sử dụng thuật toán băm SHA-256. Này được thể hiện như RS256 trong alg lĩnh vực trong tiêu đề JWT.

Ký tên vào biểu UTF-8 của đầu vào sử dụng SHA256withRSA (còn gọi là RSASSA-PKCS1-V1_5-SIGN với hàm băm SHA-256) với khóa bí mật lấy từ Google API Console. Đầu ra sẽ là một mảng byte.

Chữ ký sau đó phải được mã hóa Base64url. Các tiêu đề, bộ khiếu nại, và chữ ký được nối với nhau bằng một dấu chấm ( . ) Nhân vật. Kết quả là JWT. Nó phải như sau (đã thêm dấu ngắt dòng để rõ ràng):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Dưới đây là ví dụ về JWT trước khi mã hóa Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Dưới đây là ví dụ về JWT đã được ký và sẵn sàng để truyền:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Thực hiện yêu cầu mã thông báo truy cập

Sau khi tạo JWT đã ký, ứng dụng có thể sử dụng nó để yêu cầu mã thông báo truy cập. Truy cập này dấu hiệu yêu cầu là một HTTPS POST yêu cầu, và cơ thể là URL được mã hóa. URL được hiển thị bên dưới:

https://oauth2.googleapis.com/token

Các thông số sau được yêu cầu trong HTTPS POST yêu cầu:

Tên Sự miêu tả
grant_type Sử dụng các chuỗi sau, URL mã hóa khi cần thiết: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JWT, bao gồm cả chữ ký.

Dưới đây là một bãi chứa nguyên liệu của HTTPS POST yêu cầu sử dụng trong một access token yêu cầu:

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Dưới đây là cùng một yêu cầu, sử dụng curl :

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Xử lý phản hồi

Nếu JWT và yêu cầu mã thông báo truy cập được tạo đúng cách và tài khoản dịch vụ có quyền thực hiện hoạt động, thì phản hồi JSON từ Máy chủ cấp quyền sẽ bao gồm mã thông báo truy cập. Sau đây là một ví dụ phản hồi:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Thẻ truy cập có thể được tái sử dụng trong cửa sổ thời gian theo quy định của expires_in giá trị.

Gọi API Google

Java

Sử dụng các GoogleCredential đối tượng để gọi API của Google bằng cách hoàn thành các bước sau:

  1. Tạo một đối tượng phục vụ cho các API mà bạn muốn gọi bằng cách sử dụng GoogleCredential đối tượng. Ví dụ:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Hãy yêu cầu đối với các dịch vụ API bằng cách sử dụng giao diện được cung cấp bởi các đối tượng phục vụ . Ví dụ, để liệt kê các trường hợp cơ sở dữ liệu đám mây SQL trong thú vị-dụ-123 dự án:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Python

Sử dụng ủy quyền Credentials phản đối gọi API của Google bằng cách hoàn thành các bước sau:

  1. Xây dựng một đối tượng dịch vụ cho API mà bạn muốn gọi. Bạn xây dựng aa đối tượng dịch vụ bằng cách gọi build chức năng với tên và phiên bản của API và được ủy quyền Credentials đối tượng. Ví dụ, để gọi phiên bản 1beta3 của Cục API Mây SQL:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Hãy yêu cầu đối với các dịch vụ API bằng cách sử dụng giao diện được cung cấp bởi các đối tượng phục vụ . Ví dụ, để liệt kê các trường hợp cơ sở dữ liệu đám mây SQL trong thú vị-dụ-123 dự án:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP / REST

Sau khi ứng dụng của bạn nhận được mã thông báo truy cập, bạn có thể sử dụng mã này để thực hiện các cuộc gọi tới API Google thay mặt cho tài khoản dịch vụ hoặc tài khoản người dùng nhất định nếu (các) phạm vi truy cập mà API yêu cầu đã được cấp. Để làm điều này, bao gồm access token trong một yêu cầu đến API bằng cách bao gồm cả một access_token tham số truy vấn hoặc một Authorization tiêu đề HTTP Bearer giá trị. Khi có thể, tiêu đề HTTP được ưu tiên hơn, vì các chuỗi truy vấn có xu hướng hiển thị trong nhật ký máy chủ. Trong hầu hết các trường hợp, bạn có thể sử dụng một thư viện client để thiết lập cuộc gọi của bạn đến Google API (ví dụ, khi gọi API Drive tập tin ).

Bạn có thể thử tất cả các API của Google và xem phạm vi của họ tại OAuth 2.0 Sân chơi .

Ví dụ về HTTP GET

Một cuộc gọi đến các drive.files endpoint (API Drive Files) bằng cách sử dụng Authorization: Bearer tiêu đề HTTP có thể trông giống như sau. Lưu ý rằng bạn cần chỉ định mã thông báo truy cập của riêng mình:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Dưới đây là một lời kêu gọi các API tương tự cho các người dùng xác thực bằng cách sử dụng access_token tham số chuỗi truy vấn:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl ví dụ

Bạn có thể kiểm tra các lệnh này với curl ứng dụng dòng lệnh. Dưới đây là một ví dụ sử dụng tùy chọn tiêu đề HTTP (ưu tiên):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Hoặc, cách khác, tùy chọn tham số chuỗi truy vấn:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Khi mã thông báo truy cập hết hạn

Truy cập mã thông báo do Google OAuth 2.0 Authorization server hết hiệu lực sau thời gian được cung cấp bởi các expires_in giá trị. Khi mã thông báo truy cập hết hạn, ứng dụng sẽ tạo một JWT khác, ký tên vào nó và yêu cầu mã thông báo truy cập khác.

Mã lỗi JWT

error lĩnh vực error_description lĩnh vực Nghĩa Làm thế nào để giải quyết
unauthorized_client Unauthorized client or scope in request. Nếu bạn đang cố gắng sử dụng ủy quyền trên toàn miền, tài khoản dịch vụ không được ủy quyền trong Bảng điều khiển dành cho quản trị viên trên miền của người dùng.

Đảm bảo rằng các tài khoản dịch vụ được ủy quyền trong đoàn Domain-rộng trang của giao diện điều khiển quản trị cho người sử dụng trong sub tuyên bố (lĩnh vực).

Mặc dù thường mất vài phút, nhưng có thể mất đến 24 giờ để ủy quyền phổ biến cho tất cả người dùng trong Tài khoản Google của bạn.

unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. Tài khoản dịch vụ đã được cấp phép bằng cách sử dụng địa chỉ email khách hàng thay vì ID khách hàng (số) trong Bảng điều khiển dành cho quản trị viên. Trong phái đoàn miền toàn trang trong quản lý giao diện điều khiển, loại bỏ các khách hàng, và rồi thêm lại nó với các ID số.
access_denied (bất kỳ giá trị nào) Nếu bạn đang sử dụng ủy quyền trên toàn miền, một hoặc nhiều phạm vi được yêu cầu sẽ không được ủy quyền trong Bảng điều khiển dành cho quản trị viên.

Đảm bảo rằng các tài khoản dịch vụ được ủy quyền trong đoàn Domain-rộng trang của giao diện điều khiển quản trị cho người sử dụng trong sub tuyên bố (trường), và nó bao gồm tất cả các phạm vi bạn đang yêu cầu trong scope tuyên bố của JWT của bạn.

Mặc dù thường mất vài phút, nhưng có thể mất đến 24 giờ để ủy quyền phổ biến cho tất cả người dùng trong Tài khoản Google của bạn.

invalid_grant Not a valid email. Người dùng không tồn tại. Hãy kiểm tra xem địa chỉ email trong sub tuyên bố (trường) là đúng.
invalid_grant

Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.

Thông thường, nó có nghĩa là thời gian hệ thống cục bộ không chính xác. Nó cũng có thể xảy ra nếu exp giá trị là hơn 65 phút trong tương lai từ iat giá trị, hoặc exp giá trị thấp hơn iat giá trị.

Đảm bảo rằng đồng hồ trên hệ thống nơi JWT được tạo là chính xác. Nếu cần thiết, đồng bộ hóa thời gian của bạn với Google NTP .

invalid_grant Invalid JWT Signature.

Xác nhận JWT được ký bằng khóa riêng không được liên kết với tài khoản dịch vụ được xác định bởi email khách hàng hoặc khóa được sử dụng đã bị xóa, vô hiệu hóa hoặc đã hết hạn.

Ngoài ra, xác nhận JWT có thể được mã hóa không chính xác - nó phải được mã hóa Base64, không có dòng mới hoặc dấu bằng.

Giải mã bộ xác nhận JWT và xác minh khóa đã ký xác nhận được liên kết với tài khoản dịch vụ.

Cố gắng sử dụng thư viện OAuth do Google cung cấp để đảm bảo JWT được tạo chính xác.

invalid_scope Invalid OAuth scope or ID token audience provided. Không có phạm vi nào được yêu cầu (danh sách phạm vi trống) hoặc một trong các phạm vi được yêu cầu không tồn tại (tức là không hợp lệ).

Đảm bảo rằng scope tuyên bố (field) của JWT được phổ biến, và so sánh phạm vi mà nó chứa với phạm vi tài liệu cho các API mà bạn muốn sử dụng, để đảm bảo không có sai sót hoặc lỗi chính tả.

Lưu ý rằng danh sách các phạm vi trong scope nhu cầu đòi chủ quyền được tách bằng dấu cách, không dấu phẩy.

disabled_client The OAuth client was disabled. Khóa được sử dụng để ký xác nhận JWT đã bị vô hiệu hóa.

Tới Google API Console, và dưới IAM & Quản trị> Tài khoản dịch vụ, cho phép các tài khoản dịch vụ, trong đó có "ID Key" sử dụng để ký khẳng định.

Phụ lục: Ủy quyền tài khoản dịch vụ không có OAuth

Với một số API của Google, bạn có thể thực hiện các lệnh gọi API được ủy quyền bằng cách sử dụng JWT đã ký trực tiếp dưới dạng mã thông báo mang, thay vì mã thông báo truy cập OAuth 2.0. Khi điều này là có thể, bạn có thể tránh phải thực hiện yêu cầu mạng tới máy chủ ủy quyền của Google trước khi thực hiện lệnh gọi API.

Nếu API bạn muốn gọi có một định nghĩa vụ công bố trên kho lưu trữ Google API GitHub , bạn có thể thực hiện cuộc gọi API cho phép sử dụng một JWT thay vì một thẻ truy cập. Làm như vậy:

  1. Tạo một tài khoản dịch vụ như đã mô tả ở trên. Đảm bảo giữ tệp JSON mà bạn nhận được khi tạo tài khoản.
  2. Sử dụng bất kỳ thư viện JWT tiêu chuẩn, chẳng hạn như một phát hiện tại jwt.io , tạo một JWT với một header và tải trọng như ví dụ sau:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • Đối với kid lĩnh vực trong tiêu đề, xác định tài khoản dịch vụ của bạn chìa khóa ID riêng. Bạn có thể tìm thấy giá trị này trong private_key_id lĩnh vực dịch vụ tập tin tài khoản JSON của bạn.
    • Đối với isssub lĩnh vực, xác định địa chỉ email tài khoản dịch vụ của bạn. Bạn có thể tìm thấy giá trị này trong client_email lĩnh vực dịch vụ tập tin tài khoản JSON của bạn.
    • Đối với aud lĩnh vực, xác định điểm cuối API. Ví dụ: https:// SERVICE .googleapis.com/ .
    • Đối với iat lĩnh vực, xác định thời gian Unix hiện tại, và cho exp lĩnh vực, xác định thời gian chính xác 3600 giây sau, khi JWT sẽ hết hạn.

Ký JWT bằng RSA-256 bằng khóa riêng có trong tệp JSON tài khoản dịch vụ của bạn.

Ví dụ:

Java

Sử dụng google-api-java-clientjava-JWT :

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Sử dụng PyJWT :

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')
  1. Gọi API, sử dụng JWT ký như người mang mã thông báo:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com