Chính sách GenerateJWS

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 một JWS đã ký kèm theo 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 đó, JWS có thể được trả về cho ứng dụng khách, được truyền đến các mục tiêu phụ trợ hoặc được dùng theo các cách khác. 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.

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

Video

Xem video ngắn để tìm hiểu cách tạo JWT có chữ 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 giống nhau cho JWS.

Mẫu

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

Chính sách mẫu này tạo ra một JWS đính kèm và ký JWS 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 đính kèm có 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. Xem phần Các phần của JWS/JWT để biết thêm thông tin 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 hành động 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ý JWS dưới dạng kỹ thuật số.

Cấu hình chính sách bên dưới sẽ tạo một JWS từ mộ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 rời được ký bằng thuật toán RS256

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

Một JWS có thể tách rời bỏ qua tải trọng khỏi 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 đó sử dụng chúng để tạo chữ ký được mã hoá. Tuy nhiên, JWS được tạo lại bỏ qua tải trọng. Bạn có thể tuỳ ý chuyển tải trọng dữ liệu tới 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 thành phần 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ư minh hoạ trong bảng sau:

Thuật toán Các thành phần 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 quan trọng, hãy xem bài viết Giới thiệu về thuật toán mã hoá chữ ký.

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

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

<GenerateJWS name="JWS" 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>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> (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>

Đặ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 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ệ 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. Bạn có thể chỉ định rõ ràng thông báo dưới dạng chuỗi, số, boolean, tệp á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 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.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Thêm tiêu đề quan trọng, crit, vào JWS. Tiêu đề crit là một dãy tên tiêu đề mà bộ thu JWS phải biết và nhận dạng. Ví dụ:

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

Trong thời gian chạy, chính sáchVerifyJWS kiểm tra tiêu đề crit. Đối với mỗi tiêu đề được liệt kê trong tiêu đề crit, hệ thống 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 mà cũng không được liệt kê 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ảng hoặc tên của biến chứa mảng đó.

<DetachContent>

<DetachContent>true|false</DetachContent>

Chỉ định xem có tạo JWS với tải trọng tách rời <DetachContent>true</DetachContent> hay không, <DetachContent>false</DetachContent>.

Nếu bạn chỉ định false, thì theo 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 có thể tách rời, thì JWS được tạo sẽ bỏ qua tải trọng và có dạng:

header..signature

Với tải trọng có thể tách rời, bạn có thể chuyển tải trọng gốc chưa mã hoá sang chính sáchVerifyJWS 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 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

<OutputVariable>

<OutputVariable>JWS-variable</OutputVariable>

Chỉ định vị trí đặt JWS do chính sách này tạo. Theo mặc định, thuộc tính 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 luồng)

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

Chỉ định tải trọng JWS thô, chưa mã hoá. Chỉ định một biến chứa tải trọng (payload) 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ỳ nội dung biểu diễn nào khác của tải trọng JWS chưa được mã hoá.

<PrivateKey/Id>

<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 đề JWS. 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 Không bắt buộc
Loại Chuỗi
Giá trị hợp lệ Chuỗi hoặc biến luồng

<PrivateKey/Password>

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

Chỉ định mật khẩu mà chính sách nên sử dụng để giải mã khoá riêng tư, nếu cần. Sử dụng thuộc tính ref để truyền khoá vào một biến luồng. 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 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 một cấu hình chính sách không hợp lệ, trong đó mật khẩu được chỉ định dưới dạng văn bản thuần tuý. Biến luồng phải có tiền tố "private" (riêng tư). Ví dụ: private.mypassword

<PrivateKey/Value>

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

Chỉ định một khoá riêng tư được mã hoá PEM dùng để ký JWS. Hãy sử dụng thuộc tính tham chiếu để truyền khoá vào một biến luồng. 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 Cần để tạo JWS bằng thuật toán RS256.
Loại Chuỗi
Giá trị hợp lệ Biến luồng chứa một chuỗi đại diện cho giá trị khoá riêng tư RSA được mã hoá 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-here"/>
</SecretKey>

or

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

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

<SecretKey/Value>

<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 trong các mã HS256/HS384/HS512. Sử dụng thuộc tính ref để truyền khoá vào 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 của HS256 là 32 byte, 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 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 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 một biến luồng, biến đó phải có tiền tố "riêng tư". 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 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"
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 xảy ra lỗi. jws.JWS-Policy.failed = true

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

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