Tổng quan về chính sách JWS và JWT

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Chủ đề này cung cấp thông tin chung về JWT (Mã thông báo cho trang web theo chuẩn JSON) và JWS (Chữ ký cho trang web theo chuẩn JSON) cũng như các chính sách JWS/JWT của Apigee mà nhà phát triển proxy Apigee có thể quan tâm.

Giới thiệu

Cả JWS và JWT đều thường được dùng để chia sẻ các yêu cầu hoặc khẳng định giữa các ứng dụng được kết nối. Các chính sách JWS/JWT cho phép các proxy API Edge:

  • Tạo một JWT đã ký hoặc JWS.
  • Xác minh một JWT hoặc JWS đã ký và các khai báo trong JWS/JWT.
  • Giải mã một JWT hoặc JWS đã ký mà không xác thực chữ ký.

Trong hai trường hợp sau, chính sách này cũng đặt các biến cho phép các chính sách bổ sung hoặc chính các dịch vụ phụ trợ kiểm tra các xác nhận đã xác thực và đưa ra quyết định dựa trên những xác nhận đó.

Khi sử dụng chính sách Xác minh JWS/JWT, một JWS/JWT không hợp lệ sẽ bị từ chối và dẫn đến điều kiện lỗi. Tương tự, khi sử dụng chính sách Giải mã JWS/JWT, một JWS/JWT bị lỗi sẽ dẫn đến điều kiện lỗi.

Video

Xem một video ngắn để biết thông tin giới thiệu nhanh về JWT. Mặc dù video này dành riêng cho việc tạo JWT, nhưng nhiều khái niệm cũng tương tự đối với JWS.

Đây là một video ngắn giúp bạn tìm hiểu thêm về cấu trúc JWT.

Trường hợp sử dụng

Bạn có thể sử dụng các chính sách JWS/JWT để:

  • Tạo JWS/JWT mới ở một trong hai phía của proxy hoặc điểm cuối đích của một proxy Edge. Ví dụ: bạn có thể tạo một quy trình yêu cầu uỷ quyền tạo ra JWS/JWT và trả về cho một ứng dụng khách. Hoặc, bạn có thể thiết kế một proxy để tạo JWS/JWT trên luồng yêu cầu mục tiêu và đính kèm vào yêu cầu được gửi đến mục tiêu. Sau đó, những xác nhận quyền sở hữu đó sẽ có sẵn để cho phép các dịch vụ phụ trợ áp dụng thêm quy trình bảo mật.
  • Xác minh và trích xuất các xác nhận quyền sở hữu từ JWS/JWT nhận được từ các yêu cầu đến của ứng dụng, từ các phản hồi của dịch vụ đích, từ các phản hồi của chính sách Lệnh gọi dịch vụ hoặc từ các nguồn khác. Edge sẽ xác minh chữ ký trên JWS/JWT, cho dù JWS/JWT do bên thứ ba hay chính Edge tạo, bằng cách sử dụng thuật toán RSA hoặc HMAC.
  • Giải mã JWS/JWT. Việc giải mã hữu ích nhất khi được dùng cùng với chính sách Xác minh JWS/JWT, khi bạn phải biết giá trị của một khai báo (JWT) hoặc tiêu đề (JWS/JWT) trong JWS/JWT trước khi xác minh JWS/JWT.

Các phần của JWS/JWT

Một JWS/JWT đã ký mã hoá thông tin thành 3 phần được phân tách bằng dấu chấm: tiêu đề, phần dữ liệu thực tế và chữ ký:

header.payload.signature
  • Chính sách Tạo JWS/JWT sẽ tạo cả 3 phần.
  • Chính sách Xác minh JWS/JWT sẽ kiểm tra cả 3 phần.
  • Chính sách Giải mã JWS/JWT chỉ kiểm tra tiêu đề và phần dữ liệu thực tế.

JWS cũng hỗ trợ định dạng độc lập, tức là định dạng bỏ qua tải trọng trong JWS:

header..signature

Với JWS tách biệt, tải trọng được gửi riêng với JWS. Bạn sử dụng phần tử <DetachedContent> của chính sách Xác minh JWS để chỉ định tải trọng JWS thô, chưa được mã hoá. Sau đó, chính sách Xác minh JWS sẽ xác minh JWS bằng cách sử dụng tiêu đề và chữ ký trong JWS cũng như tải trọng do phần tử <DetachedContent> chỉ định.

Để tìm hiểu thêm về mã thông báo cũng như cách mã hoá và ký mã thông báo, hãy xem:

Sự khác biệt giữa JWS và JWT

Bạn có thể sử dụng JWT hoặc JWS để chia sẻ các yêu cầu hoặc khẳng định giữa các ứng dụng được kết nối. Điểm khác biệt chính giữa hai loại này là cách biểu thị tải trọng:

  • JWT
    • Tải trọng luôn là một đối tượng JSON
    • Phần dữ liệu thực tế luôn được đính kèm vào JWT
    • Tiêu đề typ của mã thông báo luôn được đặt thành JWT
  • JWS
    • Tải trọng có thể được biểu thị bằng bất kỳ định dạng nào, chẳng hạn như đối tượng JSON, luồng byte, luồng octet và các định dạng khác
    • Bạn không bắt buộc phải đính kèm tải trọng vào JWS

Vì định dạng JWT luôn sử dụng một đối tượng JSON để biểu thị tải trọng, nên các chính sách Tạo JWT và Xác minh JWT của Edge có sẵn tính năng hỗ trợ để xử lý các Tên khai báo đã đăng ký phổ biến, chẳng hạn như aud, iss, sub và những tên khác. Điều đó có nghĩa là bạn có thể sử dụng các phần tử của chính sách Tạo JWT để đặt các xác nhận quyền sở hữu này trong tải trọng và các phần tử của chính sách Xác minh JWT để xác minh các giá trị của chúng. Hãy xem phần Registered Claim Names (Tên khai báo đã đăng ký) trong quy cách JWT để biết thêm thông tin.

Ngoài việc hỗ trợ một số Tên yêu cầu đã đăng ký, chính sách Tạo JWT còn hỗ trợ trực tiếp việc thêm các yêu cầu có tên tuỳ ý vào JWT. Mỗi câu lệnh là một cặp tên/giá trị đơn giản, trong đó giá trị có thể thuộc loại số, boolean, chuỗi, bản đồ hoặc mảng.

Vì JWS có thể sử dụng mọi kiểu biểu thị dữ liệu cho tải trọng, nên bạn không thể thêm các khai báo vào tải trọng. Chính sách Tạo JWS có hỗ trợ việc thêm các khai báo có tên tuỳ ý vào tiêu đề của JWS. Ngoài ra, các chính sách JWS hỗ trợ tải trọng tách biệt, trong đó JWS bỏ qua tải trọng. Tải trọng tách biệt cho phép bạn gửi JWS và tải trọng riêng biệt và được yêu cầu theo một số tiêu chuẩn bảo mật.

Ngăn chặn việc chèn mẫu khi sử dụng JWS và JWT

Để ngăn chặn việc tiết lộ dữ liệu trái phép, hãy làm theo các nguyên tắc sau khi sử dụng chính sách GenerateJWT hoặc GenerateJWS:

  • Tránh tham chiếu trực tiếp đến hoạt động đầu vào của người dùng: Đừng bao giờ sử dụng thông tin đầu vào không đáng tin cậy (chẳng hạn như request.queryparam.* hoặc request.header.*) trực tiếp trong một thuộc tính ref hỗ trợ việc tạo mẫu.
  • Vệ sinh dữ liệu đầu vào: Nếu bạn phải sử dụng dữ liệu bên ngoài trong một JWT/JWS, trước tiên, hãy sử dụng chính sách AssignMessage để loại bỏ mọi dấu ngoặc nhọn ({ }) hoặc các ký tự mẫu khác khỏi dữ liệu đầu vào trước khi tham chiếu đến dữ liệu đó.
  • Sử dụng các câu lệnh rõ ràng cho chuỗi: Đối với các câu lệnh chuỗi đơn giản, hãy tránh type="map". Việc sử dụng type="string" mặc định sẽ ngăn việc tạo mẫu ngầm cho giá trị được tham chiếu.
  • Lưu ý về sự không nhất quán trong hành vi giữa các chính sách xác minh và tạo: Các chính sách tạo JWS và JWT hoạt động khác với các chính sách xác minh liên quan đến việc tạo mẫu.

Giới thiệu về thuật toán chữ ký

Các chính sách Xác minh JWS/JWT và Tạo JWS/JWT hỗ trợ các thuật toán RSA, RSASSA-PSS, ECDSA và HMAC, sử dụng tổng kiểm tra SHA2 có độ dài bit là 256, 384 hoặc 512. Chính sách Giải mã JWS/JWT hoạt động bất kể thuật toán nào được dùng để ký JWS/JWT.

Thuật toán HMAC

Thuật toán HMAC dựa vào một khoá bí mật dùng chung (còn gọi là khoá bí mật) để tạo chữ ký (còn gọi là ký JWS/JWT) và để xác minh chữ ký.

Độ dài tối thiểu của khoá bí mật phụ thuộc vào độ mạnh của bit trong thuật toán:

  • HS256: Độ dài khoá tối thiểu là 32 byte
  • HS386: Độ dài khoá tối thiểu là 48 byte
  • HS512: Độ dài khoá tối thiểu là 64 byte

Thuật toán RSA

Thuật toán RSA sử dụng một cặp khoá công khai/riêng tư cho chữ ký mã hoá. Với chữ ký RSA, bên ký sẽ dùng khoá riêng tư RSA để ký JWS/JWT, còn bên xác minh sẽ dùng khoá công khai RSA trùng khớp để xác minh chữ ký trên JWS/JWT. Không có yêu cầu nào về kích thước đối với các khoá.

Thuật toán RSASSA-PSS

Thuật toán RSASSA-PSS là phiên bản cập nhật của thuật toán RSA. Giống như RSS, RSASSA-PSS sử dụng cặp khoá công khai/riêng tư RSA cho chữ ký mã hoá. Định dạng của khoá giống như đối với RSS. Bên ký sử dụng khoá riêng tư để ký JWS/JWT, còn bên xác minh sử dụng khoá công khai phù hợp để xác minh chữ ký trên JWS/JWT. Không có yêu cầu về kích thước đối với các khoá.

Thuật toán ECDSA

Thuật toán Giải thuật ký số dựa trên đường cong Elliptic (ECDSA) là một thuật toán mật mã học đường cong elip với đường cong P-256, P-384 và P-521. Khi bạn sử dụng thuật toán ECDSA, thuật toán sẽ xác định loại khoá công khai và khoá riêng tư mà bạn phải chỉ định:

Thuật toán Đường cong Yêu cầu chính
ES256 P-256 Khoá được tạo từ đường cong P-256 (còn gọi là secp256r1 hoặc prime256v1)
ES384 P-384 Khoá được tạo từ đường cong P-384 (còn gọi là secp384r1)
ES512 P-521 Khoá được tạo từ đường cong P-521 (còn gọi là secp521r1)

Thuật toán mã hoá khoá

Các chính sách JWS/JWT hỗ trợ tất cả các thuật toán mã hoá khoá mà OpenSSL hỗ trợ.

Sử dụng một Nhóm khoá web JSON (JWKS) để xác minh JWS/JWT

Khi xác minh JWS/JWT đã ký, bạn cần cung cấp khoá công khai được liên kết với khoá riêng tư dùng để ký mã thông báo. Bạn có hai lựa chọn để cung cấp khoá công khai cho các chính sách xác minh JWS/JWT:

  • sử dụng giá trị khoá công khai thực tế (thường được cung cấp trong một biến luồng), hoặc
  • sử dụng khoá công khai được bao bọc trong JWKS.

Giới thiệu về JWKS

JWKS là một cấu trúc JSON biểu thị một tập hợp các Khoá web JSON (JWK). JWK là một cấu trúc dữ liệu JSON biểu thị một khoá mã hoá. JWK và JWKS được mô tả trong RFC7517. Xem các ví dụ về JKWS trong Phụ lục A. Ví dụ về Bộ khoá web JSON

Cấu trúc JWKS

RFC7517 mô tả các phần tử khoá JWKS cho từng loại khoá, chẳng hạn như "RSA" hoặc "EC". Ví dụ: tuỳ thuộc vào loại khoá, các tham số này có thể bao gồm:

  • kty – Loại khoá, chẳng hạn như "RSA" hoặc "EC".
  • kid (mã khoá) – Có thể là giá trị tuỳ ý (không có giá trị trùng lặp trong một bộ khoá). Nếu JWT đầu vào có một mã khoá có trong bộ JWKS, thì chính sách sẽ sử dụng khoá công khai chính xác để xác minh chữ ký JWS/JWT.

Sau đây là ví dụ về các phần tử không bắt buộc và giá trị của các phần tử đó:

  • alg – Thuật toán khoá. Khoá này phải khớp với thuật toán ký trong JWS/JWT.
  • use – Nếu có, phải là sig.

JWKS sau đây bao gồm các phần tử và giá trị bắt buộc và sẽ hợp lệ trên Edge (từ https://www.googleapis.com/oauth2/v3/certs):

{
   "keys":[
      {
         "kty":"RSA",
         "alg":"RS256",
         "use":"sig",
         "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
         "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
         "e":"AQAB"
      },
      {
          "kty":"EC",
          "alg":"ES256",
          "use":"enc",
          "kid":"k05TUSt7-V7KDjCq0_N"
          "crv":"P-256",
          "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
          "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
      }
   ]
}

Thiết kế proxy để sử dụng JWKS

Khi nhận được JWS/JWT từ một đơn vị phát hành, đơn vị phát hành thường chèn một Mã khoá (hoặc kid) vào tiêu đề JWS/JWT. Khoá này cho người nhận JWS/JWT biết cách tìm khoá công khai hoặc khoá bí mật cần thiết để xác minh chữ ký trên JWS/JWT đã ký.

Ví dụ: giả sử một tổ chức phát hành ký một JWT bằng khoá riêng tư. "Key ID" (Mã khoá) xác định khoá công khai khớp để dùng xác minh JWT. Danh sách khoá công khai thường có tại một số điểm cuối phổ biến, ví dụ: https://www.googleapis.com/oauth2/v3/certs.

Đây là trình tự cơ bản mà Edge (hoặc bất kỳ nền tảng nào hoạt động với JWKS) cần thực hiện để hoạt động với JWS/JWT có JWKS:

  1. Kiểm tra tiêu đề JWS/JWT để tìm Mã khoá (kid).
  2. Kiểm tra tiêu đề JWS/JWT để tìm thuật toán ký (alg), chẳng hạn như RS256.
  3. Truy xuất danh sách khoá và mã nhận dạng từ JWKS của điểm cuối đã biết cho một tổ chức phát hành nhất định.
  4. Trích xuất khoá công khai từ danh sách khoá có mã nhận dạng khoá được ghi chú trong tiêu đề JWS/JWT và có thuật toán phù hợp, nếu khoá JWKS chỉ định thuật toán.
  5. Sử dụng khoá công khai đó để xác minh chữ ký trên JWS/JWT.

Là nhà phát triển proxy API Edge, bạn cần làm như sau để thực hiện quy trình xác minh JWS/JWT:

  1. Truy xuất danh sách khoá và mã nhận dạng từ điểm cuối đã biết của một tổ chức phát hành cụ thể. Bạn có thể sử dụng chính sách Chú thích dịch vụ cho bước này.
  2. Trong chính sách Xác minh JWS/JWT, hãy chỉ định vị trí của JWS/JWT trong phần tử <Source> và tải trọng JWKS trong phần tử <PublicKey/JWKS>. Ví dụ: đối với chính sách VerifyJWT: 
    <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS ref="public.jwks"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

Chính sách Xác minh JWT sẽ thực hiện mọi thao tác khác:

  • Nếu không tìm thấy khoá có Mã khoá khớp với Mã khoá (kid) được xác nhận trong JWT trong JWKS, thì chính sách Xác minh JWT sẽ gửi lỗi và không xác thực JWT.
  • Nếu JWT đến không có mã khoá (kid) trong tiêu đề, thì không thể thực hiện việc ánh xạ keyid-to-verification-key này.

Là nhà thiết kế proxy, bạn chịu trách nhiệm xác định khoá cần sử dụng; trong một số trường hợp, đây có thể là một khoá cố định, được mã hoá cứng.