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
Nội dung
Xác minh chữ ký trên JWT nhận được từ các ứng dụng hoặc hệ thống khác. Chính sách này cũng trích xuất các khai báo thành các biến ngữ cảnh để các chính sách hoặc điều kiện tiếp theo có thể kiểm tra các giá trị đó để đưa ra quyết định uỷ quyền hoặc định tuyến. Hãy xem bài viết Tổng quan về chính sách JWS và JWT để biết thông tin giới thiệu chi tiết.
Khi chính sách này thực thi, Edge sẽ xác minh chữ ký của JWT và xác minh rằng JWT hợp lệ theo thời gian hết hạn và thời gian không được phép trước đó nếu có. Chính sách này cũng có thể xác minh các giá trị của các khai báo cụ thể trên JWT (không bắt buộc), chẳng hạn như chủ đề, tổ chức phát hành, đối tượng hoặc giá trị của các khai báo bổ sung.
Nếu JWT được xác minh và hợp lệ, thì tất cả các xác nhận quyền sở hữu có trong JWT sẽ được trích xuất vào các biến ngữ cảnh để các chính sách hoặc điều kiện tiếp theo sử dụng và yêu cầu được phép tiếp tục. Nếu không xác minh được chữ ký JWT hoặc nếu JWT không hợp lệ do một trong các dấu thời gian, thì mọi quy trình xử lý sẽ dừng lại và một lỗi sẽ được trả về trong phản hồi.
Để tìm hiểu về các phần của JWT và cách mã hoá cũng như ký các phần đó, hãy tham khảo RFC7519.
Video
Xem một video ngắn để tìm hiểu cách xác minh chữ ký trên JWT.
Mẫu
Xác minh JWT được ký bằng thuật toán HS256
Chính sách mẫu này xác minh một JWT được ký bằng thuật toán mã hoá HS256, HMAC bằng tổng kiểm tra SHA-256. JWT được truyền trong yêu cầu proxy bằng cách sử dụng một tham số biểu mẫu có tên là jwt. Khoá này nằm trong một biến có tên là private.secretkey.
Hãy xem video ở trên để biết ví dụ đầy đủ, bao gồm cả cách đưa ra yêu cầu đối với chính sách.
Cấu hình chính sách bao gồm thông tin mà Edge cần để giải mã và đánh giá JWT, chẳng hạn như vị trí tìm JWT (trong một biến luồng được chỉ định trong phần tử Nguồn), thuật toán ký bắt buộc, vị trí tìm khoá bí mật (được lưu trữ trong một biến luồng Edge, có thể đã được truy xuất từ Edge KVM, chẳng hạn), và một tập hợp các khai báo bắt buộc và giá trị của chúng.
<VerifyJWT name="JWT-Verify-HS256">
<DisplayName>JWT Verify HS256</DisplayName>
<Algorithm>HS256</Algorithm>
<Source>request.formparam.jwt</Source>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<SecretKey encoding="base64">
<Value ref="private.secretkey"/>
</SecretKey>
<Subject>monty-pythons-flying-circus</Subject>
<Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
<Audience>fans</Audience>
<AdditionalClaims>
<Claim name="show">And now for something completely different.</Claim>
</AdditionalClaims>
</VerifyJWT>Chính sách này ghi đầu ra vào các biến ngữ cảnh để các chính sách hoặc điều kiện tiếp theo trong proxy API có thể kiểm tra những giá trị đó. Hãy xem phần Biến luồng để biết danh sách các biến do chính sách này đặt.
Xác minh JWT được ký bằng thuật toán RS256
Chính sách mẫu này xác minh một JWT được ký bằng thuật toán RS256. Để xác minh, bạn cần cung cấp khoá công khai. JWT được truyền trong yêu cầu proxy bằng cách sử dụng một tham số biểu mẫu có tên là jwt. Khoá công khai nằm trong một biến có tên là public.publickey.
Hãy xem video ở trên để biết ví dụ đầy đủ, bao gồm cả cách đưa ra yêu cầu đối với chính sách.
Hãy xem phần Tài liệu tham khảo về phần tử để biết thông tin chi tiết về các yêu cầu và lựa chọn cho từng phần tử trong chính sách mẫu này.
<VerifyJWT name="JWT-Verify-RS256">
<Algorithm>RS256</Algorithm>
<Source>request.formparam.jwt</Source>
<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
<PublicKey>
<Value ref="public.publickey"/>
</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>Đối với cấu hình ở trên, một JWT có tiêu đề này …
{
"typ" : "JWT",
"alg" : "RS256"
}Và tải trọng này…
{
"sub" : "apigee-seattle-hatrack-montage",
"iss" : "urn://apigee-edge-JWT-policy-test",
"aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
"show": "And now for something completely different."
}… sẽ được coi là hợp lệ nếu chữ ký có thể được xác minh bằng khoá công khai đã cung cấp.
Một JWT có cùng tiêu đề nhưng có phần dữ liệu thực tế này …
{
"sub" : "monty-pythons-flying-circus",
"iss" : "urn://apigee-edge-JWT-policy-test",
"aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
"show": "And now for something completely different."
}… sẽ được xác định là không hợp lệ, ngay cả khi chữ ký có thể được xác minh, vì yêu cầu "sub" có trong JWT không khớp với giá trị bắt buộc của phần tử "Subject" như được chỉ định trong cấu hình chính sách.
Chính sách này ghi đầu ra vào các biến ngữ cảnh để các chính sách hoặc điều kiện tiếp theo trong proxy API có thể kiểm tra những giá trị đó. Hãy xem phần Biến luồng để biết danh sách các biến do chính sách này đặt.
Thiết lập các phần tử chính
Các phần tử mà bạn dùng để chỉ định khoá dùng để xác minh JWT phụ thuộc vào thuật toán đã chọn, như minh hoạ trong bảng sau:
| Thuật toán | Các yếu tố chính | |
|---|---|---|
| HS* |
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.secretkey"/> </SecretKey> |
|
| RS*, ES*, PS* | <PublicKey> <Value ref="rsa_public_key_or_value"/> </PublicKey> hoặc: <PublicKey> <Certificate ref="signed_cert_val_ref"/> </PublicKey> hoặc: <PublicKey> <JWKS ref="jwks_val_or_ref"/> </PublicKey> |
|
| *Để biết thêm về các yêu cầu chính, hãy xem phần Giới thiệu về các thuật toán mã hoá chữ ký. | ||
Tài liệu tham khảo về phần tử
Tài liệu tham khảo về chính sách này mô tả các phần tử và thuộc tính của chính sách Xác minh JWT.
Lưu ý: Cấu hình sẽ khác nhau đôi chút tuỳ thuộc vào thuật toán mã hoá mà bạn sử dụng. Hãy tham khảo phần Mẫu để xem các ví dụ minh hoạ cấu hình cho những trường hợp sử dụng cụ thể.
Các thuộc tính áp dụng cho phần tử cấp cao nhất
<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">
Các thuộc tính sau đây là thuộc tính chung của tất cả các phần tử chính của chính sách.
| Thuộc tính | Nội dung mô tả | Mặc định | Sự hiện diện |
|---|---|---|---|
| tên |
Tên nội bộ của chính sách. Bạn chỉ có thể dùng các ký tự sau trong tên:
A-Z0-9._\-$ %. Tuy nhiên, giao diện người dùng quản lý Edge sẽ áp dụng thêm các hạn chế, chẳng hạn như tự động xoá các ký tự không phải là chữ và số.
Bạn có thể tuỳ ý sử dụng phần tử |
Không áp dụng | Bắt buộc |
| continueOnError |
Đặt thành false để trả về lỗi khi một chính sách không thành công. Đây là hành vi dự kiến đối với hầu hết các chính sách.
Đặt thành |
false | Không bắt buộc |
| đang bật |
Đặt thành true để thực thi chính sách.
Đặt thành |
true | Không bắt buộc |
| không đồng bộ | Thuộc tính này không được dùng nữa. | false | Không được dùng nữa |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
Sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng một tên khác bằng ngôn ngữ tự nhiên.
| Mặc định | Nếu bạn bỏ qua phần tử này, giá trị của thuộc tính tên của chính sách sẽ được sử dụng. |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi |
<Algorithm>
<Algorithm>HS256</Algorithm>
Chỉ định thuật toán mã hoá để ký mã thông báo. Các thuật toán RS*/PS*/ES* sử dụng một cặp khoá công khai/bí mật, trong khi các thuật toán HS* sử dụng một khoá bí mật dùng chung. Xem thêm bài viết Giới thiệu về các thuật toán mã hoá chữ ký.
Bạn có thể chỉ định nhiều giá trị được phân tách bằng dấu phẩy. Ví dụ: "HS256, HS512" hoặc "RS256, PS256". Tuy nhiên, bạn không thể kết hợp các thuật toán HS* với bất kỳ thuật toán nào khác hoặc các thuật toán ES* với bất kỳ thuật toán nào khác vì chúng yêu cầu một loại khoá cụ thể. Bạn có thể kết hợp các thuật toán RS* và PS*.
| Mặc định | Không áp dụng |
| Sự hiện diện | Bắt buộc |
| Loại | Chuỗi giá trị được phân tách bằng dấu phẩy |
| Giá trị hợp lệ | HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 |
<Audience>
<Audience>audience-here</Audience> or: <Audience ref='variable-name-here'/>
Chính sách này xác minh rằng chế độ xác nhận đối tượng trong JWT khớp với giá trị được chỉ định trong cấu hình. Nếu không có kết quả trùng khớp, chính sách sẽ báo lỗi. Khai báo này xác định những người nhận mà JWT hướng đến. Đây là một trong những khai báo đã đăng ký được đề cập trong RFC7519.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi |
| Giá trị hợp lệ | Một biến luồng hoặc chuỗi xác định đối tượng. |
<AdditionalClaims/Claim>
<AdditionalClaims> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> </AdditionalClaims> or: <AdditionalClaims ref='claim_payload'/>
Xác thực rằng phần dữ liệu thực tế JWT chứa(các) khai báo bổ sung được chỉ định và các giá trị khai báo được xác nhận khớp với nhau.
Một giá trị nhận dạng bổ sung sử dụng tên không phải là một trong các tên giá trị nhận dạng JWT tiêu chuẩn, đã đăng ký. Giá trị của một yêu cầu bổ sung có thể là một chuỗi, số, boolean, bản đồ hoặc mảng. Bản đồ chỉ đơn giản là một tập hợp các cặp tên/giá trị. Bạn có thể chỉ định rõ ràng giá trị cho một khai báo thuộc bất kỳ loại nào trong số này trong cấu hình chính sách hoặc gián tiếp thông qua một tham chiếu đến biến luồng.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi, số, boolean hoặc bản đồ |
| Mảng | Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false |
| Giá trị hợp lệ | Mọi giá trị mà bạn muốn dùng cho một câu lệnh bổ sung. |
Phần tử <Claim> có các thuộc tính sau:
- name – (Bắt buộc) Tên của yêu cầu xác nhận quyền sở hữu.
- ref – (Không bắt buộc) Tên của một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của biến này làm yêu cầu. Nếu bạn chỉ định cả thuộc tính ref và giá trị khai báo rõ ràng, thì giá trị rõ ràng sẽ là giá trị mặc định và được dùng nếu biến luồng được tham chiếu không được phân giải.
- type – (Không bắt buộc) Một trong các loại: chuỗi (mặc định), số, boolean hoặc bản đồ
- array – (Không bắt buộc) Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false.
Khi bạn thêm phần tử <Claim>, tên của yêu cầu xác nhận quyền sở hữu sẽ được đặt tĩnh khi bạn định cấu hình chính sách. Ngoài ra, bạn có thể truyền một đối tượng JSON để chỉ định tên của các yêu cầu.
Vì đối tượng JSON được truyền dưới dạng một biến, nên tên của xác nhận quyền sở hữu được xác định trong thời gian chạy.
Ví dụ:
<AdditionalClaims ref='json_claims'/>
Trong đó, biến json_claims chứa một đối tượng JSON ở dạng:
{ "sub" : "person@example.com", "iss" : "urn://secure-issuer@example.com", "non-registered-claim" : { "This-is-a-thing" : 817, "https://example.com/foobar" : { "p": 42, "q": false } } }
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
Xác thực rằng tiêu đề JWT chứa(các) cặp tên/giá trị của thông tin bổ sung được chỉ định và các giá trị của thông tin được xác nhận khớp với nhau.
Một khai báo bổ sung sử dụng tên không phải là một trong các tên khai báo JWT tiêu chuẩn, đã đăng ký. Giá trị của một khai báo bổ sung có thể là một chuỗi, số, boolean, bản đồ hoặc mảng. Bản đồ chỉ đơn giản là một tập hợp các cặp tên/giá trị. Bạn có thể chỉ định rõ ràng giá trị cho một khai báo thuộc bất kỳ loại nào trong số này trong cấu hình chính sách hoặc gián tiếp thông qua một tham chiếu đến biến luồng.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại |
Chuỗi (mặc định), số, boolean hoặc bản đồ. Loại này mặc định là String nếu bạn không chỉ định loại nào. |
| Mảng | Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false |
| Giá trị hợp lệ | Mọi giá trị mà bạn muốn dùng cho một câu lệnh bổ sung. |
Phần tử <Claim> có các thuộc tính sau:
- name – (Bắt buộc) Tên của yêu cầu xác nhận quyền sở hữu.
- ref – (Không bắt buộc) Tên của một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của biến này làm yêu cầu. Nếu bạn chỉ định cả thuộc tính ref và giá trị khai báo rõ ràng, thì giá trị rõ ràng sẽ là giá trị mặc định và được dùng nếu biến luồng được tham chiếu không được phân giải.
- type – (Không bắt buộc) Một trong các loại: chuỗi (mặc định), số, boolean hoặc bản đồ
- array – (Không bắt buộc) Đặt thành true để cho biết liệu giá trị có phải là một mảng các loại hay không. Mặc định: false.
<CustomClaims>
Lưu ý: Hiện tại, phần tử CustomClaims sẽ được chèn khi bạn thêm chính sách GenerateJWT mới thông qua giao diện người dùng. Phần tử này không hoạt động và sẽ bị bỏ qua. Phần tử chính xác cần sử dụng thay thế là <AdditionalClaims>. Giao diện người dùng sẽ được cập nhật để chèn các phần tử chính xác vào thời điểm khác.
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
Xác minh rằng JWT có khai báo jti cụ thể. Khi giá trị văn bản và thuộc tính ref đều trống, chính sách sẽ tạo một jti chứa UUID ngẫu nhiên. Thông báo nhận dạng JWT (jti) là giá trị nhận dạng duy nhất cho JWT. Để biết thêm thông tin về jti, hãy tham khảo RFC7519.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi hoặc tham chiếu. |
| Giá trị hợp lệ | Một chuỗi hoặc tên của một biến luồng chứa mã nhận dạng. |
<IgnoreCriticalHeaders>
<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>
Đặt thành false nếu bạn muốn chính sách này gửi lỗi khi mọi tiêu đề được liệt kê trong tiêu đề crit của JWT không được liệt kê trong phần tử <KnownHeaders>.
Đặt thành true để khiến chính sách VerifyJWT bỏ qua tiêu đề crit.
Một lý do để đặt phần tử này thành true là nếu bạn đang ở trong môi trường kiểm thử và chưa sẵn sàng gây ra lỗi khi thiếu tiêu đề.
| Mặc định | false |
| Sự hiện diện | Không bắt buộc |
| Loại | Boolean |
| Giá trị hợp lệ | true hoặc false |
<IgnoreIssuedAt>
<IgnoreIssuedAt>true|false</IgnoreIssuedAt>
Đặt thành false (mặc định) nếu bạn muốn chính sách này gửi lỗi khi JWT chứa một yêu cầu iat (Được phát hành tại) chỉ định thời gian trong tương lai.
Đặt thành true để khiến chính sách bỏ qua iat trong quá trình xác minh.
| Mặc định | false |
| Sự hiện diện | Không bắt buộc |
| Loại | Boolean |
| Giá trị hợp lệ | true hoặc false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
Đặt thành false nếu bạn muốn chính sách này đưa ra lỗi khi không thể phân giải bất kỳ biến nào được tham chiếu mà bạn chỉ định trong chính sách. Đặt thành true để coi mọi biến không phân giải được là một chuỗi trống (rỗng).
| Mặc định | false |
| Sự hiện diện | Không bắt buộc |
| Loại | Boolean |
| Giá trị hợp lệ | true hoặc false |
<Issuer>
<Issuer ref='variable-name-here'/> <Issuer>issuer-string-here</Issuer>
Chính sách này xác minh rằng tổ chức phát hành trong JWT khớp với chuỗi được chỉ định trong phần tử cấu hình. Một khai báo xác định tổ chức phát hành JWT. Đây là một trong những tập hợp các khai báo đã đăng ký được đề cập trong RFC7519.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi hoặc tham chiếu |
| Giá trị hợp lệ | Bất kỳ |
<KnownHeaders>
<KnownHeaders>a,b,c</KnownHeaders> or: <KnownHeaders ref=’variable_containing_headers’/>
Chính sách GenerateJWT sử dụng phần tử <CriticalHeaders> để điền tiêu đề crit trong JWT. Ví dụ:
{
“typ: “...”,
“alg” : “...”,
“crit” : [ “a”, “b”, “c” ],
}Chính sách VerifyJWT sẽ kiểm tra tiêu đề crit trong JWT (nếu có) và đối với mỗi tiêu đề được liệt kê, chính sách này sẽ kiểm tra để đảm bảo rằng phần tử <KnownHeaders> cũng liệt kê tiêu đề đó. Phần tử <KnownHeaders> có thể chứa một siêu tập hợp các mục được liệt kê trong crit.
Bạn chỉ cần liệt kê tất cả tiêu đề trong crit trong phần tử <KnownHeaders>. Mọi tiêu đề mà chính sách tìm thấy trong crit không có trong <KnownHeaders> đều khiến chính sách VerifyJWT không thành công.
Bạn có thể tuỳ ý định cấu hình chính sách VerifyJWT để bỏ qua tiêu đề crit bằng cách đặt phần tử <IgnoreCriticalHeaders> thành true.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Mảng chuỗi được phân tách bằng dấu phẩy |
| Giá trị hợp lệ | Một mảng hoặc tên của một biến chứa mảng. |
<PublicKey/Certificate>
<PublicKey> <Certificate ref="signed_public.cert"/> </PublicKey> -or- <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- cert data -----END CERTIFICATE----- </Certificate> </PublicKey>
Chỉ định chứng chỉ đã ký dùng để xác minh chữ ký trên JWT. Sử dụng thuộc tính ref để truyền chứng chỉ đã ký trong một biến luồng hoặc chỉ định trực tiếp chứng chỉ được mã hoá PEM. Chỉ sử dụng khi thuật toán là một trong các thuật toán RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.
| Mặc định | Không áp dụng |
| Sự hiện diện | Để xác minh JWT được ký bằng thuật toán RSA, bạn phải sử dụng các phần tử Chứng chỉ, JWKS hoặc Giá trị. |
| Loại | Chuỗi |
| Giá trị hợp lệ | Một biến hoặc chuỗi luồng. |
<PublicKey/JWKS>
<!-- Specify the JWKS. --> <PublicKey> <JWKS>jwks-value-here</JWKS> </PublicKey> or: <!-- Specify a variable containing the JWKS. --> <PublicKey> <JWKS ref="public.jwks"/> </PublicKey> or: <!-- Specify a public URL that returns the JWKS. The URL is static, meaning you cannot set it using a variable. --> <PublicKey> <JWKS uri="jwks-url"/> </PublicKey>
Chỉ định một giá trị ở định dạng JWKS (RFC 7517) chứa một tập hợp khoá công khai. Chỉ sử dụng khi thuật toán là một trong các thuật toán RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.
Nếu JWT đầu vào có một mã khoá xuất hiện trong tập hợp JWKS, thì chính sách sẽ dùng khoá công khai chính xác để xác minh chữ ký JWT. Để biết thông tin chi tiết về tính năng này, hãy xem phần Sử dụng một Nhóm khoá web JSON (JWKS) để xác minh JWT.
Nếu bạn tìm nạp giá trị từ một URL công khai, Edge sẽ lưu JWKS vào bộ nhớ đệm trong khoảng thời gian 300 giây. Khi bộ nhớ đệm hết hạn, Edge sẽ tìm nạp lại JWKS.
| Mặc định | Không áp dụng |
| Sự hiện diện | Để xác minh JWT bằng thuật toán RSA, bạn phải sử dụng phần tử Chứng chỉ, JWKS hoặc Giá trị. |
| Loại | Chuỗi |
| Giá trị hợp lệ | Một biến luồng, giá trị chuỗi hoặc URL. |
<PublicKey/Value>
<PublicKey> <Value ref="public.publickeyorcert"/> </PublicKey> -or- <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2 ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey>
Chỉ định khoá công khai hoặc chứng chỉ công khai dùng để xác minh chữ ký trên JWT. Sử dụng thuộc tính ref để truyền khoá/chứng chỉ trong một biến luồng hoặc chỉ định trực tiếp khoá được mã hoá PEM. Chỉ sử dụng khi thuật toán là một trong các thuật toán RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.
| Mặc định | Không áp dụng |
| Sự hiện diện | Để xác minh JWT được ký bằng thuật toán RSA, bạn phải sử dụng các phần tử Chứng chỉ, JWKS hoặc Giá trị. |
| Loại | Chuỗi |
| Giá trị hợp lệ | Một biến hoặc chuỗi luồng. |
<SecretKey/Value>
<SecretKey encoding="base16|hex|base64|base64url"> <Value ref="private.your-variable-name"/> </SecretKey>
Cung cấp khoá bí mật dùng để xác minh hoặc ký mã thông báo bằng thuật toán HMAC. Chỉ sử dụng khi thuật toán là một trong các thuật toán HS256, HS384, HS512..
| Mặc định | Không áp dụng |
| Sự hiện diện | Bắt buộc đối với các thuật toán HMAC. |
| Loại | Chuỗi |
| Giá trị hợp lệ |
Đối với Sử dụng thuộc tính ref để truyền khoá trong một biến luồng. Lưu ý: Nếu là một biến luồng, thì biến đó phải có tiền tố "private". Ví dụ:
|
<Source>
<Source>jwt-variable</Source>
Nếu có, hãy chỉ định biến luồng mà chính sách dự kiến sẽ tìm thấy JWT để xác minh.
| Mặc định | request.header.authorization (Xem lưu ý ở trên để biết thông tin quan trọng về chế độ mặc định). |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi |
| Giá trị hợp lệ | Tên biến luồng Edge. |
<Tiêu đề>
<Subject>subject-string-here</Subject>
Chính sách này xác minh rằng chủ đề trong JWT khớp với chuỗi được chỉ định trong cấu hình chính sách. Thông báo này xác định hoặc đưa ra một tuyên bố về chủ đề của JWT. Đây là một trong những bộ tiêu chuẩn khai báo được đề cập trong RFC7519.
| Mặc định | Không áp dụng |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi |
| Giá trị hợp lệ | Mọi giá trị nhận dạng riêng biệt một chủ đề. |
<TimeAllowance>
<TimeAllowance>120s</TimeAllowance>
"Thời gian gia hạn" cho các lần. Ví dụ: nếu bạn định cấu hình thời gian cho phép là 60 giây, thì JWT đã hết hạn sẽ được coi là vẫn hợp lệ trong 60 giây sau khi hết hạn được xác nhận. Thời gian không được phép trước đó sẽ được đánh giá tương tự. Mặc định là 0 giây (không có khoảng thời gian gia hạn).
| Mặc định | 0 giây (không có thời gian gia hạn) |
| Sự hiện diện | Không bắt buộc |
| Loại | Chuỗi |
| Giá trị hợp lệ |
Một giá trị hoặc một giá trị tham chiếu đến biến luồng chứa giá trị. Bạn có thể chỉ định khoảng thời gian như sau:
|
Biến luồng
Sau khi thành công, các chính sách Xác minh JWT và Giải mã JWT được đặt biến ngữ cảnh theo mẫu sau:
jwt.{policy_name}.{variable_name}
Ví dụ: nếu tên chính sách là jwt-parse-token, thì chính sách sẽ lưu trữ
đối tượng được chỉ định trong JWT thành biến ngữ cảnh có tên jwt.jwt-parse-token.decoded.claim.sub.
(Để có khả năng tương thích ngược, thư viện này cũng sẽ có trong jwt.jwt-parse-token.claim.subject)
| Tên biến | Mô tả |
|---|---|
claim.audience |
Đối tượng JWT. Giá trị này có thể là một chuỗi hoặc một mảng chuỗi. |
claim.expiry |
Ngày/giờ hết hạn, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống. |
claim.issuedat |
Ngày phát hành mã thông báo, được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống. |
claim.issuer |
Yêu cầu của nhà phát hành JWT. |
claim.notbefore |
Nếu JWT bao gồm xác nhận quyền sở hữu nbf, biến này sẽ chứa giá trị được biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống. |
claim.subject |
Chủ thể JWT xác nhận quyền sở hữu. |
claim.name |
Giá trị của thông báo xác nhận quyền sở hữu có tên (tiêu chuẩn hoặc bổ sung) trong tải trọng. Một trong những mức giá trị này sẽ được đặt cho mọi xác nhận quyền sở hữu trong tải trọng. |
decoded.claim.name |
Giá trị có thể phân tích cú pháp JSON của thông báo xác nhận quyền sở hữu đã nêu (tiêu chuẩn hoặc bổ sung) trong tải trọng. Một biến được đặt cho
mọi xác nhận quyền sở hữu trong tải trọng. Ví dụ: bạn có thể sử dụng decoded.claim.iat để
truy xuất thời điểm phát hành JWT, được biểu thị bằng giây kể từ thời gian bắt đầu của hệ thống. Khi bạn
cũng có thể sử dụng các biến luồng claim.name. Đây là
biến được đề xuất dùng để truy cập vào thông báo xác nhận quyền sở hữu. |
decoded.header.name |
Giá trị có thể phân tích cú pháp JSON của một tiêu đề trong tải trọng. Một biến được đặt cho
mọi tiêu đề trong tải trọng. Mặc dù bạn cũng có thể sử dụng các biến luồng header.name,
đây là biến được đề xuất dùng để truy cập vào tiêu đề. |
expiry_formatted |
Ngày/giờ hết hạn, được định dạng dưới dạng một chuỗi mà con người có thể đọc được. Ví dụ: 2017-09-28T21:30:45.000+0000 |
header.algorithm |
Thuật toán ký dùng trên JWT. Ví dụ: RS256, HS384, v.v. Hãy xem mục Thông số tiêu đề(Thuật toán) để tìm hiểu thêm. |
header.kid |
Mã khoá, nếu được thêm vào khi JWT được tạo. Xem thêm bài viết "Sử dụng bộ khoá web JSON (JWKS)" tại JWT tổng quan về chính sách để xác minh JWT. Hãy xem Tham số tiêu đề(Mã khoá) để tìm hiểu thêm. |
header.type |
Sẽ được đặt thành JWT. |
header.name |
Giá trị của tiêu đề có tên (tiêu chuẩn hoặc bổ sung). Một trong những mức giá trị này sẽ được đặt cho mọi tiêu đề bổ sung trong phần tiêu đề của JWT. |
header-json |
Tiêu đề ở định dạng JSON. |
is_expired |
true hoặc false |
payload-claim-names |
Một loạt các thông báo xác nhận quyền sở hữu được JWT hỗ trợ. |
payload-json |
Tải trọng ở định dạng JSON.
|
seconds_remaining |
Số giây trước khi mã thông báo hết hạn. Nếu mã thông báo đã hết hạn, số này sẽ là số âm. |
time_remaining_formatted |
Thời gian còn lại trước khi mã thông báo hết hạn, có định dạng là chuỗi mà con người có thể đọc được. Ví dụ: 00:59:59.926 |
valid |
Trong trường VerifyJWT, biến này sẽ có giá trị true khi chữ ký được xác minh và
thời gian hiện tại là trước khi mã thông báo hết hạn và sau giá trị not Google trước giá trị, nếu chúng
đều có sẵn. Còn không thì cờ này sẽ là false.
Trong trường hợp DecodeJWT, biến này không được thiết lập. |
Tham chiếu lỗi
Phần này mô tả các mã lỗi và thông báo lỗi được trả về, cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này đóng vai trò quan trọng trong việc phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.
Lỗi thời gian chạy
Những lỗi này có thể xảy ra khi thực thi chính sách.
| Mã lỗi | Trạng thái HTTP | Xảy ra khi |
|---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 | Xảy ra khi chính sách xác minh có nhiều thuật toán. |
steps.jwt.AlgorithmMismatch |
401 | Thuật toán được chỉ định trong chính sách Tạo không khớp với thuật toán dự kiến trong chính sách Xác minh. Thuật toán được chỉ định phải khớp. |
steps.jwt.FailedToDecode |
401 | Chính sách không thể giải mã JWT. JWT có thể bị hỏng. |
steps.jwt.GenerationFailed |
401 | Chính sách không thể tạo JWT. |
steps.jwt.InsufficientKeyLength |
401 | Đối với khoá có kích thước nhỏ hơn 32 byte đối với thuật toán HS256, nhỏ hơn 48 byte đối với thuật toán HS386 và nhỏ hơn 64 byte đối với thuật toán HS512. |
steps.jwt.InvalidClaim |
401 | Đối với thông báo xác nhận quyền sở hữu bị thiếu hoặc không khớp hoặc thiếu tiêu đề hoặc tiêu đề không khớp. |
steps.jwt.InvalidCurve |
401 | Đường cong do khoá chỉ định không hợp lệ cho thuật toán Đường cong Elliptic. |
steps.jwt.InvalidJsonFormat |
401 | Tìm thấy JSON không hợp lệ trong tiêu đề hoặc tải trọng. |
steps.jwt.InvalidToken |
401 | Lỗi này xảy ra khi không xác minh được chữ ký JWT. |
steps.jwt.JwtAudienceMismatch |
401 | Không xác nhận được đối tượng khi xác minh mã thông báo. |
steps.jwt.JwtIssuerMismatch |
401 | Xác nhận quyền sở hữu của nhà phát hành không thành công khi xác minh mã thông báo. |
steps.jwt.JwtSubjectMismatch |
401 | Không xác nhận được chủ thể khi xác minh mã thông báo. |
steps.jwt.KeyIdMissing |
401 | Chính sách Xác minh sử dụng JWKS làm nguồn cho khoá công khai, nhưng JWT đã ký không
có thuộc tính kid trong tiêu đề. |
steps.jwt.KeyParsingFailed |
401 | Không thể phân tích cú pháp khoá công khai từ thông tin khoá đã cho. |
steps.jwt.NoAlgorithmFoundInHeader |
401 | Xảy ra khi JWT không chứa tiêu đề thuật toán. |
steps.jwt.NoMatchingPublicKey |
401 | Chính sách Xác minh sử dụng JWKS làm nguồn cho khoá công khai, nhưng kid
trong JWT đã ký không có trong JWKS. |
steps.jwt.SigningFailed |
401 | Trong GenerateJWT, đối với khoá nhỏ hơn kích thước tối thiểu dành cho thuật toán HS384 hoặc HS512 |
steps.jwt.TokenExpired |
401 | Chính sách này cố gắng xác minh một mã thông báo đã hết hạn. |
steps.jwt.TokenNotYetValid |
401 | Mã thông báo chưa hợp lệ. |
steps.jwt.UnhandledCriticalHeader |
401 | Một tiêu đề do chính sách Verify JWT tìm thấy trong tiêu đề crit không được liệt kê trong KnownHeaders. |
steps.jwt.UnknownException |
401 | Đã xảy ra ngoại lệ không xác định. |
steps.jwt.WrongKeyType |
401 | Chỉ định sai loại khoá. Ví dụ: nếu bạn chỉ định khoá RSA cho thuật toán Elliptic Curve hoặc khoá đường cong cho thuật toán RSA. |
Lỗi triển khai
Những lỗi này có thể xảy ra khi bạn triển khai proxy chứa chính sách này.
| Tên lỗi | Nguyên nhân | Khắc phục |
|---|---|---|
InvalidNameForAdditionalClaim |
Việc triển khai sẽ không thành công nếu thông báo xác nhận quyền sở hữu dùng trong phần tử con <Claim> của phần tử <AdditionalClaims> là một trong những tên đã đăng ký sau đây: kid, iss, sub, aud, iat, exp, nbf hoặc jti.
|
build |
InvalidTypeForAdditionalClaim |
Nếu thông báo xác nhận quyền sở hữu dùng trong phần tử con <Claim> của phần tử <AdditionalClaims> không thuộc loại string, number, boolean hoặc map, thì quá trình triển khai sẽ không thành công.
|
build |
MissingNameForAdditionalClaim |
Nếu tên của thông báo xác nhận quyền sở hữu không được chỉ định trong phần tử con <Claim> của phần tử <AdditionalClaims>, thì quá trình triển khai sẽ không thành công.
|
build |
InvalidNameForAdditionalHeader |
Lỗi này xảy ra khi tên của thông báo xác nhận quyền sở hữu dùng trong phần tử con <Claim> của phần tử <AdditionalClaims> là alg hoặc typ.
|
build |
InvalidTypeForAdditionalHeader |
Nếu loại thông báo xác nhận quyền sở hữu dùng trong phần tử con <Claim> của phần tử <AdditionalClaims> không thuộc loại string, number, boolean hoặc map, thì quá trình triển khai sẽ không thành công.
|
build |
InvalidValueOfArrayAttribute |
Lỗi này xảy ra khi giá trị của thuộc tính mảng trong phần tử con <Claim> của phần tử <AdditionalClaims> không được đặt thành true hoặc false.
|
build |
InvalidValueForElement |
Nếu giá trị được chỉ định trong phần tử <Algorithm> không phải là giá trị được hỗ trợ, thì quá trình triển khai sẽ không thành công.
|
build |
MissingConfigurationElement |
Lỗi này sẽ xảy ra nếu không sử dụng phần tử <PrivateKey> với thuật toán nhóm RSA hoặc phần tử <SecretKey> không được sử dụng với thuật toán Nhóm HS.
|
build |
InvalidKeyConfiguration |
Nếu phần tử con <Value> không được xác định trong các phần tử <PrivateKey> hoặc <SecretKey>, thì quá trình triển khai sẽ không thành công.
|
build |
EmptyElementForKeyConfiguration |
Nếu thuộc tính ref của phần tử con <Value> trong các phần tử <PrivateKey> hoặc <SecretKey> bị trống hoặc chưa được chỉ định, thì quá trình triển khai sẽ không thành công.
|
build |
InvalidConfigurationForVerify |
Lỗi này xảy ra nếu phần tử <Id> được xác định trong phần tử <SecretKey>.
|
build |
InvalidEmptyElement |
Lỗi này xảy ra nếu phần tử <Source> của chính sách Verify JWT trống. Nếu có, bạn phải xác định biến này bằng tên biến Luồng biên.
|
build |
InvalidPublicKeyValue |
Nếu giá trị dùng trong phần tử con <JWKS> của phần tử <PublicKey> không sử dụng định dạng hợp lệ như được chỉ định trong RFC 7517, thì quá trình triển khai sẽ không thành công.
|
build |
InvalidConfigurationForActionAndAlgorithm |
Nếu phần tử <PrivateKey> được sử dụng với thuật toán Gia đình HS hoặc phần tử <SecretKey> được sử dụng với thuật toán Nhóm RSA, thì quá trình triển khai sẽ không thành công.
|
build |
Biến lỗi
Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.
| Biến | Trong đó | Ví dụ: |
|---|---|---|
fault.name="fault_name" |
fault_name là tên của lỗi, như được liệt kê trong bảng Lỗi thời gian chạy ở trên. Tên lỗi là phần cuối cùng của mã lỗi. | fault.name Matches "TokenExpired" |
JWT.failed |
Tất cả các chính sách JWT đều đặt cùng một biến trong trường hợp không thành công. | JWT.failed = true |
Ví dụ về phản hồi khi gặp lỗi
Để xử lý lỗi, phương pháp hay nhất là bẫy phần errorcode của lỗi
của bạn. Đừng dựa vào văn bản trong faultstring vì văn bản này có thể thay đổi.
Ví dụ về quy tắc lỗi
<FaultRules>
<FaultRule name="JWT Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWT.failed=true</Condition>
</FaultRule>
</FaultRules>