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 có liên quan

OAuth 2.0 được tiêu chuẩn hoá theo RFC 6749. Bạn có thể xem tài liệu chi tiết tại https://oauth.net/2. Phương thức xác thực cơ bản qua HTTP được xác định trong mục 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ế (chẳng hạn như gói dữ liệu và thông tin chi tiết về ví), người dùng cuối (chủ sở hữu tài nguyên) cần 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à hạn chế như lưu trữ thông tin đăng nhập, xác thực bằng 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 những vấn đề này bằng cách giới thiệu một lớp uỷ quyền và do đó bảo mật cũng như hạn chế quyền 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 đăng nhập của người dùng cuối để truy cập vào các tài nguyên được bảo vệ (chẳng hạn 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 đăng nhập của GTAF. Sau đó, GTAF sẽ sử dụng mã truy cập để truy cập vào thông tin chi tiết về gói dữ liệu do DPA lưu trữ.

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

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

Mã truy cập

Mã truy cập là thông tin đăng nhập mà GTAF dùng để truy cập vào thông tin chi tiết về gói dữ liệu từ DPA của nhà mạng. Mã truy cập là một chuỗi đại diện cho một uỷ quyền được cấp cho GTAF. Chuỗi này thường không rõ ràng đối với GTAF. Mã thông báo đại diện cho các phạm vi và thời hạn truy cập cụ thể, do người dùng cuối cấp cho hãng vận chuyển và được DPA cũng như máy chủ OAuth của hãng vận chuyển 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 uỷ quyền khác nhau (ví dụ: tên người dùng và mật khẩu) bằng một mã duy nhất mà DPA hiểu được. Lớp trừu tượng này cho phép phát hành mã truy cập hạn chế hơn so với quyền uỷ quyền được dùng để lấy mã truy cập, cũng như loại bỏ nhu cầu của DPA trong việc tìm hiểu 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 các yêu cầu bảo mật của hãng vận chuyển. GTAF chỉ hỗ trợ mã truy cập thuộc loại người mang được xác định trong [RFC6750].

Xác thực ứng dụng

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

Các ứng dụng khách bí mật như GTAF (được cấp thông tin đăng nhập của ứng dụng khách) sẽ xác thực bằng máy chủ OAuth của hãng vận chuyển trong khi đưa ra yêu cầu đến điểm cuối của mã thông báo. Chế độ 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 đăng nhập của ứng dụng, 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 bộ thông tin đăng nhập của ứng dụng khách sẽ nhanh hơn đáng kể so với việc thu hồi toàn bộ bộ mã 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 đăng nhập định kỳ.

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

Khả năng xoay vòng thông tin đăng nhập của khách hàng là đặc biệt quan trọng. Máy chủ OAuth phải có khả năng hỗ trợ 2 cặp thông tin đăng nhập đồng thời trong quá trình xoay vòng và phải có khả năng vô hiệu hoá thông tin đăng nhập. Trong một quy trình thay đổi định kỳ thông tin xác thực thông thường:

Hãng vận chuyển tạo thông tin đăng nhập mới trên máy chủ OAuth và gửi thông tin đăng nhập đó cho Người quản lý tài khoản kỹ thuật của họ một cách an toàn.
Google kiểm thử thông tin đăng nhập mới và thay đổi cấu hình GTAF để sử dụng thông tin đăng nhập mới.
Google thông báo cho hãng vận chuyển rằng thông tin xác thực cũ có thể bị vô hiệu hoá.
Nhà mạng vô hiệu hoá 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

Máy chủ OAuth phải hỗ trợ được quy trình xoay vòng nêu 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ã uỷ quyền hoặc mã làm mới. Điểm cuối mã thông báo được dùng với mọi khoản uỷ quyền, ngoại trừ loại khoản uỷ 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 một điểm cuối mã thông báo:

Bạn nên cung cấp vị trí của điểm cuối mã thông báo trong tài liệu dịch vụ.
URI điểm cuối có thể bao gồm một thành phần truy vấn được định dạng "application/x-www-form-urlencoded" mà bạn phải giữ lại khi thêm các tham số truy vấn bổ sung. URI điểm cuối không được chứa thành phần phân đoạn.
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 đăng nhập văn bản thuần tuý (trong yêu cầu và phản hồi HTTP), nên máy chủ OAuth của hãng vận chuyển 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 "POST" HTTP khi đưa ra yêu cầu về mã truy cập.
Các tham số được gửi mà không có giá trị phải được coi là bị bỏ qua trong yêu cầu. Máy chủ OAuth phải bỏ qua các tham số yêu cầu không xác định. Bạn không được đưa các tham số yêu cầu và phản hồi nhiều lần.
GTAF chỉ hỗ trợ mã truy cập thuộc loại người mang.

Phạm vi mã truy cập

Các điểm cuối uỷ 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 tham số yêu cầu "scope". Đến lượt, máy chủ uỷ quyền sẽ sử dụng tham số phản hồi "scope" để thông báo cho ứng dụng khách về phạm vi của mã truy cập đã phát hành.

Giá trị của tham số phạm vi được biểu thị dưới dạng một danh sách các chuỗi có phân biệt chữ hoa chữ thường, được phân tách bằng dấu cách. 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 đó 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 được 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 bạn triển khai phạm vi, nhưng có 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.

Phát hành mã truy cập

Nếu yêu cầu mã truy cập do GTAF gửi là hợp lệ và được uỷ quyền, thì máy chủ OAuth sẽ cấp mã truy cập và mã làm mới (không bắt buộc). Nếu yêu cầu không xác thực được máy khách hoặc không hợp lệ, thì máy chủ OAuth sẽ trả về một 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ẽ phát hành 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 tham số sau vào phần nội dung của phản hồi HTTP có mã trạng thái 200 (OK):\

access_token: BẮT BUỘC. Mã truy cập do máy chủ OAuth phát hành. GTAF dự kiến điểm cuối mã thông báo sẽ trả về mã thông báo của người mang.
expires_in: BẮT BUỘC. Thời gian tồn tại của mã truy cập tính bằng giây. Ví dụ: giá trị "3600" cho biết 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ỏ qua, máy chủ OAuth sẽ cung cấp thời gian hết hạn bằng các phương tiện khác hoặc ghi lại giá trị mặc định.
token_type: BẮT BUỘC. Loại mã thông báo được phát hành. Để biết thêm thông tin về các loại mã thông báo, 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. Tại thời điểm viết bài này, GTAF chỉ hỗ trợ mã thông báo của người mang.
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ùng một quyền uỷ quyền.
scope: KHÔNG BẮT BUỘC, nếu được triển khai và giống với phạm vi mà GTAF yêu cầu; nếu không, bạn phải cung cấp.

Các tham số này được đưa vào phần nội dung 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 JavaScript Object Notation (JSON) bằng cách thêm từng tham số ở cấp cấu trúc cao nhất. Tên tham số và giá trị chuỗi được đưa vào dưới dạng chuỗi JSON. Các giá trị bằng 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ể thay đổi.

Máy chủ uỷ quyền PHẢI bao gồm trường tiêu đề phản hồi "Cache-Control" của HTTP có giá trị "no-store" trong mọi phản hồi chứa mã thông báo, thông tin đăng nhập hoặc thông tin nhạy cảm khác, cũng như trường tiêu đề phản hồi "Pragma" có giá trị "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 cần cân nhắc:

GTAF bỏ qua những tên giá trị không nhận dạng được 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 vẫn chưa được xác định.
GTAF không nên đưa ra 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ủ đó phát hành.

Phản hồi lỗi

Nếu yêu cầu uỷ quyền không thành công vì bất kỳ lý do nào, chẳng hạn như thiếu, không hợp lệ hoặc không khớp với URI chuyển hướng, hoặc nếu thiếu hoặc không hợp lệ mã nhận dạng ứng dụng, 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ừ phi có quy định khác) và phải bao gồm ít nhất một trong các tham số được liệt kê trong phần Phản hồi và mã lỗi.

Cấp quyền uỷ quyền trong GTAF

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

GTAF sử dụng loại cấp client_credentials. Trong loại cấp client_credentials, GTAF yêu cầu một mã thông báo bằng cách sử dụng yêu cầu HTTP POST và phương thức Xác thực cơ bản HTTP. Tất cả các yêu cầu đề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 mà không có chứng chỉ TLS hợp lệ. GTAF có thể truyền một phạm vi mã thông báo có thể định cấu hình và sẽ truyền một phạm vi trống nếu bạn không định cấu hình phạm vi nào.

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

Để biết thêm thông tin chi tiết về nhiều loại quyền truy cập, hãy xem mục 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ột 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 cho một DPA thực phải an toàn hơn nhiều so với mật khẩu ứng dụng trong ví dụ.

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

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

Sau đó, GTAF sẽ gửi yêu cầu HTTPS POST đến máy chủ OAuth bằng cách sử dụng thông tin xác thực này, loại cấp client_credentials và phạm vi đã định cấu hình. Ví dụ: yêu cầu của GTAF có dạng tương tự như yêu cầu do:

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

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

GTAF mong muốn nhận được phản hồi theo 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ã và phản hồi báo lỗi

Nếu yêu cầu uỷ quyền 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, thì 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ừ phi có quy định khác) và đưa một trong các tham số sau vào 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 yêu cầu máy chủ OAuth hỗ trợ các phản hồi lỗi sau:

Mã lỗi	Đáp	Lý do
HTTP 400	invalid_request	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 quyền), lặp lại một tham số, bao gồm nhiều thông tin đăng nhập, sử dụng nhiều cơ chế để xác thực bằng GTAF hoặc có định dạng không chính xác.
HTTP 401	invalid_client	Xác thực máy khách không thành công (ví dụ: máy khách không xác định, không có thông tin xác thực máy khách 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 (Không được phép) để cho biết các giao thức xác thực HTTP được hỗ trợ. Nếu ứng dụng cố gắng xác thực thông qua trường tiêu đề yêu cầu "Authorization", thì máy chủ OAuth phải phản hồi bằng mã trạng thái HTTP 401 (Không được uỷ quyền) và bao gồm trường tiêu đề phản hồi "WWW-Authenticate" 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 mục 5.2 của RFC 6749.

OAuth cho API Tác nhân gói dữ liệu Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.