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

Chính sách DecodeJWT

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ã JWT mà không cần xác minh chữ ký trên JWT. Phương thức này hữu ích nhất khi được dùng cùng với chính sáchVerifyJWT, khi bạn phải xác định giá trị của một thông báo xác nhận quyền sở hữu trong JWT trước khi xác minh chữ ký của JWT.

Chính sách Giải mã JWT hoạt động bất kể thuật toán dùng để ký JWT. Hãy xem bài viết Tổng quan về các chính sách JWS và JWT để nắm được nội dung giới thiệu chi tiết.

Video

Xem một video ngắn để tìm hiểu cách giải mã JWT.

Mẫu: Giải mã JWT

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

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

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 các 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.

Tài liệu tham khảo phần tử cho Giải mã JWT

Tài liệu tham khảo về 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ã JWT.

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

<DecodeJWT name="JWT" 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>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 JWT để giải mã.

Lưu ý: Theo mặc định, JWT được truy xuất từ biến request.header.delegate. Trong trường hợp này, Edge sẽ tìm JWT trong tiêu đề Uỷ quyền của yêu cầu. Nếu chuyển JWT trong tiêu đề Uỷ quyền, thì bạn không cần đưa phần tử Nguồn 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 JWT trong tiêu đề Uỷ quyền như sau:

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

Bạn có thể định cấu hình cho chính sách để truy xuất JWT 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 JWT, 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 Xác minh JWT và Giải mã JWT sẽ đặt các 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 này sẽ lưu trữ đối tượng được chỉ định trong JWT vào biến ngữ cảnh có tên là jwt.jwt-parse-token.decoded.claim.sub. (Để có khả năng tương thích ngược, tính năng này cũng có trong jwt.jwt-parse-token.claim.subject)

Tên biến	Nội dung mô tả
`claim.audience`	Xác nhận quyền sở hữu đố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, biểu thị bằng mili giây kể từ thời gian bắt đầu của hệ thống.
`claim.issuer`	Khiếu nại của nhà phát hành JWT.
`claim.notbefore`	Nếu JWT có thông báo xác nhận quyền sở hữu nbf, thì 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`	Tuyên bố về chủ đề JWT.
`claim.name`	Giá trị của thông báo xác nhận quyền sở hữu được đặt tên (tiêu chuẩn hoặc bổ sung) trong tải trọng. Một trong các chế độ cài đặt này sẽ được đặt cho mọi thông báo 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 có tên (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 tại thời điểm JWT, biểu thị bằng giây kể từ thời gian bắt đầu của hệ thống. Mặc dù bạn cũng có thể dùng các biến luồng `claim.name`, nhưng đây là biến bạn nên 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ị 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 đề.
`expiry_formatted`	Ngày/giờ hết hạn, ở định dạng 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. 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 JWT. Hãy xem thêm phần "Sử dụng Bộ khoá web JSON (JWKS)" trong bài viết Tổng quan về chính sách JWT để xác minh JWT. Xem Tham số tiêu đề(ID khóa) để biết thêm.
`header.type`	Sẽ được đặt thành `JWT`.
`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 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 do 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, ở định dạng chuỗi mà con người có thể đọc được. Ví dụ: 00:59:59.926
`valid`	Trong trường hợp của VerifyJWT, biến này sẽ là đúng khi chữ ký được xác minh, đồng thời thời gian hiện tại là trước khi mã thông báo hết hạn và sau khi có giá trị notBefore của mã thông báo (nếu có). Nếu không, giá trị này sẽ là false. Trong trường hợp của DecodeJWT, 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	Nguyên nhân
`steps.jwt.FailedToDecode`	401	Xảy ra khi chính sách không thể giải mã JWT. JWT có thể không đúng định dạng, không hợp lệ hoặc không thể giải mã.
`steps.jwt.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.jwt.InvalidToken`	401	Xảy ra khi biến luồng được chỉ định trong phần tử `<Source>` của chính sách nằm ngoài phạm vi hoặc không thể giải quyết.

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
`InvalidEmptyElement`	Xảy ra khi biến luồng chứa JWT cần giải mã không được chỉ định trong phần tử `<Source>` của chính sách.

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"`
`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 xảy ra lỗi.	`JWT.failed = true`

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

Mã lỗi chính sách JWT

Để 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="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>