Chính sách GenerateJWS

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Nội dung

Tạo một JWS đã ký, với một tập hợp các khai báo có thể định cấu hình. Sau đó, JWS có thể được trả về cho các ứng dụng, 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 thông tin giới thiệu chi tiết.

Để tìm hiểu về các phần của JWS và cách chúng được mã hoá và ký, hãy tham khảo RFC7515.

Video

Xem một video ngắn để tìm hiểu cách tạo JWT đã ký. Mặc dù video này dành riêng cho việc tạo JWT, nhưng nhiều khái niệm cũng tương tự đối với JWS.

Mẫu

Tạo một JWS được đính kèm và ký bằng thuật toán HS256

Chính sách mẫu này tạo ra một JWS được đính kèm và ký bằng thuật toán HS256. HS256 dựa vào một khoá bí mật dùng chung để ký và xác minh chữ ký.

Một JWS được đính kèm chứa tiêu đề, tải trọng và chữ ký được mã hoá:

header.payload.signature

Đặt <DetachContent> thành true để tạo nội dung tách biệt. Hãy xem phần Các phần của JWS/JWT để biết thêm về cấu trúc và định dạng của JWS.

Sử dụng phần tử <Payload> để chỉ định tải trọng JWS thô, chưa được mã hoá. Trong ví dụ này, một biến chứa tải trọng. Khi thao tác chính sách này được kích hoạt, Edge sẽ mã hoá tiêu đề và tải trọng JWS, sau đó thêm chữ ký đã mã hoá để ký kỹ thuật số JWS.

Cấu hình chính sách bên dưới sẽ tạo một JWS từ tải trọng có trong biến private.payload.

<GenerateJWS name="JWS-Generate-HS256">
    <DisplayName>JWS Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <Payload ref="private.payload" />
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

Tạo một JWS tách biệt được ký bằng thuật toán RS256

Chính sách mẫu này tạo một JWS tách biệt và ký bằng thuật toán RS256. Việc tạo chữ ký RS256 dựa trên khoá riêng tư RSA. Bạn phải cung cấp khoá này ở dạng được mã hoá bằng PEM.

JWS tách biệt sẽ bỏ qua tải trọng trong JWS:

header..signature

Sử dụng phần tử <Payload> để chỉ định tải trọng JWS thô, chưa được mã hoá. Khi chính sách này được kích hoạt, Edge sẽ mã hoá tiêu đề và tải trọng JWS, sau đó dùng các tiêu đề và tải trọng này để tạo chữ ký đã mã hoá. Tuy nhiên, JWS được tạo sẽ bỏ qua tải trọng. Bạn có thể truyền tải trọng đến chính sách VerifyJWS bằng cách sử dụng phần tử <DetachedContent> của chính sách VerifyJWS.

<GenerateJWS name="JWS-Generate-RS256">
    <DisplayName>JWS Generate RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Payload ref="private.payload" />
    <DetachContent>true</DetachContent>
    <OutputVariable>jws-variable</OutputVariable>
</GenerateJWS>

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

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

Thuật toán Các yếu 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>

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 bài viết Giới thiệu về các thuật toán mã hoá chữ ký.

Tài liệu tham khảo về phần tử cho Generate JWS

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

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 Mẫu để xem các ví dụ minh hoạ cấu hình cho những 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

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

Các thuộc tính sau đây là thuộc tính chung của tất cả các phần tử chính 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ể dùng các ký tự sau trong tên: A-Z0-9._\-$ %. Tuy nhiên, giao diện người dùng quản lý Edge sẽ áp dụng 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ể tuỳ ý sử dụng phần tử <displayname></displayname> để 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 khác bằng ngôn ngữ tự nhiên.

 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 thành cô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ả sau khi một 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. Chính sách này sẽ không được thực thi ngay cả khi vẫn được đính kèm vào một luồng.

 true 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

<DisplayName>

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

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

<AdditionalHeaders/Claim>

<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ị của khai báo bổ sung vào tiêu đề cho JWS.

Mặc định Không áp dụng
Sự hiện diện Không bắt buộc
Giá trị hợp lệ Mọi giá trị mà bạn muốn dùng cho một câu lệnh bổ sung. Bạn có thể chỉ định rõ ràng yêu cầu dưới dạng chuỗi, số, boolean, bản đồ 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 yêu cầu 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 biến này làm giá trị xác nhận quyền sở hữu. Nếu bạn chỉ định cả thuộc tính ref và giá trị khai báo rõ ràng, thì giá trị rõ ràng 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: chuỗi (mặc định), số, boolean hoặc bản đồ
  • array – (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.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Thêm tiêu đề quan trọng crit vào JWS. Phần đầu crit là một mảng tên phần đầu mà người nhận JWS phải biết và nhận ra. Ví dụ:

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

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

<DetachContent>

<DetachContent>true|false</DetachContent>

Chỉ định có tạo JWS bằng tải trọng tách rời (<DetachContent>true</DetachContent>) hay không (<DetachContent>false</DetachContent>).

Nếu bạn chỉ định giá trị false (mặc định), JWS được tạo sẽ có dạng:

header.payload.signature

Nếu bạn chỉ định true để tạo tải trọng tách biệt, JWS được tạo sẽ bỏ qua tải trọng và có dạng:

header..signature

Với tải trọng tách biệt, bạn có thể truyền tải trọng chưa mã hoá ban đầu đến chính sách VerifyJWS bằng cách sử dụng phần tử <DetachedContent> của chính sách VerifyJWS.

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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Chỉ định vị trí đặt JWS do chính sách này tạo. Theo mặc định, giá trị này được đặt vào biến luồng jws.POLICYNAME.generated_jws.

Mặc định jws.POLICYNAME.generated_jws
Sự hiện diện Không bắt buộc
Loại Chuỗi (tên biến của quy trình công việc)

<Payload>

<Payload ref="flow-variable-name-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

Chỉ định tải trọng JWS thô, chưa được mã hoá. Chỉ định một biến chứa tải trọng hoặc một chuỗi.

Mặc định Không áp dụng
Sự hiện diện Bắt buộc
Loại Chuỗi, mảng byte, luồng hoặc bất kỳ cách biểu thị nào khác của tải trọng JWS chưa được mã hoá.

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

Chỉ định mã khoá (kid) cần đưa vào tiêu đề JWS. 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 Không bắt buộc
Loại Chuỗi
Giá trị hợp lệ Một biến hoặc chuỗi luồng

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>PrivateKey

Nếu cần, hãy chỉ định mật khẩu mà chính sách sẽ dùng để giải mã khoá riêng tư. Sử dụng thuộc tính 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 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 Không bắt buộc
Loại Chuỗi
Giá trị hợp lệ Một 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 cấu hình chính sách không hợp lệ 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

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>PrivateKey

Chỉ định một khoá riêng tư được mã hoá dạng PEM dùng để ký JWS. Sử dụng thuộc tính 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 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 Bạn phải tạo JWS 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á riêng tư RSA được mã hoá dạng PEM.

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

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

Chỉ định giá trị nhận dạng khoá (kid) cần đưa vào tiêu đề JWS của một JWS được ký bằng thuật toán HMAC. Chỉ sử dụng khi thuật toán là một trong các thuật toán 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 biến hoặc chuỗi luồng

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/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 thuật toán 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 tối thiểu của khoá cho các thuật toán HS256/HS384/HS512. Độ dài khoá tối thiểu cho HS256 là 32 byte, cho HS384 là 48 byte và cho HS512 là 64 byte. Việc sử dụng khoá có độ mạnh thấp hơn sẽ gây ra lỗi trong 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 thuật toán HMAC.
Loại Chuỗi
Giá trị hợp lệ Một biến luồng đề cập đến một chuỗi

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

Biến luồng

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

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 rất quan trọng nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, hãy xem các bài viết Những điều bạn cần biết về lỗi về chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi thực thi chính sách.

Mã lỗi Trạng thái HTTP Xảy ra khi
steps.jws.GenerationFailed 401 Chính sách này không thể tạo JWS.
steps.jws.InsufficientKeyLength 401 Đối với khoá nhỏ hơn 32 byte đối với thuật toán HS256
steps.jws.InvalidClaim 401 Đối với thông báo xác nhận quyền sở hữu bị thiếu hoặc không khớp hoặc thiếu tiêu đề hoặc tiêu đề không khớp.
steps.jws.InvalidCurve 401 Đường cong do khoá chỉ định không hợp lệ cho thuật toán Đường cong Elliptic.
steps.jws.InvalidJsonFormat 401 Tìm thấy JSON không hợp lệ trong tiêu đề JWS.
steps.jws.InvalidPayload 401 Tải trọng JWS không hợp lệ.
steps.jws.InvalidSignature 401 <DetachedContent> bị bỏ qua và JWS có tải trọng nội dung tách rời.
steps.jws.KeyIdMissing 401 Chính sách Xác minh sử dụng JWKS làm nguồn cho khoá công khai, nhưng JWS đã ký không có thuộc tính kid trong tiêu đề.
steps.jws.KeyParsingFailed 401 Không thể phân tích cú pháp khoá công khai từ thông tin khoá đã cho.
steps.jws.MissingPayload 401 Thiếu tải trọng JWS.
steps.jws.NoAlgorithmFoundInHeader 401 Xảy ra khi JWS bỏ qua tiêu đề thuật toán.
steps.jws.SigningFailed 401 Trong GenerateJWS, đố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.jws.UnknownException 401 Đã xảy ra ngoại lệ không xác định.
steps.jws.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 Xảy ra khi
InvalidAlgorithm Các giá trị hợp lệ duy nhất là: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

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

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

Ví dụ về phản hồi khi gặp lỗi

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