Chính sách Xác minh JWT

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

Xác minh chữ ký trên JWT nhận được từ ứng dụng hoặc hệ thống khác. Chính sách này cũng trích xuất các thông báo xác nhận quyền sở hữu 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ị đó nhằm đưa ra quyết định uỷ quyền hoặc định tuyến. 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.

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 là hợp lệ theo thời gian hết hạn chứ không phải trước thời điểm nếu có. Chính sách này cũng có thể tuỳ ý xác minh giá trị của các thông báo xác nhận quyền sở hữu cụ thể trên JWT, chẳng hạn như chủ thể, người phát hành, đối tượng hoặc giá trị của thông báo xác nhận quyền sở hữu bổ sung.

Nếu JWT đã được xác minh và hợp lệ, thì mọi thông báo xác nhận quyền sở hữu trong JWT sẽ được trích xuất thành các biến ngữ cảnh để dùng cho các chính sách hoặc điều kiện tiếp theo, và yêu cầu sẽ được phép tiếp tục. Nếu không thể xác minh chữ ký JWT hoặc nếu JWT không hợp lệ vì một trong những dấu thời gian, thì mọi quá trình xử lý sẽ dừng và lỗi sẽ được trả về trong phản hồi.

Để tìm hiểu về các thành phần của JWT cũng như cách các thành phần đó được mã hoá và ký, 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 một JWT được ký bằng thuật toán HS256

Chính sách ví dụ này xác minh một JWT đã được ký bằng thuật toán mã hoá HS256, HMAC bằng giá trị tổng kiểm SHA-256. JWT được chuyển vào yêu cầu proxy bằng cách sử dụng tham số biểu mẫu có tên jwt. Khoá này nằm trong biến có tên private.secretkey. Xem video ở trên để biết ví dụ hoàn chỉnh, bao gồm cả cách gửi 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ư nơi tìm JWT (trong biến luồng được chỉ định trong phần tử Nguồn), thuật toán ký bắt buộc, nơi tìm khoá bí mật (được lưu trữ trong biến luồng Edge, có thể được truy xuất từ Edge KVM chẳng hạn) và tập hợp các xác nhận quyền sở hữu bắt buộc cũng như 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 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.

Xác minh JWT đã ký bằng thuật toán RS256

Chính sách trong ví dụ 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 chuyển vào yêu cầu proxy bằng cách sử dụng tham số biểu mẫu có tên jwt. Khoá công khai nằm trong biến có tên public.publickey. Xem video ở trên để biết ví dụ hoàn chỉnh, bao gồm cả cách gửi yêu cầu đối với chính sách.

Hãy xem 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, 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.

JWT có cùng tiêu đề nhưng với tải trọng 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 có thể xác minh chữ ký, vì thông báo xác nhận quyền sở hữu "phụ" có trong JWT không khớp với giá trị bắt buộc của phần tử "Tiêu đề" 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 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.

Thiết lập thành phần chính

Các phần tử mà bạn sử dụng để chỉ định khoá dùng để xác minh JWT còn phụ thuộc vào thuật toán đã chọn, như minh hoạ trong bảng sau:

Thuật toán Các thành phần chính
HS*
<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>
RS*, Tây Ban Nha*, 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 quan trọng, hãy xem bài viết Giới thiệu về thuật toán mã hoá chữ ký.

Tham chiếu phần tử

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 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 Ứng dụng mẫu để xem các ví dụ minh hoạ cấu hình cho các trường hợp sử dụng cụ thể.

Những 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">

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

<Algorithm>

<Algorithm>HS256</Algorithm>

Chỉ định thuật toán mã hoá để ký mã thông báo. Thuật toán RS*/PS*/ES* sử dụng một cặp khoá công khai/bí mật, trong khi thuật toán HS* sử dụng một cặp khoá bí mật dùng chung. Xem thêm bài viết Giới thiệu về 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 thuật toán HS* với bất kỳ thuật toán nào khác hoặc thuật toán ES* với bất kỳ thuật toán nào khác vì các thuật toán này yêu cầu một loại khoá cụ thể. Bạn có thể kết hợp 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 thông báo xác nhận quyền sở hữu đố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ẽ gửi lỗi. Thông báo xác nhận quyền sở hữu này xác định những người nhận mà JWT muốn gửi. Đây là một trong những thông báo xác nhận quyền sở hữu đã được đăng ký và đượ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ệ Chuỗi hoặc biến luồng xác định đối tượng.

<AdditionalClaims/Claim> (Xác nhận bổ sung/Xác nhận quyền sở hữu>)

<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 tải trọng JWT chứa(các) thông báo xác nhận bổ sung được chỉ định và các giá trị xác nhận quyền sở hữu đã xác nhận trùng khớp với nhau.

Thông báo xác nhận quyền sở hữu bổ sung có tên không phải là một trong các tên xác nhận quyền sở hữu chuẩn được đăng ký và được đăng ký tại JWT. Giá trị của một tuyên bố bổ sung có thể là chuỗi, số, boolean, tệp ánh xạ hoặc mảng. Tệp ánh xạ 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 giá trị cho thông báo xác nhận quyền sở hữu thuộc bất kỳ loại nào trong số này một cách rõ ràng trong cấu hình chính sách hoặc gián tiếp thông qua 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ệ Bất kỳ giá trị nào mà bạn muốn sử dụng cho một thông báo xác nhận quyền sở hữu bổ sung.

Phần tử <Claim> có các thuộc tính sau:

  • name – (Bắt buộc) Tên của thông báo xác nhận quyền sở hữu.
  • ref – (Không bắt buộc) Tên của biến luồng. Nếu có, chính sách này sẽ sử dụng giá trị của biến này làm thông báo xác nhận quyền sở hữu. Nếu bạn chỉ định cả thuộc tính ref và giá trị tuyên bố rõ ràng, thì giá trị tường minh 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: string (mặc định), number, boolean hoặc map
  • mảng – (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 thông báo xác nhận quyền sở hữu sẽ được đặt cố định khi bạn định cấu hình chính sách. Ngoài ra, bạn có thể truyền đối tượng JSON để chỉ định tên xác nhận quyền sở hữu. Vì đối tượng JSON được truyền dưới dạng biến, nên tên 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 đố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> (Thông tin bổ sung/Xác nhận quyền sở hữu>)

<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ị xác nhận bổ sung được chỉ định và các giá trị xác nhận quyền sở hữu trùng khớp với nhau.

Thông báo xác nhận quyền sở hữu bổ sung sử dụng tên không phải là một trong các tên xác nhận quyền sở hữu JWT chuẩn đã được đăng ký. Giá trị của một tuyên bố bổ sung có thể là chuỗi, số, boolean, tệp ánh xạ hoặc mảng. Tệp ánh xạ 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 giá trị cho thông báo xác nhận quyền sở hữu thuộc bất kỳ loại nào trong số này một cách rõ ràng trong cấu hình chính sách hoặc gián tiếp thông qua 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 đồ.

Kiểu mặc định là Chuỗi nếu 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ệ Bất kỳ giá trị nào mà bạn muốn sử dụng cho một thông báo xác nhận quyền sở hữu bổ sung.

Phần tử <Claim> có các thuộc tính sau:

  • name – (Bắt buộc) Tên của thông báo xác nhận quyền sở hữu.
  • ref – (Không bắt buộc) Tên của biến luồng. Nếu có, chính sách này sẽ sử dụng giá trị của biến này làm thông báo xác nhận quyền sở hữu. Nếu bạn chỉ định cả thuộc tính ref và giá trị tuyên bố rõ ràng, thì giá trị tường minh 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: string (mặc định), number, boolean hoặc map
  • mảng – (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 một 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à bị bỏ qua. Phần tử chính xác cần sử dụng là <AdditionalClaims> (Giao diện người dùng). Giao diện người dùng sẽ được cập nhật để chèn đúng phần tử sau này.

<Mã nhận dạng>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Xác minh rằng JWT có xác nhận quyền sở hữu jti cụ thể. Khi cả giá trị văn bản và thuộc tính tham chiếu đều trống, chính sách này sẽ tạo một jti chứa UUID ngẫu nhiên. Tuyên bố xác nhận quyền sở hữu mã JWT (jti) là giá trị nhận dạng duy nhất của 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 tệp tham chiếu.
Giá trị hợp lệ Một chuỗi hoặc tên của biến luồng có 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 báo lỗi khi có bất kỳ tiêu đề nào trong tiêu đề crit của JWT không có 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 (đúng) 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 trên tiêu đề bị thiế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 gửi một lỗi khi JWT chứa thông báo xác nhận quyền sở hữu iat (Được phát hành lúc) chỉ định một thời điểm trong tương lai. Nếu bạn đặt chính sách này thành true (đúng), thì chính sách sẽ 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 báo lỗi khi không thể giải quyết mọi biến được tham chiếu đã chỉ định trong chính sách. Đặt thành true để coi mọi biến không thể phân giải là chuỗi trống (null).

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 trình phát hành trong JWT khớp với chuỗi được chỉ định trong phần tử cấu hình. Đơn khiếu nại xác định bên phát hành JWT. Đây là một trong nhóm thông báo xác nhận quyền sở hữu đã đăng ký và đượ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 tệp 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áchGenerateJWT 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 kiểm tra tiêu đề crit trong JWT nếu có. Đối với mỗi tiêu đề được liệt kê, chính sách 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 tập mẹ của các mục được liệt kê trong crit. Điều cần thiết là tất cả tiêu đề được liệt kê trong crit phải được liệt kê trong phần tử <KnownHeaders>. Nếu bất kỳ tiêu đề nào mà chính sách này tìm thấy trong crit nhưng không cũng có trong <KnownHeaders>, thì chính sách này đều sẽ 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ảng hoặc tên của biến chứa mảng đó.

<Khoá công khai/Chứng chỉ>

<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. Hãy 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ã hóa PEM. Chỉ sử dụng khi thuật toán là một trong các giá trị 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 một JWT đã 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ệ Chuỗi hoặc biến 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 các khoá công khai. Chỉ sử dụng khi thuật toán là một trong các giá trị RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

Nếu JWT đến có mã nhận dạng khoá nằm trong tập hợp JWKS, thì chính sách này sẽ 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 bài viết Sử dụng Bộ 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ệ 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 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 loại 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 một JWT đã 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ệ Chuỗi hoặc biến 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 mã HS256, HS384, HS512..

Mặc định Không áp dụng
Sự hiện diện Bắt buộc đối với thuật toán HMAC.
Loại Chuỗi
Giá trị hợp lệ

Đối với encoding, giá trị hợp lệ là hex, base16, base64 hoặc base64url. Các giá trị mã hoá hexbase16 là các từ đồng nghĩa.

Sử dụng thuộc tính ref để truyền khoá vào một biến luồng.

Lưu ý: Nếu một biến luồng, biến đó phải có tiền tố "private". Ví dụ: private.mysecret

<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 để xác minh.

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.

<Subject>

<Subject>subject-string-here</Subject>

Chính sách này xác minh rằng chủ thể trong JWT khớp với chuỗi được chỉ định trong cấu hình chính sách. Tuyên bố này xác định hoặc đưa ra tuyên bố về chủ thể của JWT. Đây là một trong những nhóm thông báo xác nhận quyền sở hữu tiêu chuẩn đượ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ệ Bất kỳ giá trị nào xác định duy nhất một chủ thể.

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

"Thời gian ân hạn" cho thời gian. Ví dụ: nếu thời gian cho phép được định cấu hình 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. Giá trị không phải thời gian trước đó cũng sẽ được đánh giá tương tự. Giá trị mặc định là 0 giây (không có 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ệ Giá trị hoặc 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:
  • s = giây
  • m = phút
  • h = giờ
  • d = ngày

Biến luồng

Sau khi thành công, các chính sách Xác minh JWTGiả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áchXử 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.
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.
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.
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>alg hoặc typ.
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.
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.
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.
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.
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.
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.
InvalidConfigurationForVerify Lỗi này xảy ra nếu phần tử <Id> được xác định trong phần tử <SecretKey>.
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.
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.
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.

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>