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ý, 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 đó, JWS 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.

Để 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 đã ký. Trong khi video này đang để tạo JWT, nhiều khái niệm cũng giống nhau đối với JWS.

Mẫu

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

Chính sách ví dụ này tạo một JWS đính kèm và ký JWS 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ý.

Một JWS đí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 rời. Xem 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 mã hoá. Trong ví dụ này, một biến chứa tải trọng. Khi hành động theo chính sách này được kích hoạt, Edge mã hoá tiêu đề và tải trọng JWS, sau đó thêm chữ ký được mã hoá để ký JWS theo hình thức điện tử.

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 RS256 thuật toán

Chính sách trong ví dụ này tạo ra một JWS tách biệt và ký JWS 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.

Một JWS đã tách rời bỏ qua trọng tải khỏi JWS:

header..signature

Sử dụng phần tử <Payload> để chỉ định tải trọng JWS thô, chưa 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. rồi sử dụng chúng để tạo chữ ký mã hoá. Tuy nhiên, JWS đã tạo sẽ bỏ qua phần tải trọng này. Bạn có tùy thuộc vào việc 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 thành phần chính

Các phần tử mà bạn dùng để chỉ định khoá dùng để tạo JWS 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 JWS

Tài liệu tham khảo chính sách này mô tả các thành phần 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 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

<GenerateJWS name="JWS" 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;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 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 để 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 JWS. Tiêu đề crit là một mảng tên tiêu đề mà bộ nhận 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 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 liệt kê trong <KnownHeaders> sẽ 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 đó.

&lt;DetachContent&gt;

<DetachContent>true|false</DetachContent>

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

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

header.payload.signature

Nếu bạn chỉ định đúng để tạo tải trọng tách rời, thì JWS đã tạo sẽ bỏ qua tải trọng này và có dạng như sau:

header..signature

Với một tải trọng đã tách, bạn có thể chọn truyền tải trọng chưa mã hoá ban đầu đến chính sáchVerifyJWS bằng cách 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

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

<OutputVariable>JWS-variable</OutputVariable>

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

&lt;Payload&gt;

<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 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 đại diện nào khác của tải trọng JWS chưa mã hoá.

&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á (con) để đưa vào tiêu đề JWS. 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ý JWS. 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 Cầ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á 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á (con) để đưa vào tiêu đề JWS của JWS đượ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

Biến luồng

Chính sách Tạo JWS không đặt 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>