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

Chính sách DecodeJWS

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Nội dung

Giải mã tiêu đề JWS mà không cần xác minh chữ ký trên JWS và ghi từng tiêu đề vào một biến luồng. Chính sách này hữu ích nhất khi được dùng cùng với chính sáchVerifyJWS, khi phải xác định được giá trị của tiêu đề bên trong JWS trước khi xác minh chữ ký của JWS.

JWS có thể có tải trọng đính kèm, như trong biểu mẫu:

header.payload.signature

Hoặc JWS có thể bỏ qua tải trọng, được gọi là tải trọng detached và ở dạng:

header..signature

Chính sách DecodeJWS hoạt động với cả hai dạng vì chính sách này chỉ giải mã phần tiêu đề của JWS. Chính sách DecodeJWS cũng hoạt động bất kể thuật toán dùng để ký JWS.

Hãy xem bài viết Tổng quan về các chính sách JWS và JWT để biết nội dung giới thiệu chi tiết và thông tin tổng quan về định dạng của JWS.

Video

Xem một video ngắn để tìm hiểu cách giải mã JWT. Mặc dù video này dành riêng cho một JWT, nhưng nhiều khái niệm giống nhau đối với JWS.

Mẫu: Giải mã JWS

Chính sách hiển thị bên dưới giải mã một JWS có trong biến luồng var.JWS. Biến này phải có mặt và chứa một JWS khả thi (có thể phân tách). Chính sách này có thể lấy JWS từ bất kỳ biến luồng nào.

<DecodeJWS name="JWS-Decode-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Source>var.JWS</Source>
</DecodeJWS>

Đối với mỗi tiêu đề trong phần tiêu đề của JWS, chính sách này sẽ đặt một biến luồng có tên là:

jws.policy-name.header.header-name

Nếu JWS có tải trọng đính kèm, thì JWS sẽ đặt biến luồng jws.policy-name.header.payload thành tải trọng. Đối với tải trọng có thể tách rời, payload sẽ trống. Xem phần Biến luồng để biết danh sách đầy đủ các biến do chính sách này đặt.

Tài liệu tham khảo phần tử để giải mã JWS

Tài liệu tham khảo chính sách mô tả các phần tử và thuộc tính của chính sách Giải mã JWS.

Những thuộc tính áp dụng cho phần tử cấp cao nhất

<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">

Những thuộc tính sau đây là những thuộc tính chung của tất cả phần tử mẹ của chính sách.

Thuộc tính	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 dùng các ký tự sau đây trong tên: `A-Z0-9._\-$ %`. Tuy nhiên, giao diện người dùng quản lý Edge thực thi các hạn chế bổ sung, chẳng hạn như tự động xoá các ký tự không phải là chữ và số. Bạn có thể sử dụng phần tử `<displayname></displayname>` để gắn nhãn cho chính sách bằng một tên ngôn ngữ tự nhiên khác trong trình chỉnh sửa proxy giao diện người dùng quản lý (không bắt buộc).	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 hoạt độ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 `true` để quá trình thực thi luồng tiếp tục ngay cả khi chính sách không thành công.	false	Không bắt buộc
đang bật	Đặt thành `true` để thực thi chính sách. Đặt thành `false` để "tắt" chính sách này. Chính sách này sẽ không được thực thi ngay cả khi chính sách vẫn được đính kèm vào một quy trình.	đúng	Không bắt buộc
async	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 tên để gắn nhãn cho chính sách bằng một tên khác bằng ngôn ngữ tự nhiên trong trình chỉnh sửa proxy giao diện người dùng quản lý.

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

<Nguồn>

<Source>JWS-variable</Source>

Nếu có, hãy chỉ định biến luồng mà chính sách dự kiến sẽ tìm JWS để giải mã.

Lưu ý: Theo mặc định, JWS được truy xuất từ biến request.header.management. Trong trường hợp này, Edge sẽ tìm JWS trong tiêu đề Uỷ quyền yêu cầu. Nếu chuyển JWS trong tiêu đề Uỷ quyền, bạn không cần đưa phần tử Source vào chính sách. Tuy nhiên, bạn phải đưa Bheader vào tiêu đề xác thực. Ví dụ: bạn sẽ chuyển JWS trong tiêu đề Uỷ quyền như sau:

curl -v http://52.200.92.187:9001/doctest-JWS/verify-rs256 -H "Authorization: Bearer <your JWS>"

Bạn có thể định cấu hình để truy xuất JWS từ một biểu mẫu hoặc biến tham số truy vấn hay bất kỳ biến nào khác. Nếu biến không tồn tại hoặc nếu chính sách không tìm thấy JWS, thì chính sách sẽ trả về lỗi.

Mặc định	`request.header.authorization` (Xem ghi chú ở 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

Biến luồng

Sau khi thành công, các chính sách Verify JWS (Xác minh JWS) và Decode JWS (Giải mã JWS) sẽ đặt các biến ngữ cảnh theo mẫu sau:

jws.{policy_name}.{variable_name}

Ví dụ: nếu tên chính sách là verify-jws, thì chính sách sẽ lưu trữ thuật toán được chỉ định trong JWS vào biến ngữ cảnh này: jws.verify-jws.header.algorithm

Tên biến	Nội dung mô tả
`decoded.header.name`	Giá trị 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ể dùng các biến luồng `header.name`, nhưng đây là biến bạn nên dùng để truy cập vào tiêu đề.
`header.algorithm`	Thuật toán ký dùng trên JWS. Ví dụ: RS256, HS384, v.v. Xem Thông số tiêu đề(Thuật toán) để biết thêm thông tin.
`header.kid`	Mã khoá, nếu được thêm vào khi tạo JWS. Hãy xem thêm bài viết "Sử dụng Bộ khoá web JSON (JWKS)" tại bài viết Tổng quan về chính sách JWT và JWS để xác minh JWS. Xem Tham số tiêu đề(ID khóa) để biết thêm.
`header.type`	Giá trị loại tiêu đề. Xem nội dung Tham số tiêu đề(Type) để biết thêm thông tin.
`header.name`	Giá trị của tiêu đề đã đặt tên (chuẩn hoặc bổ sung). Một trong các chế độ cài đặt này sẽ được đặt cho mọi tiêu đề bổ sung trong phần tiêu đề của JWS.
`header-json`	Tiêu đề ở định dạng JSON.
`payload`	Tải trọng JWS nếu JWS có tải trọng đính kèm. Đối với tải trọng có thể tách rời, biến này trống.
`valid`	Trong trường hợp của VerifyJWS, biến này sẽ là true khi chữ ký được xác minh, thời gian hiện tại là trước khi mã thông báo hết hạn và sau giá trị của mã thông báo notBefore (nếu có). Nếu không, giá trị này sẽ là false. Trong trường hợp của DecodeJWS, biến này không được đặt.

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.jws.FailedToDecode`	401	Chính sách không thể giải mã JWS. JWS có thể bị hỏng.
`steps.jws.FailedToResolveVariable`	401	Xảy ra khi biến luồng được chỉ định trong phần tử `<Source>` của chính sách không tồn tại.
`steps.jws.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.jws.InvalidJsonFormat`	401	Tìm thấy JSON không hợp lệ trong tiêu đề JWS.
`steps.jws.InvalidJws`	401	Lỗi này xảy ra khi không xác minh được chữ ký JWS.
`steps.jws.InvalidPayload`	401	Tải trọng JWS không hợp lệ.
`steps.jws.InvalidSignature`	401	`<DetachedContent>` bị bỏ qua và JWS có tải trọng nội dung tách rời.
`steps.jws.MissingPayload`	401	Thiếu tải trọng JWS.
`steps.jws.NoAlgorithmFoundInHeader`	401	Xảy ra khi JWS bỏ qua tiêu đề thuật toán.
`steps.jws.UnknownException`	401	Đã xảy ra ngoại lệ không xác định.

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 Xảy ra khi

InvalidAlgorithm Các giá trị hợp lệ duy nhất là: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

Tên lỗi	Xảy ra khi
`InvalidAlgorithm`	Các giá trị hợp lệ duy nhất là: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.
`EmptyElementForKeyConfiguration` `FailedToResolveVariable` `InvalidConfigurationForActionAndAlgorithmFamily` `InvalidConfigurationForVerify` `InvalidEmptyElement` `InvalidFamiliesForAlgorithm` `InvalidKeyConfiguration` `InvalidNameForAdditionalClaim` `InvalidNameForAdditionalHeader` `InvalidPublicKeyId` `InvalidPublicKeyValue` `InvalidSecretInConfig` `InvalidTypeForAdditionalClaim` `InvalidTypeForAdditionalHeader` `InvalidValueForElement` `InvalidValueOfArrayAttribute` `InvalidVariableNameForSecret` `MissingConfigurationElement` `MissingElementForKeyConfiguration` `MissingNameForAdditionalClaim` `MissingNameForAdditionalHeader`	Các lỗi triển khai khác có thể xảy ra.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

Các lỗi triển khai khác có thể xảy ra.

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 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ư 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"`
`JWS.failed`	Tất cả các chính sách JWS đều đặt cùng một biến trong trường hợp xảy ra lỗi.	`jws.JWS-Policy.failed = true`

Ví dụ về phản hồi lỗi

Để xử lý lỗi, phương pháp hay nhất là giữ phần errorcode của phản hồi lỗi. Đừ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="JWS Policy Errors">
        <Step>
            <Name>JavaScript-1</Name>
            <Condition>(fault.name Matches "TokenExpired")</Condition>
        </Step>
        <Condition>JWS.failed=true</Condition>
    </FaultRule>
</FaultRules>