Chính sách Xác minh JWS

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 JWS 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 tiêu đề thành các biến ngữ cảnh để các chính sách hoặc điều kiện tiếp theo có thể kiểm tra các giá trị đó nhằm đưa ra quyết định uỷ quyền hoặc định tuyến. 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.

Nếu JWS đã được xác minh và hợp lệ thì yêu cầu sẽ được phép tiếp tục. Nếu không thể xác minh chữ ký JWS hoặc nếu JWS không hợp lệ do một số loại lỗi, thì mọi quá trình xử lý sẽ dừng và lỗi sẽ được trả về trong phản hồi.

Để 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 một video ngắn để tìm hiểu cách xác minh chữ ký trên JWS. Mặc dù video này dành riêng cho việc xác minh JWT, nhưng nhiều khái niệm giống nhau đối với JWS.

Mẫu

• Xác minh một JWS đính kèm được ký bằng thuật toán HS256
• Xác minh một JWS đã tách rời được ký bằng thuật toán RS256

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

Chính sách ví dụ này xác minh một JWS đính kèm đã được ký bằng thuật toán mã hoá HS256, HMAC bằng giá trị tổng kiểm SHA-256. JWS được truyền vào yêu cầu proxy bằng cách sử dụng tham số biểu mẫu có tên JWS. Khoá này nằm trong biến có tên private.secretkey.

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

header.payload.signature

Cấu hình chính sách bao gồm thông tin mà Edge cần để giải mã và đánh giá JWS, chẳng hạn như nơi tìm JWS (trong biến luồng được chỉ định trong phần tử <Source>), thuật toán ký bắt buộc và 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 chẳng hạn).

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

Chính sách này ghi đầu ra 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 phần Biến luồng để biết danh sách các biến do chính sách này đặt.

Xác minh một JWS đã tách rời được ký bằng thuật toán RS256

Chính sách ví dụ này xác minh một JWS đã tách rời và được ký bằng thuật toán RS256. Để xác minh, bạn cần cung cấp khoá công khai. JWS được truyền vào yêu cầu proxy bằng cách sử dụng tham số biểu mẫu có tên JWS. Khoá công khai nằm trong biến có tên public.publickey.

Một JWS có thể tách rời bỏ qua tải trọng khỏi JWS:

header..signature

Bạn có thể tuỳ ý chuyển tải trọng tới chính sách VerifyJWS bằng cách chỉ định tên biến chứa tải trọng cho phần tử <DetachedContent>. Nội dung chỉ định trong <DetachedContent> phải ở dạng ban đầu chưa mã hoá khi chữ ký JWS được tạo.

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

Chính sách này ghi đầu ra 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 phần Biến luồng để biết danh sách các biến do chính sách này đặt.

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

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

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

Tham chiếu phần tử

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 Xác minh 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

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

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

<Algorithm>

<Algorithm>HS256</Algorithm>

Chỉ định thuật toán mã hoá để ký mã thông báo. Thuật toán RS*/PS*/ES* sử dụng một cặp khoá công khai/bí mật, trong khi thuật toán HS* sử dụng một cặp khoá bí mật dùng chung. Xem thêm bài viết Giới thiệu về 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ì các thuật toán này yêu cầu một loại khoá cụ thể. Bạn có thể kết hợp thuật toán RS* và PS*.

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

Xác thực rằng tiêu đề JWS chứa(các) cặp giá trị/tên xác nhận bổ sung được chỉ định và các giá trị xác nhận quyền sở hữu đã xác nhận khớp với nhau.

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

<DetachedContent>

<DetachedContent>variable-name-here</DetachedContent>

JWS được tạo với tải trọng nội dung có dạng:

header.payload.signature

Nếu bạn sử dụng GenerateJWS chính sách để tạo tải trọng có thể tách, thì JWS được tạo sẽ bỏ qua tải trọng và có dạng:

header..signature

Đối với tải trọng có thể tách rời, bạn có thể chuyển tải trọng đó tới chính sách VerifyJWS bằng cách sử dụng phần tử <DetachedContent>. Tải trọng nội dung được chỉ định phải ở dạng ban đầu chưa mã hoá khi chữ ký JWS được tạo.

Chính sách này sẽ báo lỗi khi:

• <DetachedContent> được chỉ định khi JWS không chứa tải trọng nội dung có thể tách rời (mã lỗi là steps.jws.ContentIsNotDetached).
• <DetachedContent> bị bỏ qua và JWS có tải trọng nội dung tách rời (mã lỗi là steps.jws.InvalidSignature).

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

Đặt thành false nếu bạn muốn chính sách báo lỗi khi có bất kỳ tiêu đề nào trong tiêu đề crit của JWS không có trong phần tử <KnownHeaders>. Đặt thành true để chính sách VerifyJWS bỏ qua tiêu đề crit.

Một lý do để đặt phần tử này thành true (đúng) là nếu bạn đang trong môi trường thử nghiệm và bạn không muốn chính sách này không hoạt động do thiếu tiêu đề.

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

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

Chính sáchGenerateJWS sử dụng phần tử <CriticalHeaders> để điền tiêu đề crit vào mã thông báo. Ví dụ:

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

Chính sách VerifyJWS kiểm tra tiêu đề crit trong JWS nếu có. Đối với mỗi mục được liệt kê, chính sách sẽ kiểm tra để đảm bảo rằng phần tử <KnownHeaders> cũng liệt kê tiêu đề đó. Phần tử <KnownHeaders> có thể chứa tập mẹ của các mục được liệt kê trong crit. Điều cần thiết là tất cả tiêu đề được liệt kê trong crit phải được liệt kê trong phần tử <KnownHeaders>. Nếu bất kỳ tiêu đề nào mà chính sách này tìm thấy trong crit nhưng không cũng không được liệt kê trong <KnownHeaders>, thì chính sách VerifyJWS sẽ không thành công.

Bạn có thể tuỳ ý định cấu hình chính sách VerifyJWS để bỏ qua tiêu đề crit bằng cách đặt phần tử <IgnoreCriticalHeaders> thành true.

<PublicKey/JWKS>

<!-- 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) 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 giá trị RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

Nếu JWS đến có mã nhận dạng khoá có trong tập hợp JWKS, thì chính sách này sẽ sử dụng khoá công khai chính xác để xác minh chữ ký JWS. Để biết thông tin chi tiết về tính năng này, hãy xem bài viết Sử dụng Bộ khoá web JSON (JWKS) để xác minh JWS.

Nếu bạn tìm nạp giá trị từ một URL công khai, 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.

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickey"/>
</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 dùng để xác minh chữ ký trên JWS. Hãy sử dụng thuộc tính ref để truyền khoá vào 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 loại RS256/RS384/RS512, PS256/PS384/PS512 hoặc ES256/ES384/ES512.

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

<Nguồn>

<Source>JWS-variable</Source>

Nếu có, hãy chỉ định biến luồng mà chính sách dự kiến sẽ tìm JWS để xác minh.

Biến luồng

Sau khi thành công, các chính sách Verify JWS (Xác minh JWS) và Decode JWS (Giải mã JWS) sẽ đặt các biến ngữ cảnh theo mẫu sau:

jws.{policy_name}.{variable_name}

Ví dụ: nếu tên chính sách là verify-jws, thì chính sách sẽ lưu trữ thuật toán được chỉ định trong JWS vào biến ngữ cảnh này: jws.verify-jws.header.algorithm

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

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.

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.

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>