Chính sách GenerateJWT

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

Tạo JWT đã ký với một tập hợp các thông báo xác nhận quyền sở hữu có thể định cấu hình. Sau đó, JWT có thể được trả về ứng dụng khách, được truyền đến các mục tiêu phụ trợ hoặc được sử dụng theo những cách khác. 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.

Video

Xem video ngắn để tìm hiểu cách tạo JWT đã ký.

Mẫu

Tạo JWT được ký bằng HS256 thuật toán

Chính sách ví dụ này tạo ra một JWT mới và ký chính sách đó bằng thuật toán HS256. Cần có HS256 về một khoá bí mật dùng chung cho cả việc ký và xác minh chữ ký.

Khi hành động theo chính sách này được kích hoạt, Edge sẽ mã hoá tiêu đề và tải trọng JWT, sau đó theo phương thức kỹ thuật số ký JWT. 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 ở đây sẽ tạo JWT với một tập hợp các thông báo xác nhận quyền sở hữu chuẩn được xác định theo thông số kỹ thuật JWT, bao gồm cả thời gian hết hạn 1 giờ cũng như một yêu cầu xác nhận bổ sung. Bạn có thể bao gồm bao nhiêu xác nhận quyền sở hữu bổ sung tùy thích. Xem tài liệu tham khảo 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 này.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

JWT kết quả sẽ có tiêu đề này ...

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

... và sẽ có một tải trọng có nội dung như sau:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

Giá trị của các thông báo xác nhận quyền sở hữu iat, exp và jti sẽ khác nhau.

Tạo JWT được ký bằng RS256 thuật toán

Chính sách ví dụ này sẽ tạo một JWT mới và ký bằng thuật toán RS256. Tạo một Chữ ký RS256 dựa trên khoá riêng tư RSA. Khoá này phải được cung cấp ở dạng mã hoá PEM. Hãy xem video ở trên để biết ví dụ đầy đủ, bao gồm cách yêu cầu chính sách.

Khi hành động theo chính sách này được kích hoạt, Edge sẽ mã hoá và ký bằng chữ ký số JWT, bao gồm cả các thông báo xác nhận quyền sở hữu. Để 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.

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

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 để tạo 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{256/384/512}* 
<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>
RS/PS/ES{256/384/512}* 
<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Các phần tử <Password> và <Id> là không bắt buộc.
*Để 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ạo JWT

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 Tạo 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ể.

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

<GenerateJWT 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 bằng 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 á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, 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

&lt;Algorithm&gt;

<Algorithm>algorithm-here</Algorithm>

Chỉ định thuật toán mã hoá để ký mã thông báo.

Mặc định Không áp dụng
Sự hiện diện Bắt buộc
Loại Chuỗi
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_containing_audience'/>

Chính sách này tạo JWT chứa thông báo xác nhận quyền sở hữu aud thành giá trị được chỉ định giá trị. Thông báo 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 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 Mảng (danh sách các giá trị được phân tách bằng dấu phẩy)
Giá trị hợp lệ Bất kỳ thông tin nào 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'/>

Cho phép bạn chỉ định thêm(các) cặp tên/giá trị xác nhận quyền sở hữu trong tải trọng của JWT. Bạn có thể chỉ định tuyên bố rõ ràng ở dạng chuỗi, số, boolean, ánh xạ hoặc mảng. Bản đồ chỉ là một tập hợp tên/giá trị cặp.

Mặc định Không áp dụng
Sự hiện diện Không bắt buộc
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. Bạn có thể chỉ định tuyên bố rõ ràng ở dạng chuỗi, số, boolean, ánh xạ hoặc mảng.

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 trong JWT đã tạo đượ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 }
  }
}

JWT được tạo bao gồm tất cả các thông báo xác nhận quyền sở hữu trong đối tượng JSON.

&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>

Đặt(các) cặp tên/giá trị xác nhận quyền sở hữu bổ sung vào tiêu đề cho JWT.

Mặc định Không áp dụng
Sự hiện diện Không bắt buộc
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. Bạn có thể chỉ định tuyên bố rõ ràng ở dạng chuỗi, số, boolean, ánh xạ hoặc mảng.

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;CriticalHeaders&gt;

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Thêm tiêu đề quan trọng, crit, vào tiêu đề JWT. Tiêu đề crit là một mảng tên tiêu đề phải được bộ nhận JWT biết và công nhận. Ví dụ:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Trong thời gian chạy, chính sách VerifyJWT sẽ kiểm tra tiêu đề crit. Đối với mỗi mục được liệt kê trong tiêu đề crit, phần tử này sẽ kiểm tra để đảm bảo rằng phần tử <KnownHeaders> của chính sách VerifyJWT cũng liệt kê tiêu đề đó. Mọi tiêu đề mà chính sách VerifyJWT 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.

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;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;ExpiresIn&gt;

<ExpiresIn>time-value-here</ExpiresIn>

Chỉ định thời gian tồn tại của JWT tính bằng mili giây, giây, phút, giờ hoặc ngày.

Mặc định N/A
Sự hiện diện Không bắt buộc
Loại Số nguyên
Giá trị hợp lệ

Giá trị hoặc tham chiếu đến biến luồng có chứa giá trị. Đơn vị thời gian có thể là được chỉ định như sau:

  • ms = mili giây (mặc định)
  • s = giây
  • m = phút
  • h = giờ
  • d = ngày

Ví dụ: ExpiresIn=10d tương đương với ExpiresIn của 864000.

&lt;Id&gt;

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

Tạo JWT với thông báo xác nhận quyền sở hữu jti cụ thể. Khi giá trị văn bản và thuộc tính ref đều là để trống, chính sách sẽ tạo một jti chứa UUID ngẫu nhiên. Thông báo xác nhận quyền sở hữu mã JWT (jti) là giá trị nhận dạng duy nhất cho 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;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 Sai
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 tạo ra một JWT chứa thông báo xác nhận quyền sở hữu có tên iss kèm theo một tập hợp giá trị thành giá trị được chỉ đị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;NotBefore&gt;

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Chỉ định thời điểm mã thông báo có hiệu lực. Mã thông báo không hợp lệ cho đến thời điểm được chỉ định. Bạn có thể chỉ định giá trị thời gian tuyệt đối hoặc thời gian tương ứng với thời điểm tạo mã thông báo.

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ệ Hãy xem nội dung bên dưới.

Giá trị thời gian hợp lệ cho phần tử NotBefore đối với các giá trị thời gian tuyệt đối

Tên Định dạng Ví dụ
có thể sắp xếp yyyy-MM-dd'T'HH:mm:ss.SSSZ 2017-08-14T11:00:21.269-0700
RFC 1123 EEE, dd MMM yyyy HH:mm:ss zzz Thứ 2, ngày 14 tháng 8 năm 2017 11:00:21 theo giờ PDT
RFC 850 EEEE, dd-MMM-yy HH:mm:ss zzz Thứ hai, 14-8-17 11:00:21 theo Giờ ban ngày Thái Bình Dương (PDT)
ANCI-C EEE MMM d HH:mm:ss yyyy Thứ 2 ngày 14 tháng 8 11:00:21 2017

Đối với các giá trị thời gian tương đối, hãy chỉ định số nguyên và khoảng thời gian, ví dụ:

  • 10 giây
  • 60 triệu
  • 12 giờ

&lt;OutputVariable&gt;

<OutputVariable>jwt-variable</OutputVariable>

Chỉ định vị trí đặt JWT do chính sách này tạo. Theo mặc định, thẻ này được đặt vào biến luồng jwt.POLICYNAME.generated_jwt.

Mặc định jwt.POLICYNAME.generated_jwt
Sự hiện diện Không bắt buộc
Loại Chuỗi (tên biến luồng)

&lt;PrivateKey/Id&gt;

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Chỉ định mã nhận dạng khoá (kid) để đưa vào tiêu đề JWT. 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.

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 chuỗi hoặc biến luồng

&lt;PrivateKey/Password&gt;

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Chỉ định mật khẩu mà chính sách sẽ sử dụng để giải mã khoá riêng tư, nếu cần. Sử dụng ref để truyền khoá trong một biến luồng. 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.

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ệ Tham chiếu biến luồng.

Lưu ý: Bạn phải chỉ định một biến luồng. Edge sẽ từ chối là không hợp lệ cấu hình chính sách trong đó mật khẩu được chỉ định ở dạng văn bản thuần tuý. Biến luồng phải có tiền tố "private". Ví dụ: private.mypassword

&lt;PrivateKey/Value&gt;

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Chỉ định một khoá riêng tư được mã hoá PEM dùng để ký JWT. Sử dụng thuộc tính ref để truyền trong một biến luồng. 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.

Mặc định Không áp dụng
Sự hiện diện Bạn phải tạo JWT bằng thuật toán RS256.
Loại Chuỗi
Giá trị hợp lệ Một biến luồng chứa một chuỗi đại diện cho giá trị khoá cá nhân RSA được mã hoá ở dạng PEM.

Lưu ý: Biến luồng phải có tiền tố "private". Ví dụ: private.mykey

&lt;SecretKey/Id&gt;

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Chỉ định mã nhận dạng khoá (kid) để đưa vào tiêu đề JWT của JWT được ký bằng HMAC thuật toán. Chỉ sử dụng khi thuật toán là HS256/HS384/HS512.

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 chuỗi hoặc biến luồng

&lt;SecretKey/Value&gt;

<SecretKey>
  <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 của HS256/HS384/HS512. Sử dụng thuộc tính ref để truyền khoá trong một biến luồng.

Edge thực thi độ mạnh khoá tối thiểu cho các thuật toán HS256/HS384/HS512. Độ dài khoá tối thiểu đối với HS256 là 32 byte, đối với HS384 là 48 byte và đối với HS512 là 64 byte. Việc sử dụng khoá có độ mạnh thấp hơn sẽ gây ra lỗi thời gian chạy.

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ệ Biến luồng tham chiếu đến một chuỗi

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

&lt;Subject&gt;

<Subject>subject-string-here</Subject>
 hoặc 
<Subject ref="flow_variable" />

Ví dụ:

<Subject ref="apigee.developer.email"/>

Chính sách này tạo JWT chứa thông báo xác nhận quyền sở hữu sub, được đặt thành giá trị được chỉ định value.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 bộ thông báo xác nhận quyền sở hữ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ể hoặc biến luồng tham chiếu đến một giá trị.

Biến luồng

Chính sách Tạo JWT không đặt biến luồng.

Tham chiếu lỗi

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Occurs when
steps.jwt.AlgorithmInTokenNotPresentInConfiguration 401 Occurs when the verification policy has multiple algorithms.
steps.jwt.AlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
steps.jwt.FailedToDecode 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.
steps.jwt.GenerationFailed 401 The policy was unable to generate the JWT.
steps.jwt.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
steps.jwt.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jwt.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jwt.InvalidJsonFormat 401 Invalid JSON found in the header or payload.
steps.jwt.InvalidToken 401 This error occurs when the JWT signature verification fails.
steps.jwt.JwtAudienceMismatch 401 The audience claim failed on token verification.
steps.jwt.JwtIssuerMismatch 401 The issuer claim failed on token verification.
steps.jwt.JwtSubjectMismatch 401 The subject claim failed on token verification.
steps.jwt.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a kid property in the header.
steps.jwt.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jwt.NoAlgorithmFoundInHeader 401 Occurs when the JWT contains no algorithm header.
steps.jwt.NoMatchingPublicKey 401 The Verify policy uses a JWKS as a source for public keys, but the kid in the signed JWT is not listed in the JWKS.
steps.jwt.SigningFailed 401 In GenerateJWT, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jwt.TokenExpired 401 The policy attempts to verify an expired token.
steps.jwt.TokenNotYetValid 401 The token is not yet valid.
steps.jwt.UnhandledCriticalHeader 401 A header found by the Verify JWT policy in the crit header is not listed in KnownHeaders.
steps.jwt.UnknownException 401 An unknown exception occurred.
steps.jwt.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidNameForAdditionalClaim The deployment will fail if the claim used in the child element <Claim> of the <AdditionalClaims> element is one of the following registered names: kid, iss, sub, aud, iat, exp, nbf, or jti.
InvalidTypeForAdditionalClaim If the claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
MissingNameForAdditionalClaim If the name of the claim is not specified in the child element <Claim> of the <AdditionalClaims> element, the deployment will fail.
InvalidNameForAdditionalHeader This error ccurs when the name of the claim used in the child element <Claim> of the <AdditionalClaims> element is either alg or typ.
InvalidTypeForAdditionalHeader If the type of claim used in the child element <Claim> of the <AdditionalClaims> element is not of type string, number, boolean, or map, the deployment will fail.
InvalidValueOfArrayAttribute This error occurs when the value of the array attribute in the child element <Claim> of the <AdditionalClaims> element is not set to true or false.
InvalidConfigurationForActionAndAlgorithm If the <PrivateKey> element is used with HS Family algorithms or the <SecretKey> element is used with RSA Family algorithms, the deployment will fail.
InvalidValueForElement If the value specified in the <Algorithm> element is not a supported value, the deployment will fail.
MissingConfigurationElement This error will occur if the <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
InvalidKeyConfiguration If the child element <Value> is not defined in the <PrivateKey> or <SecretKey> elements, the deployment will fail.
EmptyElementForKeyConfiguration If the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements is empty or unspecified, the deployment will fail.
InvalidVariableNameForSecret This error occurs if the flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidSecretInConfig This error occurs if the child element <Value> of the <PrivateKey> or <SecretKey> elements does not contain the private prefix (private.).
InvalidTimeFormat If the value specified in the<NotBefore> element does not use a supported format, the deployment will fail.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "TokenExpired"
JWT.failed All JWT policies set the same variable in the case of a failure. JWT.failed = true

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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