OAuth 2.0 cho ứng dụng dành cho máy tính

Tài liệu này giải thích cách các ứng dụng dành cho máy tính (chẳng hạn như ứng dụng chạy trên Windows, macOS hoặc Linux hoặc các công cụ giao diện dòng lệnh (CLI)) sử dụng các điểm cuối OAuth 2.0 của Google để cho phép truy cập vào các API của Google.

OAuth 2.0 cho phép người dùng chia sẻ dữ liệu cụ thể với một ứng dụng trong khi vẫn giữ bí mật tên người dùng, mật khẩu và các thông tin khác. Ví dụ: một ứng dụng có thể sử dụng OAuth 2.0 để xin phép người dùng lưu trữ tệp trong Google Drive của họ.

Ứng dụng dành cho máy tính được cài đặt cục bộ trên máy của người dùng (chẳng hạn như phần mềm độc lập dành cho máy tính, công cụ CLI dành cho nhà phát triển, tiện ích đồng bộ hoá trong nền hoặc tập lệnh). Vì các ứng dụng này được phân phối đến từng thiết bị, nên chúng tôi giả định rằng các ứng dụng này không thể giữ bí mật (chúng là ứng dụng công khai). Các ứng dụng này có thể truy cập vào API của Google khi người dùng đang tương tác với ứng dụng hoặc khi ứng dụng đang chạy ở chế độ nền.

Quy trình uỷ quyền này tương tự như quy trình dùng cho ứng dụng máy chủ web. Điểm khác biệt chính là ứng dụng dành cho máy tính phải mở trình duyệt hệ thống và cung cấp URI chuyển hướng cục bộ (chẳng hạn như địa chỉ IP lặp lại) để xử lý phản hồi từ máy chủ uỷ quyền của Google.

Thư viện và mẫu

Bạn nên sử dụng Thư viện ứng dụng API của Google cho ngôn ngữ lập trình của mình (ví dụ: Python, Java, Node.js, Go, .NET) khi triển khai OAuth 2.0 cho ứng dụng dành cho máy tính. Thư viện ứng dụng xử lý việc uỷ quyền người dùng và quản lý mã thông báo, giúp việc triển khai trở nên đơn giản hơn và ít gặp lỗi hơn so với việc sử dụng trực tiếp các điểm cuối HTTP/REST cấp thấp hơn.

Đối với ứng dụng di động, hãy xem hướng dẫn uỷ quyền cho Android và iOS.

Đối với các ứng dụng chạy trên thiết bị không hỗ trợ trình duyệt hệ thống hoặc có khả năng nhập dữ liệu hạn chế, chẳng hạn như TV, máy chơi trò chơi, máy ảnh hoặc máy in, hãy xem bài viết OAuth 2.0 cho TV và thiết bị hoặc Đăng nhập trên TV và thiết bị đầu vào hạn chế.

Điều kiện tiên quyết

Bật API cho dự án của bạn

Mọi ứng dụng gọi API của Google đều cần bật các API đó trong Bảng điều khiển API.

Cách bật API cho dự án:

1. Mở Thư viện API trong Google API Console.
2. Nếu bạn nhận được lời nhắc, hãy chọn một dự án hoặc tạo dự án mới.
3. Thư viện API liệt kê tất cả những API có sẵn, được nhóm theo nhóm sản phẩm và mức độ phổ biến. Nếu API bạn muốn chọn không hiển thị trong danh sách, hãy sử dụng chức năng tìm kiếm để tìm API đó hoặc nhấp vào Xem tất cả trong nhóm sản phẩm chứa API đó.
4. Chọn API bạn muốn bật, sau đó nhấp vào nút Bật.
5. Nếu bạn nhận được một lời nhắc, hãy bật tính năng thanh toán.
6. Nếu bạn nhận được lời nhắc, hãy đọc và chấp nhận Điều khoản dịch vụ của API.

Tạo thông tin uỷ quyền

Bất kỳ ứng dụng nào sử dụng OAuth 2.0 để truy cập vào API của Google đều phải có thông tin xác thực uỷ quyền để xác định ứng dụng đó với máy chủ OAuth 2.0 của Google. Các bước sau đây giải thích cách tạo thông tin xác thực cho dự án của bạn. Sau đó, các ứng dụng của bạn có thể sử dụng thông tin đăng nhập để truy cập vào các API mà bạn đã bật cho dự án đó.

1. Chuyển đến trang Ứng dụng.
2. Nhấp vào Tạo ứng dụng.
3. Chọn loại ứng dụng Ứng dụng dành cho máy tính.
4. Trong trường Name (Tên), hãy nhập tên cho ứng dụng OAuth. Tên này được hiển thị trên trang Ứng dụng của dự án để xác định ứng dụng.
5. Nhấp vào Tạo.

Mã ứng dụng khách và khoá bí mật của ứng dụng khách sẽ được tạo và hiển thị trong Google Cloud Console. Ứng dụng dành cho máy tính là ứng dụng khách công khai và không thể giữ bí mật. Luôn sử dụng PKCE (Khoá xác thực cho việc trao đổi mã) khi yêu cầu mã uỷ quyền.

Xác định phạm vi truy cập

Phạm vi cho phép ứng dụng của bạn chỉ yêu cầu quyền truy cập vào những tài nguyên cần thiết, đồng thời cho phép người dùng kiểm soát mức độ truy cập mà họ cấp cho ứng dụng của bạn. Do đó, có thể có mối quan hệ nghịch đảo giữa số lượng phạm vi được yêu cầu và khả năng nhận được sự đồng ý của người dùng.

Trước khi bắt đầu triển khai quy trình uỷ quyền OAuth 2.0, bạn nên xác định các phạm vi mà ứng dụng của bạn cần có quyền truy cập.

Tài liệu Phạm vi API OAuth 2.0 chứa danh sách đầy đủ các phạm vi mà bạn có thể sử dụng để truy cập vào các API của Google.

Lấy mã truy cập OAuth 2.0

Các bước sau đây cho thấy cách ứng dụng của bạn tương tác với máy chủ OAuth 2.0 của Google để nhận được sự đồng ý của người dùng nhằm thực hiện yêu cầu API thay mặt cho người dùng. Ứng dụng của bạn phải có sự đồng ý đó trước khi có thể thực thi yêu cầu API của Google cần có sự uỷ quyền của người dùng.

Bước 1: Tạo trình xác minh mã và thử thách

Google hỗ trợ giao thức Khoá xác thực cho việc trao đổi mã (PKCE) để giúp quy trình ứng dụng đã cài đặt trở nên an toàn hơn. Một trình xác minh mã duy nhất được tạo cho mỗi yêu cầu uỷ quyền và giá trị đã biến đổi của trình xác minh mã đó (gọi là "code_challenge") sẽ được gửi đến máy chủ uỷ quyền để lấy mã uỷ quyền.

Tạo trình xác minh mã

code_verifier là một chuỗi ngẫu nhiên mật mã có entropy cao, sử dụng các ký tự không được đặt trước [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", có độ dài tối thiểu là 43 ký tự và độ dài tối đa là 128 ký tự.

Trình xác minh mã phải có đủ entropy để không thể đoán được giá trị.

Tạo thử thách mã

Có hai phương thức tạo thử thách mã được hỗ trợ.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Bước 2: Gửi yêu cầu đến máy chủ OAuth 2.0 của Google

Để được người dùng uỷ quyền, hãy gửi yêu cầu đến máy chủ uỷ quyền của Google tại https://accounts.google.com/o/oauth2/v2/auth. Điểm cuối này xử lý việc tra cứu phiên hoạt động, xác thực người dùng và nhận được sự đồng ý của người dùng. Điểm cuối chỉ có thể truy cập được qua SSL và từ chối các kết nối HTTP (không phải SSL).

Máy chủ uỷ quyền hỗ trợ các tham số chuỗi truy vấn sau đây cho các ứng dụng đã cài đặt:

URL uỷ quyền mẫu

Các thẻ bên dưới cho thấy URL uỷ quyền mẫu cho các lựa chọn URI chuyển hướng.

Các URL này giống hệt nhau, ngoại trừ giá trị của tham số redirect_uri. Các URL này cũng chứa các tham số response_type và client_id bắt buộc cũng như tham số state không bắt buộc. Mỗi URL đều chứa dấu ngắt dòng và dấu cách để dễ đọc.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Bước 3: Google nhắc người dùng đồng ý

Trong bước này, người dùng quyết định xem có cấp cho ứng dụng của bạn quyền truy cập được yêu cầu hay không. Ở giai đoạn này, Google sẽ hiển thị một cửa sổ yêu cầu sự đồng ý, trong đó có tên ứng dụng của bạn và các dịch vụ API của Google mà ứng dụng đang yêu cầu quyền truy cập bằng thông tin xác thực của người dùng, cũng như thông tin tóm tắt về phạm vi truy cập sẽ được cấp. Sau đó, người dùng có thể đồng ý cấp quyền truy cập vào một hoặc nhiều phạm vi mà ứng dụng của bạn yêu cầu hoặc từ chối yêu cầu.

Ứng dụng của bạn không cần làm gì ở giai đoạn này vì ứng dụng đang chờ phản hồi từ máy chủ OAuth 2.0 của Google cho biết liệu có quyền truy cập nào được cấp hay không. Phản hồi đó được giải thích trong bước tiếp theo.

Bước 4: Xử lý phản hồi của máy chủ OAuth 2.0

Cách ứng dụng của bạn nhận được phản hồi uỷ quyền phụ thuộc vào lược đồ URI chuyển hướng mà ứng dụng sử dụng. Bất kể lược đồ nào, phản hồi sẽ chứa mã uỷ quyền (code) hoặc lỗi (error). Ví dụ: error=access_denied cho biết người dùng đã từ chối yêu cầu.

Nếu người dùng cấp quyền truy cập vào ứng dụng của bạn, thì bạn có thể đổi mã uỷ quyền lấy mã truy cập và mã làm mới như mô tả trong bước tiếp theo.

Bước 5: Đổi mã uỷ quyền lấy mã làm mới và mã truy cập

Để đổi mã uỷ quyền lấy mã truy cập, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các tham số sau:

Mặc dù việc sử dụng DPoP là không bắt buộc, nhưng bạn nên sử dụng để tăng cường bảo mật. Tính bảo mật của DPoP phụ thuộc vào việc khoá riêng tư chỉ được dùng cho một thiết bị; bạn nên lưu trữ khoá riêng tư theo cách không thể sao chép khoá đó ra khỏi thiết bị, chẳng hạn như bằng cách sử dụng TPM, Secure Enclave hoặc các kho khoá khác dựa trên phần cứng. Để sử dụng DPoP, ứng dụng của bạn phải tạo một JWT bằng chứng DPoP mới, duy nhất cho mỗi yêu cầu đến điểm cuối mã thông báo và thêm JWT đó làm tiêu đề yêu cầu HTTP.

Đoạn mã sau đây cho thấy một yêu cầu mẫu:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Tạo bằng chứng DPoP

Các bước sau đây cho biết cách tạo bằng chứng DPoP bằng OpenSSL từ dòng lệnh:

1. Tạo cặp khoá EC P-256:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. Tạo tiêu đề DPoP:

   Tiêu đề phải bao gồm các thông báo xác nhận quyền sở hữu typ, alg và jwk (khoá công khai). Giá trị x và y là toạ độ được mã hoá Base64Url của khoá công khai EC. Mã hoá Base64Url cho JSON này:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. Tạo tải trọng DPoP:

   Trọng tải phải bao gồm jti (giá trị nhận dạng riêng biệt cho yêu cầu), htm (phương thức HTTP, ví dụ: POST), htu (URI HTTP, ví dụ: https://oauth2.googleapis.com/token) và iat (thời điểm phát hành). Nếu nhận được số chỉ dùng một lần từ máy chủ trong tiêu đề DPoP-Nonce khi phản hồi một yêu cầu trước đó, thì bạn phải đưa giá trị số chỉ dùng một lần đó vào thông báo xác nhận quyền sở hữu nonce. Xác nhận nonce là không bắt buộc đối với việc trao đổi mã uỷ quyền và chỉ được sử dụng khi tiêu đề DPoP-Nonce đã được nhận trước đó. Mã hoá Base64Url cho JSON này:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   Giá trị jti phụ thuộc vào loại sàn giao dịch:

   • Đối với hoạt động trao đổi mã uỷ quyền, jti phải là hàm băm SHA256 được mã hoá Base64Url của mã uỷ quyền: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • Đối với hoạt động trao đổi mã làm mới, jti phải là giá trị nhận dạng duy nhất cho mỗi yêu cầu: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. Ký bằng chứng:

   Nối tiêu đề và tải trọng đã mã hoá bằng dấu chấm (.), sau đó ký kết quả bằng khoá riêng tư của bạn thông qua ES256. Xin lưu ý rằng JWS yêu cầu chữ ký phải ở định dạng nối R | S thô (64 byte cho P-256). Nếu sử dụng trực tiếp OpenSSL, bạn phải chuyển đổi chữ ký được mã hoá ASN.1 DER mặc định sang định dạng thô này.

Giao dịch trao đổi thành công được biểu thị bằng phản hồi 200 OK chứa mã thông báo. Nếu bạn sử dụng bằng chứng DPoP hợp lệ trong quá trình trao đổi, thì mã làm mới mà Google trả về sẽ được liên kết với khoá của bạn theo cơ chế DPoP, nhưng mã truy cập sẽ không được liên kết theo cơ chế DPoP. Mã truy cập sẽ giữ lại token_type của Bearer thay vì DPoP. Ngoài ra, Google sẽ trả về tiêu đề HTTP DPoP-Nonce trong phản hồi. Ứng dụng của bạn phải lưu trữ nonce này vào bộ nhớ đệm và đưa nonce này vào thông báo xác nhận quyền sở hữu nonce của bằng chứng DPoP trong các yêu cầu tiếp theo (chẳng hạn như khi đổi mã làm mới lấy mã truy cập mới hoặc khi gọi các API được DPoP bảo vệ). Bằng cách sử dụng số chỉ dùng một lần được cấp sớm này, bạn có thể tránh được lỗi khứ hồi bổ sung (use_dpop_nonce) trong yêu cầu tiếp theo.

Bạn phải cung cấp bằng chứng DPoP cho các yêu cầu trao đổi mã thông báo được thực hiện bằng mã làm mới liên kết với DPoP.

Lỗi trao đổi xảy ra nếu thiếu tiêu đề DPoP khi dự kiến, không hợp lệ hoặc nếu bằng chứng sử dụng khoá khác với khoá liên kết với mã thông báo. Trong những trường hợp này, máy chủ sẽ trả về lỗi 400 Bad Request. Nếu bằng chứng DPoP có các thông báo xác nhận quyền sở hữu htm hoặc htu không khớp, iat đã hết hạn, jti được sử dụng lại hoặc chữ ký không hợp lệ, thì Google sẽ trả về mã lỗi invalid_dpop_proof. Nếu cần có số chỉ dùng một lần DPoP, chẳng hạn như trong quá trình trao đổi mã làm mới và bằng chứng DPoP thiếu thông báo xác nhận quyền sở hữu nonce hoặc giá trị số chỉ dùng một lần không được máy chủ chấp nhận (ví dụ: đã hết hạn, đã được sử dụng hoặc không chính xác), thì Google sẽ trả về mã lỗi use_dpop_nonce cùng với tiêu đề HTTP DPoP-Nonce chứa số chỉ dùng một lần mới mà bạn có thể sử dụng trong yêu cầu tiếp theo. Các lỗi khác có thể trả về invalid_grant.

Google phản hồi yêu cầu này bằng cách trả về một đối tượng JSON chứa mã truy cập ngắn hạn và mã làm mới.

Phản hồi chứa các trường sau:

Đoạn mã sau đây cho thấy tiêu đề phản hồi và nội dung phản hồi thành công mẫu khi sử dụng DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Bước 6: Kiểm tra xem người dùng đã cấp những phạm vi nào

Khi yêu cầu nhiều quyền (phạm vi), người dùng có thể không cấp cho ứng dụng của bạn quyền truy cập vào tất cả các quyền đó. Ứng dụng của bạn phải xác minh những phạm vi thực sự được cấp và xử lý linh hoạt các trường hợp một số quyền bị từ chối, thường là bằng cách tắt các tính năng dựa vào những phạm vi bị từ chối đó.

Tuy nhiên, vẫn có một số ngoại lệ. Các ứng dụng Google Workspace Enterprise có quyền uỷ quyền trên toàn miền hoặc các ứng dụng được đánh dấu là Đáng tin cậy sẽ bỏ qua màn hình xin phép cấp quyền truy cập chi tiết. Đối với những ứng dụng này, người dùng sẽ không thấy màn hình xin phép cấp quyền chi tiết. Thay vào đó, ứng dụng của bạn sẽ nhận được tất cả phạm vi được yêu cầu hoặc không nhận được phạm vi nào.

Để biết thêm thông tin chi tiết, hãy xem bài viết Cách xử lý các quyền truy cập chi tiết.

Để kiểm tra xem người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào một phạm vi cụ thể hay chưa, hãy kiểm tra trường scope trong phản hồi mã truy cập. Phạm vi truy cập được cấp bởi mã truy cập được biểu thị dưới dạng danh sách các chuỗi phân biệt chữ hoa chữ thường, được phân tách bằng dấu cách.

Ví dụ: phản hồi mã truy cập mẫu sau đây cho biết rằng người dùng đã cấp cho ứng dụng của bạn quyền truy cập vào hoạt động trên Drive chỉ có thể đọc và quyền truy cập vào các sự kiện trên Lịch:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Gọi API của Google

Sau khi ứng dụng của bạn nhận được mã truy cập, bạn có thể sử dụng mã này để thực hiện lệnh gọi đến một API của Google thay mặt cho một 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. Để thực hiện việc này, hãy thêm mã truy cập vào yêu cầu gửi đến API bằng cách thêm tham số truy vấn access_token hoặc giá trị Bearer của tiêu đề HTTP Authorization. Nếu có thể, bạn nên sử dụng tiêu đề HTTP vì 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 thư viện ứng dụng để thiết lập lệnh gọi đến API của Google (ví dụ: khi gọi API tệp Drive).

Bạn có thể dùng thử tất cả API của Google và xem phạm vi của các API đó tại OAuth 2.0 Playground.

Ví dụ về HTTP GET

Lệnh gọi đến điểm cuối drive.files (API Tệp trên Drive) bằng tiêu đề HTTP Authorization: Bearer có thể có dạng như sau. Lưu ý rằng bạn cần chỉ định mã 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à lệnh gọi đến cùng một API cho người dùng đã xác thực bằng tham số chuỗi truy vấn access_token:

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

Ví dụ về curl

Bạn có thể kiểm thử các lệnh này bằng ứng dụng dòng lệnh curl. Sau đây là ví dụ sử dụng lựa chọn tiêu đề HTTP (ưu tiên):

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

Hoặc, bạn có thể chọn tham số chuỗi truy vấn:

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

Làm mới mã truy cập

Mã truy cập sẽ hết hạn định kỳ và trở thành thông tin xác thực không hợp lệ cho một yêu cầu API có liên quan. Bạn có thể làm mới mã truy cập mà không cần nhắc người dùng cấp quyền (kể cả khi người dùng không có mặt) nếu bạn đã yêu cầu quyền truy cập khi không có mạng vào các phạm vi liên kết với mã thông báo.

Để làm mới mã truy cập, ứng dụng của bạn sẽ gửi một yêu cầu HTTPS POST đến máy chủ uỷ quyền của Google (https://oauth2.googleapis.com/token) có chứa các tham số sau trong phần nội dung yêu cầu:

Mặc dù việc sử dụng DPoP là không bắt buộc, nhưng bạn nên sử dụng để tăng cường bảo mật. Để sử dụng DPoP với mã làm mới, ứng dụng của bạn phải tạo một JWT bằng chứng DPoP mới, duy nhất cho mỗi yêu cầu đến điểm cuối mã thông báo. Bằng chứng này phải được ký bằng cùng một khoá riêng tư đã được dùng trong quá trình trao đổi mã uỷ quyền ban đầu. Ứng dụng của bạn thêm bằng chứng dưới dạng tiêu đề của yêu cầu HTTP.

Đoạn mã sau đây cho thấy một yêu cầu mẫu:

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

Để sử dụng DPoP với mã làm mới, bạn phải tạo một JWT bằng chứng DPoP mới, duy nhất cho yêu cầu. Hãy xem phần Tạo bằng chứng DPoP để biết hướng dẫn từng bước về cách tạo cặp khoá và tạo JWT.

Giao dịch trao đổi thành công được biểu thị bằng phản hồi 200 OK chứa mã truy cập mới. Khi sử dụng DPoP, token_type là Bearer. Phản hồi thành công xác nhận rằng bằng chứng DPoP cho mã làm mới đã được chấp nhận. Google cũng có thể trả về một tiêu đề HTTP DPoP-Nonce mới trong phản hồi; nếu được trả về, ứng dụng của bạn phải lưu số chỉ dùng một lần này vào bộ nhớ đệm và đưa số đó vào thông báo xác nhận quyền sở hữu nonce của bằng chứng DPoP trong các yêu cầu tiếp theo.

Lượt trao đổi không thành công xảy ra nếu tiêu đề DPoP bị thiếu, không hợp lệ hoặc sử dụng khoá không chính xác. Để biết thông tin chi tiết về các mã lỗi DPoP cụ thể và cách xử lý số chỉ dùng một lần, hãy xem phần Trao đổi không thành công.

Đoạn mã sau đây cho thấy tiêu đề phản hồi và nội dung phản hồi thành công mẫu khi sử dụng DPoP:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Xin lưu ý rằng có giới hạn về số lượng mã làm mới sẽ được cấp; một giới hạn cho mỗi tổ hợp ứng dụng khách/người dùng và một giới hạn khác cho mỗi người dùng trên tất cả ứng dụng khách. Bạn nên lưu mã làm mới trong bộ nhớ dài hạn và tiếp tục sử dụng mã đó miễn là mã vẫn còn hiệu lực. Nếu ứng dụng của bạn yêu cầu quá nhiều mã làm mới, thì ứng dụng có thể đạt đến các giới hạn này. Trong trường hợp đó, các mã làm mới cũ hơn sẽ ngừng hoạt động.

Thu hồi mã thông báo

Trong một số trường hợp, người dùng có thể muốn thu hồi quyền truy cập đã cấp cho một ứng dụng. Người dùng có thể thu hồi quyền truy cập bằng cách truy cập vào phần Cài đặt tài khoản. Hãy xem phần Xoá quyền truy cập của trang web hoặc ứng dụng trong tài liệu hỗ trợ Các trang web và ứng dụng bên thứ ba có quyền truy cập vào tài khoản của bạn để biết thêm thông tin.

Ứng dụng cũng có thể thu hồi quyền truy cập được cấp cho ứng dụng đó theo phương thức lập trình. Việc thu hồi theo chương trình là rất quan trọng trong trường hợp người dùng huỷ đăng ký, xoá một ứng dụng hoặc tài nguyên API mà ứng dụng yêu cầu đã thay đổi đáng kể. Nói cách khác, một phần của quy trình xoá có thể bao gồm yêu cầu API để đảm bảo các quyền đã cấp trước đó cho ứng dụng sẽ bị xoá.

Để thu hồi mã thông báo theo phương thức lập trình, ứng dụng của bạn sẽ gửi một yêu cầu đến https://oauth2.googleapis.com/revoke và đưa mã thông báo vào làm tham số:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Mã thông báo có thể là mã truy cập hoặc mã làm mới. Nếu mã thông báo là mã truy cập và có mã làm mới tương ứng, thì mã làm mới cũng sẽ bị thu hồi.

Nếu yêu cầu thu hồi được xử lý thành công, thì mã trạng thái HTTP của phản hồi sẽ là 200. Đối với các điều kiện lỗi, mã trạng thái HTTP 400 sẽ được trả về cùng với mã lỗi.

Phương thức Redirect Method

Bảo vệ ứng dụng của bạn

Quyền truy cập theo thời gian

Quyền truy cập theo thời gian cho phép người dùng cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu của họ trong một khoảng thời gian có hạn để hoàn tất một hành động. Quyền truy cập theo thời gian được cung cấp trong một số sản phẩm của Google trong quy trình đồng ý, cho phép người dùng cấp quyền truy cập trong một khoảng thời gian giới hạn. Ví dụ: Data Portability API cho phép chuyển dữ liệu một lần.

Khi người dùng cấp cho ứng dụng của bạn quyền truy cập theo thời gian, mã làm mới sẽ hết hạn sau khoảng thời gian được chỉ định. Xin lưu ý rằng mã làm mới có thể bị vô hiệu sớm hơn trong một số trường hợp cụ thể; hãy xem các trường hợp này để biết thông tin chi tiết. Trường refresh_token_expires_in được trả về trong phản hồi trao đổi mã uỷ quyền thể hiện thời gian còn lại cho đến khi mã làm mới hết hạn trong những trường hợp như vậy.

Tài liệu đọc thêm

Phương pháp hay nhất hiện tại của IETF OAuth 2.0 cho ứng dụng gốc thiết lập nhiều phương pháp hay nhất được ghi lại tại đây.