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 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 sau đó 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 phần 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 hạn và thời điểm không trước thời điểm đó (nếu có). Chính sách này có thể tuỳ ý cũng xác minh giá trị của các yêu cầu cụ thể về JWT, chẳng hạn như chủ thể, người phát hành, đối tượng người xem hoặc giá trị của các 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ì tất cả các xác nhận quyền sở hữu có trong JWT đều là được trích xuất vào các biến ngữ cảnh để sử dụng cho các chính sách hoặc điều kiện tiếp theo và yêu cầu đượ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ệ do một trong các dấu thời gian, tất cả quá trình xử lý đều dừng và lỗi được trả về trong phản hồi.

Để tìm hiểu về các phần của JWT cũng như cách các phần đó được mã hoá và ký, hãy tham khảo bài viết RFC7519.

Video

Xem 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 đã ký bằng HS256 thuật toán

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 cách sử dụ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 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ách yêu cầu 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 một biến luồng được chỉ định trong phần tử Nguồn), yêu cầu thuật toán ký, 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) và một tập hợp các xác nhận quyền sở hữu bắt buộc và giá trị.

<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 ghi kết quả 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 bài viết Các biến Luồng để biết danh sách các biến do chính sách này đặt ra.

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

Chính sách mẫu này xác minh 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 là jwt. Khoá công khai này 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ách yêu cầu chính sách.

Xem tài liệu tham khảo về Phần tử để biết chi tiết về các yêu cầu và lựa chọn cho mỗi phần tử trong chính sách mẫu.

<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 với .

Một 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ẽ bị xác định là không hợp lệ, ngay cả khi chữ ký đó có thể xác minh được vì "sub" thông báo xác nhận quyền sở hữu trong JWT không khớp với giá trị bắt buộc của "Subject" dưới dạng được chỉ định trong cấu hình chính sách.

Chính sách ghi kết quả 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 bài viết Các biến Luồng để biết danh sách các biến do chính sách này đặt ra.

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

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

Thuật toán Phần tử 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 chính, hãy xem 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 chính sách mô tả các thành phần 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 phương thức 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ạ cho các 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 áp dụng chung cho tất cả phần tử mẹ 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ể sử dụng các ký tự trong tên này: A-Z0-9._\-$ %. Tuy nhiên, giao diện người dùng quản lý Edge sẽ thực thi thêm các hạn chế cụ thể, chẳng hạn như tự động xoá các ký tự không phải là chữ và số.

Bạn có thể dùng phần tử <displayname></displayname> để (không bắt buộc) gắn nhãn chính sách trong trình chỉnh sửa proxy của giao diện người dùng quản lý bằng ngôn ngữ tự nhiên khác .

Không áp dụng Bắt buộc
continueOnError Đặt thành false để trả về lỗi khi chính sách không thành công. Điều này là dự kiến đối với hầu hết các chính sách.

Đặt thành true để tiếp tục thực thi luồng ngay cả sau khi có chính sách không thành công.

false Không bắt buộc
đang bật Hãy đặt thành true để thực thi chính sách này.

Đặt thành false để "tắt" chính sách. Chính sách này sẽ không được thực thi ngay cả khi đoạn mã vẫn được liên kết với một luồng.

đúng 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

&lt;DisplayName&gt;

<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 ngôn ngữ tự nhiên khác.

Mặc định Nếu bạn bỏ qua phần tử này, hệ thống sẽ sử dụng giá trị của thuộc tính tên của chính sách.
Sự hiện diện Không bắt buộc
Loại Chuỗi

&lt;Algorithm&gt;

<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, còn thuật toán HS* sử dụng một bí mật dùng chung. Xem thêm 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 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ì 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

&lt;Audience&gt;

<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 . Nếu không có kết quả nào trùng khớp, chính sách sẽ gửi thông báo lỗi. Xác nhận quyền sở hữu này xác định người nhận mà JWT nhắm đến. Đây là một trong những tuyên bố đã đă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ệ Biến luồng hoặc chuỗi xác định đối tượng.

&lt;AdditionalClaims/Claim&gt;

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

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 thông báo xác nhận quyền sở hữu JWT tiêu chuẩn. Giá trị của một thông báo xác nhận quyền sở hữu bổ sung có thể là chuỗi, số, boolean, ánh xạ hoặc mảng. Một bản đồ chỉ 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ố các loại này rõ ràng trong cấu hình chính sách hoặc gián tiếp thông qua việc 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 ánh xạ
Mảng Đặt thành true để cho biết liệu giá trị có phải là một mảng loại hay không. Mặc định: sai
Giá trị hợp lệ Bất kỳ giá trị nào mà bạn muốn sử dụng để 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 một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của đoạn mã 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ị xác nhận rõ ràng thì giá trị rõ ràng là mặc định và được dùng nếu biến luồng được tham chiếu không được giải quyết.
  • type – (Không bắt buộc) Một trong các giá trị: string (mặc định), number, boolean hoặc map
  • array – (Tùy chọn) Đặt thành true để cho biết giá trị có phải là một mảng 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 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 thông báo 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 thông báo 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'/>

Trường hợp 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 }
  }
}

&lt;AdditionalHeaders/Claim&gt;

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

Yêu cầ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 tiêu chuẩn đã đăng ký. Giá trị của một thông báo xác nhận quyền sở hữu bổ sung có thể là một chuỗi, một số, một boolean, một ánh xạ hoặc một mảng. Một bản đồ chỉ 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ố các loại này rõ ràng trong cấu hình chính sách hoặc gián tiếp thông qua việc 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 ánh xạ.

Kiểu mặc định là Chuỗi nếu không có kiểu nào được chỉ định.

Mảng Đặt thành true để cho biết liệu giá trị có phải là một mảng loại hay không. Mặc định: sai
Giá trị hợp lệ Bất kỳ giá trị nào mà bạn muốn sử dụng để 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 một biến luồng. Nếu có, chính sách sẽ sử dụng giá trị của đoạn mã 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ị xác nhận rõ ràng thì giá trị rõ ràng là mặc định và được dùng nếu biến luồng được tham chiếu không được giải quyết.
  • type – (Không bắt buộc) Một trong các giá trị: string (mặc định), number, boolean hoặc map
  • array – (Tùy chọn) Đặt thành true để cho biết giá trị có phải là một mảng loại hay không. Mặc định: false.

&lt;CustomClaims&gt;

Lưu ý: Hiện tại, phần tử Custom tuỳ chỉnh sẽ được chèn vào khi bạn thêm một phần tử mới Chính sách GenerateJWT thông qua giao diện người dùng. Phần tử này không hoạt động và bị bỏ qua. Chính xác để sử dụng là &lt;AdditionalClaims&gt;. Giao diện người dùng sẽ được cập nhật để chèn đúng phần tử sau này.

&lt;Id&gt;

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

Xác minh rằng JWT có yêu cầu xác nhận quyền sở hữu jti cụ thể. Khi giá trị văn bản và ref đều trống, thì chính sách sẽ tạo một jti chứa mã nhận dạng duy nhất (UUID) ngẫu nhiên. Mã JWT Thông báo xác nhận quyền sở hữu (jti) là giá trị nhận dạng duy nhất của JWT. Để biết thêm thông tin về jti, vui lòng 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ệ Có thể là một chuỗi hoặc tên của một biến luồng chứa mã nhận dạng này.

&lt;IgnoreCriticalHeaders&gt;

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Đặt thành false nếu bạn muốn chính sách hiển thị lỗi khi có bất kỳ tiêu đề nào được liệt kê trong tiêu đề crit của JWT không được liệt kê trong phần tử <KnownHeaders>. Bạn có thể đặ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 thử nghiệm và chưa sẵn sàng xử lý 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

&lt;IgnoreIssuedAt&gt;

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

Đặt thành false (mặc định) nếu bạn muốn chính sách gửi thông báo lỗi khi JWT chứa Khiếu nại iat (Được cấp lúc) chỉ định một thời điểm trong tương lai. Hãy đặt thành true để khiến chính sách này 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

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Đặt thành false nếu bạn muốn chính sách gửi thông báo lỗi khi bất kỳ biến nào được tham chiếu được chỉ định không thể giải quyết được trong chính sách. Đặt thành true để coi mọi biến không thể giải quyết 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

&lt;Issuer&gt;

<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. Thông báo xác nhận quyền sở hữu nhà phát hành JWT. Đây là một trong những tập hợp các thông báo xác nhận quyền sở hữu đã đăng ký nêu 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ỳ

&lt;KnownHeaders&gt;

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

Chính sáchGenerateJWT sử dụng phần tử <CriticalHeaders> để điền giá trị 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 tiêu đề đó có tồn tại và từng tiêu đề được liệt kê sẽ kiểm tra để đảm bảo phần tử <KnownHeaders> cũng liệt kê tiêu đề đó. Chiến lược phát hành đĩa đơn Phần tử <KnownHeaders> có thể chứa tập mẹ của các mục được liệt kê trong crit. Chỉ cần tất cả các tiêu đề được liệt kê trong crit phải được liệt kê trong Phần tử <KnownHeaders>. Bất kỳ tiêu đề nào mà chính sách tìm thấy trong crit không được liệt kê trong <KnownHeaders> sẽ khiến chính sách VerifyJWT không thành công.

Bạn có thể định cấu hình chính sách VerifyJWT để bỏ qua tiêu đề crit (không bắt buộc) 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 đó.

&lt;PublicKey/Certificate&gt;

<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 tham chiếu để 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à 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 Chứng chỉ, JWKS hoặc Phần tử giá trị.
Loại Chuỗi
Giá trị hợp lệ Biến luồng hoặc chuỗi.

&lt;PublicKey/JWKS&gt;

<!-- 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) có 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 chuẩn RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

Nếu JWT đến mang một mã khoá có trong tập hợp JWKS thì chính sách này sẽ sử dụng đúng khoá công khai để xác minh chữ ký JWT. Để biết thông tin về tính năng này, hãy xem 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, thì 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 Chứng chỉ, JWKS hoặc Phần tử giá trị.
Loại Chuỗi
Giá trị hợp lệ Biến luồng, giá trị chuỗi hoặc URL.

&lt;PublicKey/Value&gt;

<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 tham chiếu để 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 Chứng chỉ, JWKS hoặc Phần tử giá trị.
Loại Chuỗi
Giá trị hợp lệ Biến luồng hoặc chuỗi.

&lt;SecretKey/Value&gt;

<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 các thuật toán HMAC.
Loại Chuỗi
Giá trị hợp lệ

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

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ụ: private.mysecret

&lt;Source&gt;

<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ề 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 cạnh.

&lt;Subject&gt;

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

Chính sách này xác minh rằng đối tượng trong JWT khớp với chuỗi được chỉ định trong 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 các 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ể.

&lt;TimeAllowance&gt;

<TimeAllowance>120s</TimeAllowance>

"Thời gian ân hạn" thời gian. Ví dụ: nếu thời gian cho phép được thiết lậ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. Chiến lược phát hành đĩa đơn chưa hoàn tất sẽ được đánh giá tương tự. 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 có chứa giá trị. Khoảng thời gian có thể là được chỉ định 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 đượ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á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 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

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

Để 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>