Trang này được dịch bởi Cloud Translation API.

OAuth cho API Tác nhân gói dữ liệu

Tài liệu liên quan

OAuth 2.0 được chuẩn hoá theo tiêu chuẩn RFC 6749. Bạn có thể xem tài liệu chi tiết tại https://oauth.net/2. Xác thực HTTP cơ bản được xác định trong phần 2 của RFC 2617.

Tổng quan

Thông thường, để cấp cho các ứng dụng bên thứ ba quyền truy cập vào các tài nguyên bị hạn chế như thông tin chi tiết về gói dữ liệu và ví, người dùng cuối (chủ sở hữu tài nguyên) cần phải chia sẻ thông tin đăng nhập của mình với bên thứ ba. Điều này gây ra một số vấn đề và giới hạn, chẳng hạn như bộ nhớ thông tin xác thực, xác thực mật khẩu, quyền truy cập rộng rãi vào tài nguyên của người dùng cuối và rò rỉ mật khẩu, v.v. OAuth2.0 giải quyết các vấn đề này bằng cách giới thiệu một lớp ủy quyền, từ đó giới hạn và truy cập vào các tài nguyên được bảo vệ của người dùng cuối.

Thay vì sử dụng thông tin xác thực của người dùng cuối để truy cập vào tài nguyên được bảo vệ như thông tin chi tiết về gói dữ liệu, GTAF sẽ lấy mã truy cập. Mã thông báo truy cập được cấp cho GTAF thay mặt cho thông tin xác thực GTAF&39; Sau đó, GTAF sử dụng mã truy cập để truy cập thông tin chi tiết về gói dữ liệu do DPA lưu trữ.

Hình sau đây cung cấp dòng thông tin cấp cao:

Hình 1. Luồng OAuth trừu tượng.

Mã truy cập

Mã truy cập là thông tin xác thực mà GTAF sử dụng để truy cập thông tin chi tiết về gói dữ liệu từ DPA của nhà mạng. Mã thông báo truy cập là một chuỗi đại diện cho quá trình ủy quyền được cấp cho GTAF. Chuỗi này thường mờ với GTAF. Mã thông báo đại diện cho các phạm vi và thời lượng truy cập cụ thể, được người dùng cuối cấp cho nhà mạng, đồng thời được máy chủ OAuth của DPA và nhà mạng thực thi.

Mã truy cập cung cấp một lớp trừu tượng, thay thế các cấu trúc ủy quyền khác nhau (ví dụ: tên người dùng và mật khẩu) bằng một mã thông báo duy nhất do DPA hiểu được. Tính năng trừu tượng này cho phép việc phát hành mã thông báo truy cập có tính hạn chế cao hơn so với quyền cấp phép dùng để có được các thông báo đó, cũng như việc xoá các DPA cần hiểu rõ nhiều phương thức xác thực.

Mã truy cập có thể có nhiều định dạng, cấu trúc và phương thức sử dụng (ví dụ: thuộc tính mật mã) dựa trên yêu cầu bảo mật của nhà mạng. GTAF chỉ hỗ trợ mã thông báo truy cập loại trình mang được xác định trong [RFC6750].

Xác thực máy khách

GTAF hoạt động như một "ứng dụng bí mật" và có khả năng bảo vệ mật khẩu. GTAF hiện chỉ hỗ trợ xác thực HTTP cơ bản để xác thực bằng DPA. Mã nhận dạng khách hàng được mã hoá bằng thuật toán mã hoá &&tt;application/x-www-form-urlencoded" và giá trị đã mã hoá được dùng làm tên người dùng; mật khẩu được mã hoá bằng cùng một thuật toán và dùng làm mật khẩu.

Các ứng dụng bí mật, chẳng hạn như GTAF, được cấp thông tin đăng nhập ứng dụng, sẽ xác thực với máy chủ OAuth của nhà mạng trong khi gửi yêu cầu đến điểm cuối mã thông báo. Xác thực ứng dụng được dùng cho: \

Khôi phục từ một ứng dụng bị xâm nhập bằng cách vô hiệu hoá ứng dụng hoặc thay đổi thông tin xác thực, nhờ đó ngăn chặn kẻ tấn công lạm dụng mã làm mới bị đánh cắp. Việc thay đổi một nhóm thông tin đăng nhập của ứng dụng sẽ nhanh hơn đáng kể so với việc thu hồi toàn bộ tập hợp mã thông báo làm mới.
Triển khai các phương pháp hay nhất về quản lý xác thực, yêu cầu xoay vòng thông tin xác thực định kỳ.

GTAF sử dụng thông số "client_id" yêu cầu để xác định chính nó khi gửi yêu cầu đến điểm cuối mã thông báo.

Đặc biệt quan trọng là khả năng xoay vòng thông tin đăng nhập ứng dụng khách. Máy chủ OAuth phải có khả năng hỗ trợ hai cặp thông tin xác thực đồng thời trong quá trình xoay và phải có khả năng tắt thông tin xác thực. Trong một chu kỳ xác thực thông thường:

Nhà mạng di chuyển tạo thông tin xác thực mới trên máy chủ OAuth và cung cấp thông tin xác thực cho Người quản lý tài khoản kỹ thuật của họ một cách an toàn.
Google sẽ thử nghiệm thông tin xác thực mới và thay đổi cấu hình GTAF để sử dụng thông tin xác thực mới.
Google sẽ thông báo cho nhà mạng rằng thông tin đăng nhập cũ có thể đã bị vô hiệu hóa.
Nhà mạng sẽ vô hiệu hóa thông tin xác thực và thông báo cho Google
Google xác minh rằng thông tin đăng nhập cũ không còn hoạt động nữa

Máy chủ OAuth phải có khả năng hỗ trợ quá trình xoay ở trên.

Điểm cuối mã thông báo

GTAF sử dụng điểm cuối mã thông báo để lấy mã truy cập bằng cách trình bày mã cấp phép hoặc mã làm mới. Người dùng sẽ sử dụng điểm cuối mã thông báo với mọi cấp quyền, ngoại trừ loại cấp quyền ngầm (vì mã truy cập được phát hành trực tiếp).

Sau đây là một số điểm cần cân nhắc khi định cấu hình điểm cuối mã thông báo:

Bạn phải cung cấp vị trí của điểm cuối mã thông báo trong tài liệu về dịch vụ.
URI điểm cuối có thể bao gồm "application/x-www-form-urlencoded" thành phần truy vấn được định dạng phải được giữ lại khi thêm tham số truy vấn khác. URI điểm cuối không được bao gồm thành phần mảnh.
Vì các yêu cầu đến điểm cuối mã thông báo dẫn đến việc truyền thông tin xác thực văn bản rõ ràng (trong yêu cầu và phản hồi HTTP), máy chủ OAuth của nhà mạng phải sử dụng TLS để gửi yêu cầu đến điểm cuối mã thông báo.
GTAF sử dụng phương thức HTTP "POST" khi yêu cầu mã thông báo truy cập.
Bạn phải coi các thông số được gửi không có giá trị là bị bỏ qua khỏi yêu cầu. Máy chủ OAuth phải bỏ qua các tham số yêu cầu không nhận dạng được. Không được thêm các thông số yêu cầu và phản hồi nhiều lần.
GTAF chỉ hỗ trợ mã thông báo truy cập loại mang tải.

Phạm vi mã thông báo truy cập

Các điểm cuối ủy quyền và mã thông báo cho phép ứng dụng chỉ định phạm vi của yêu cầu truy cập bằng cách sử dụng "scope" thông số yêu cầu. Đổi lại, máy chủ uỷ quyền sử dụng thông số "scope" phản hồi để thông báo cho ứng dụng về phạm vi của mã thông báo truy cập đã cấp.

Giá trị của thông số phạm vi được biểu thị dưới dạng danh sách các chuỗi được phân tách bằng dấu cách, phân biệt chữ hoa chữ thường. Các chuỗi này do máy chủ uỷ quyền xác định. Nếu giá trị chứa nhiều chuỗi được phân tách bằng dấu cách, thì thứ tự của các chuỗi này không quan trọng và mỗi chuỗi sẽ thêm một phạm vi truy cập bổ sung vào phạm vi yêu cầu.

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF không yêu cầu triển khai phạm vi nhưng hỗ trợ tính năng này. Để biết thêm thông tin, hãy tham khảo Mục 3.3 của RFC 6749.

Cấp mã truy cập

Nếu yêu cầu mã thông báo truy cập do GTAF gửi là hợp lệ và được ủy quyền, thì máy chủ OAuth sẽ cấp mã thông báo truy cập và mã làm mới không bắt buộc. Nếu yêu cầu không thành công hoặc không hợp lệ, máy chủ OAuth sẽ trả về phản hồi lỗi như mô tả trong phần sau.

Phản hồi thành công

Khi GTAF gửi yêu cầu, máy chủ OAuth sẽ gửi một mã truy cập và mã làm mới không bắt buộc, đồng thời tạo phản hồi bằng cách thêm các thông số sau vào phần nội dung của phản hồi HTTP bằng mã trạng thái 200 (OK): \

access_token: PHẢI. Mã truy cập do máy chủ OAuth cấp. GTAF yêu cầu điểm cuối mã thông báo trả về một mã thông báo truy cập.
expiration_in: bắt buộc. Thời gian tồn tại của mã thông báo truy cập tính bằng giây. Ví dụ: giá trị "3600" biểu thị rằng mã truy cập sẽ hết hạn sau một giờ kể từ thời điểm phản hồi được tạo. Nếu bạn bỏ qua, máy chủ OAuth sẽ cung cấp thời gian hết hạn thông qua các phương tiện khác hoặc ghi lại giá trị mặc định.
token_type: PHẢI. Loại mã thông báo đã phát hành. Để biết thêm thông tin về các loại mã thông báo khác nhau, hãy tham khảo Mục 7.1 của RFC 6749. Giá trị này không phân biệt chữ hoa chữ thường. GTAF chỉ hỗ trợ mã thông báo truy cập tại thời điểm viết bài này.
refresh_token: KHÔNG BẮT BUỘC. Mã làm mới (có thể dùng để lấy mã truy cập mới) bằng cách sử dụng cùng một khoản uỷ quyền.
phạm vi: OPTIONAL, nếu được triển khai và giống với phạm vi của GTAF; nếu không thì bắt buộc.

Các thông số này được đưa vào phần nội dung của thực thể của phản hồi HTTP bằng cách sử dụng &"application/json" Các tham số được chuyển đổi tuần tự thành cấu trúc Ký hiệu đối tượng JavaScript (JSON) bằng cách thêm từng tham số ở cấp cấu trúc cao nhất. Tên thông số và giá trị chuỗi được đưa vào dưới dạng chuỗi JSON. Giá trị số được đưa vào dưới dạng số JSON. Thứ tự của các tham số không quan trọng và có thể khác nhau.

Máy chủ uỷ quyền PHẢI bao gồm trường HTTP "Cache-Control" tiêu đề phản hồi với giá trị là "no-store" trong bất kỳ phản hồi nào chứa mã thông báo, thông tin xác thực hoặc thông tin nhạy cảm khác, cũng như trường "Pragma" tiêu đề phản hồi có giá trị là "no-cache"

Ví dụ:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Sau đây là một số điểm quan trọng bạn cần xem xét:

GTAF bỏ qua các tên giá trị không được nhận dạng trong phản hồi.
Kích thước của mã thông báo và các giá trị khác nhận được từ máy chủ OAuth không xác định.
GTAF cần tránh giả định về kích thước giá trị. Máy chủ OAuth phải ghi lại kích thước của mọi giá trị mà máy chủ đưa ra.

Phản hồi lỗi

Nếu yêu cầu cấp phép không thành công vì bất kỳ lý do nào như thiếu URI chuyển hướng, không hợp lệ hoặc không khớp, hoặc nếu giá trị nhận dạng ứng dụng khách bị thiếu hoặc không hợp lệ, thì máy chủ OAuth sẽ phản hồi bằng mã trạng thái HTTP 400 (Yêu cầu không hợp lệ) (trừ khi được chỉ định khác) và phải bao gồm ít nhất một trong các thông số được liệt kê trong phần Phản hồi lỗi và Mã.

Cấp quyền trong GTAF

Cấp quyền là một thông tin đăng nhập thể hiện thông tin cấp phép của người dùng cuối (để truy cập vào tài nguyên được bảo vệ, chẳng hạn như thông tin số dư dữ liệu) mà GTAF sử dụng để lấy mã truy cập.

GTAF sử dụng loại cấp quyền client_credentials. Trong loại cấp quyền client_credentials, GTAF yêu cầu mã thông báo bằng yêu cầu HTTP POST và Xác thực cơ bản HTTP. Tất cả các yêu cầu được gửi qua TLS (tức là HTTPS) và GTAF không thể tích hợp với máy chủ OAuth nếu không có chứng chỉ TLS hợp lệ. GTAF có thể chuyển phạm vi mã thông báo có thể định cấu hình và sẽ chuyển phạm vi trống nếu không định cấu hình phạm vi.

GTAF dự kiến rằng mã truy cập được trả về cùng với giá trị "expiration_in" giá trị (thời gian tồn tại). Giá trị đếm_hết phải ít nhất là 900 giây và không được quá vài giờ. Yêu cầu mã thông báo mới không được làm cho các mã thông báo hiện có hết hạn sớm.

Để biết thêm thông tin về các loại cấp quyền, hãy xem phần 1.3 của RFC 6749.

Ví dụ về yêu cầu và phản hồi

Giả sử GTAF có cấu hình sau cho máy chủ OAuth:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

Lưu ý: Mật khẩu ứng dụng khách cho một DPA thực sự phải an toàn hơn nhiều so với mật khẩu hiển thị trong ví dụ.

Để tạo chuỗi uỷ quyền, mã ứng dụng khách <39;:' và mật khẩu sẽ được nối và mã hoá base64. Bạn có thể sao chép nội dung này trong giao diện dòng lệnh như sau:

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

Sau đó, GTAF sẽ tạo một yêu cầu POST HTTPS đến máy chủ OAuth bằng cách sử dụng các thông tin xác thực này, client_credentials Grants type và phạm vi được định cấu hình. Ví dụ: yêu cầu của GTAF\39; tương tự như yêu cầu được tạo bởi:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

Các tiêu đề mà GTAF sử dụng sẽ không khớp với các tiêu đề do curl gửi, mặc dù tiêu đề uỷ quyền sẽ giống hệt.

GTAF dự kiến sẽ có phản hồi dưới dạng:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

Sau đây là ví dụ về một phản hồi hợp lệ:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

Lưu ý: Phản hồi phải là JSON hợp lệ.

Mã phản hồi và mã lỗi

Nếu yêu cầu cấp phép từ GTAF không thành công vì bất kỳ lý do nào được nêu trong phần Phản hồi lỗi, máy chủ OAuth phải phản hồi bằng mã trạng thái HTTP 400 (Yêu cầu không hợp lệ) (trừ khi có quy định khác) và bao gồm một trong các tham số sau cùng với phản hồi:

Ví dụ: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF dự kiến máy chủ OAuth sẽ hỗ trợ các phản hồi lỗi sau:

Mã lỗi	Đáp	Lý do
HTTP 400	yêu_cầu_không_hợp_lệ	Yêu cầu thiếu một tham số bắt buộc, bao gồm một giá trị tham số không được hỗ trợ (ngoài loại cấp), lặp lại một tham số, bao gồm nhiều thông tin xác thực, sử dụng nhiều cơ chế để xác thực bằng GTAF, hoặc có định dạng không đúng.
HTTP 401	client_client không hợp lệ	Xác thực ứng dụng không thành công (ví dụ: ứng dụng không xác định, không có xác thực ứng dụng hoặc phương thức xác thực không được hỗ trợ). Máy chủ OAuth có thể trả về mã trạng thái HTTP 401 (Chưa được uỷ quyền) để cho biết lược đồ xác thực HTTP nào được hỗ trợ. Nếu ứng dụng khách đã xác thực thông qua trường "ủy quyền" tiêu đề yêu cầu, máy chủ OAuth phải phản hồi bằng mã trạng thái HTTP 401 (Chưa được uỷ quyền) và bao gồm trường "WWW-Authentication" tiêu đề phản hồi khớp với lược đồ xác thực mà ứng dụng sử dụng.
HTTP 500	Lỗi máy chủ OAuth

Để biết thông tin chi tiết về các phản hồi khác có thể dùng để gỡ lỗi, hãy tham khảo phần 5.2 của RFC 6749.