Chính sách xác thực OAS

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến tài liệu về Apigee X. thông tin

Giới thiệu về chính sách OASValidation

Chính sách OASValidation (Xác thực thông số kỹ thuật OpenAPI) cho phép bạn xác thực một yêu cầu hoặc thông báo phản hồi đến bằng Thông số kỹ thuật OpenAPI 3.0 (JSON hoặc YAML). Xem bài viết Nội dung nào được xác thực?

Chính sách OASValidation chỉ định tên của Quy cách OpenAPI để sử dụng cho việc xác thực khi bước mà chính sách được đính kèm thực thi. Thông số kỹ thuật OpenAPI được lưu trữ dưới dạng tài nguyên ở vị trí tiêu chuẩn sau đây trong gói proxy API: apiproxy/resources/oas. Thông số kỹ thuật OpenAPI phải có phần mở rộng .json, .yml, .yaml.

Thêm Thông số kỹ thuật OpenAPI làm tài nguyên vào gói proxy API bằng giao diện người dùng hoặc API, như mô tả trong phần Quản lý tài nguyên.

Nội dung nào được xác thực?

Bảng sau đây tóm tắt nội dung thông báo yêu cầu được chính sách OASValidation xác thực theo thành phần.

Thành phần Yêu cầu xác thực
Đường dẫn cơ sở Xác thực đường dẫn cơ sở do proxy API xác định; bỏ qua đường dẫn cơ sở được chỉ định trong Quy cách OpenAPI.
Đường dẫn Xác thực rằng đường dẫn yêu cầu (trừ đường dẫn cơ sở) khớp với một trong các mẫu đường dẫn được xác định trong Quy cách OpenAPI.
Động từ Xác thực rằng động từ được xác định cho đường dẫn trong Thông số kỹ thuật OpenAPI.
Nội dung yêu cầu
  • Xác thực sự tồn tại của nội dung thư trong yêu cầu (nếu cần).
  • Xác thực nội dung thư theo giản đồ nội dung yêu cầu của thao tác trong Quy cách OpenAPI (không bắt buộc). Định cấu hình tuỳ chọn này bằng <ValidateMessageBody>

Lưu ý: Chính sách này chỉ xác thực phần nội dung của thông báo yêu cầu theo Thông số kỹ thuật OpenAPI nếu bạn đặt Content-Type thành application/json. Nếu bạn không đặt loại nội dung thành application/json, thì quy trình xác thực nội dung yêu cầu sẽ tự động vượt qua (mà không thực sự xác thực nội dung).

Thông số
  • Xác thực rằng các tham số bắt buộc có trong yêu cầu, bao gồm cả tham số đường dẫn, tiêu đề, truy vấn và cookie.
  • Xác thực rằng các giá trị tham số khớp với các giá trị được xác định trong Quy cách OpenAPI.
  • Xác thực xem có tham số nào trong yêu cầu không được xác định trong Quy cách OpenAPI hay không (không bắt buộc). Định cấu hình tuỳ chọn này bằng <AllowUnspecifiedParameters>

Bảng sau đây tóm tắt nội dung thông báo phản hồi được chính sách OASValidation xác thực theo thành phần.

Thành phần Xác thực phản hồi
Đường dẫn Xác thực rằng đường dẫn yêu cầu (trừ đường dẫn cơ sở) khớp với một trong các mẫu đường dẫn được xác định trong Quy cách OpenAPI.
Động từ Xác thực rằng động từ được xác định cho đường dẫn trong Thông số kỹ thuật OpenAPI.
Nội dung thư phản hồi
  • Xác thực sự tồn tại của nội dung thư trong phản hồi, nếu cần.
  • Xác thực rằng tiêu đề phản hồi trong Quy cách OpenAPI có trong thông báo phản hồi và giá trị của tiêu đề phản hồi khớp với giản đồ.
  • Xác thực phần nội dung của thông báo theo giản đồ phần nội dung phản hồi của thao tác trong Quy cách OpenAPI (không bắt buộc). Định cấu hình tuỳ chọn này bằng <ValidateMessageBody>

Mẫu

Các ví dụ sau đây cho thấy một số cách bạn có thể sử dụng chính sách OASValidation để xác thực thông báo theo Thông số kỹ thuật OpenAPI 3.0.

Xác thực thông báo yêu cầu

Trong ví dụ sau, chính sách myoaspolicy xác thực nội dung của thông báo yêu cầu dựa trên giản đồ nội dung thông báo yêu cầu của thao tác được xác định trong Thông số kỹ thuật OpenAPI my-spec.json. 

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.json</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
   <Source>request</Source>
</OASValidation>

Nếu nội dung thư không tuân thủ Quy cách OpenAPI, hệ thống sẽ trả về lỗi policies.oasvalidation.Failed.

Xác thực tham số

Ví dụ sau đây sẽ định cấu hình chính sách không thành công nếu tham số tiêu đề, truy vấn hoặc cookie được chỉ định trong yêu cầu không được xác định trong Quy cách OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Phần tử <OASValidation>

Xác định chính sách Xác thực thông số kỹ thuật OpenAPI.

Giá trị mặc định Xem thẻ Chính sách mặc định bên dưới
Bắt buộc? Bắt buộc
Loại Đối tượng phức tạp
Phần tử mẹ Không có
Phần tử con <DisplayName>
<OASResource>
<Source>
<Options>
<Source>

Cú pháp

Phần tử <OASValidation> sử dụng cú pháp sau:

<OASValidation
  continueOnError="[true|false]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All OASValidation child elements are optional except OASResource -->
    <DisplayName>policy_display_name</DisplayName>
    <OASResource>validation_JSON_or_YAML</OASResource>
    <Options>
        <ValidateMessageBody>[true|false]</ValidateMessageBody>
        <AllowUnspecifiedParameters>
            <Header>[true|false]</Header>
            <Query>[true|false]</Query>
            <Cookie>[true|false]</Cookie>
        </AllowUnspecifiedParameters>
    </Options>
    <Source>message_to_validate</Source>
</OASValidation>

Chính sách mặc định

Ví dụ sau đây cho thấy chế độ cài đặt mặc định khi bạn thêm chính sách Xác thực OAS vào luồng trong giao diện người dùng Apigee:

<OASValidation continueOnError="false" enabled="true" name="OpenAPI-Spec-Validation-1">
    <DisplayName>OpenAPI Spec Validation-1</DisplayName>
    <Properties/>
    <Source>request</Source>
    <OASResource>oas://OpenAPI-Spec-Validation-1.yaml</OASResource>
</OASValidation>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.
continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

Tham chiếu phần tử con

Phần này mô tả các phần tử con của <OASValidation>.

<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, nghe tự nhiên hơn.

Phần tử <DisplayName> là phần tử chung cho tất cả các chính sách.

Giá trị mặc định Không có
Bắt buộc? Không bắt buộc. Nếu bạn bỏ qua <DisplayName>, giá trị của thuộc tính name của chính sách sẽ được sử dụng
Loại Chuỗi
Phần tử mẹ <PolicyElement>
Phần tử con Không có

Phần tử <DisplayName> sử dụng cú pháp sau:

Cú pháp

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Ví dụ:

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

Phần tử <DisplayName> không có thuộc tính hoặc phần tử con nào.

<OASResource>

Chỉ định Quy cách OpenAPI để xác thực. Bạn có thể lưu trữ tệp này:

  • Ở phạm vi proxy API trong /apiproxy/resources/oas trong gói proxy API
  • Trong mục Resources của chế độ xem Trình điều hướng của trình chỉnh sửa proxy API.

Để biết thêm thông tin, hãy xem bài viết Quản lý tài nguyên.

Bạn có thể chỉ định Thông số kỹ thuật OpenAPI bằng cách sử dụng mẫu thông báo, chẳng hạn như {oas.resource.url}. Trong trường hợp này, giá trị của biến flow oas.resource.url (trong dấu ngoặc nhọn) sẽ được đánh giá và thay thế vào chuỗi tải trọng trong thời gian chạy. Để biết thêm thông tin, hãy xem phần Mẫu thông báo.

Giá trị mặc định Không có
Bắt buộc? Bắt buộc
Loại Chuỗi
Phần tử mẹ <OASValidation>
Phần tử con Không có

Cú pháp

Phần tử <OASResource> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau tham chiếu đến thông số kỹ thuật my-spec.yaml được lưu trữ trong /apiproxy/resources/oas trong gói proxy API:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
</OASValidation>

Phần tử <OASResource> không có thuộc tính hoặc phần tử con nào.

<Tuỳ chọn>

Định cấu hình các tuỳ chọn cho chính sách.

Giá trị mặc định Không có
Bắt buộc? Không bắt buộc
Loại Loại phức tạp
Phần tử mẹ <OASValidation>
Phần tử con <ValidateMessageBody>
<AllowUnspecifiedParameters>

Cú pháp

Phần tử <Options> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <ValidateMessageBody>[true|false]</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây định cấu hình các tuỳ chọn cho chính sách. Mỗi tuỳ chọn được mô tả chi tiết hơn ở bên dưới.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>false</ValidateMessageBody>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<ValidateMessageBody>

Chỉ định xem chính sách có xác thực phần nội dung thông báo theo giản đồ phần nội dung yêu cầu của thao tác trong Quy cách OpenAPI hay không. Đặt thành true để xác thực nội dung của phần nội dung thư. Đặt thành false để chỉ xác thực rằng phần nội dung thư tồn tại.

Bạn có thể kiểm soát việc thực thi luồng có tiếp tục sau lỗi xác thực hay không bằng cách đặt thuộc tính continueOnError cho phần tử <OASValidation> thành true.

Giá trị mặc định false
Bắt buộc? Không bắt buộc
Loại Boolean
Phần tử mẹ <Options>
Phần tử con Không có

Cú pháp

Phần tử <ValidateMessageBody> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
         <ValidateMessageBody>[true|false]</ValidateMessageBody>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây cho phép xác thực nội dung của phần nội dung thư:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <ValidateMessageBody>true</ValidateMessageBody>
   </Options>
</OASValidation>

<AllowUnspecifiedParameters>

Định cấu hình hành vi của chính sách nếu có các tham số tiêu đề, truy vấn hoặc cookie trong yêu cầu không được xác định trong Quy cách OpenAPI.

Giá trị mặc định Không có
Bắt buộc? Không bắt buộc
Loại Loại phức tạp
Phần tử mẹ <Options>
Phần tử con <Header>
<Query>
<Cookie>

Cú pháp

Phần tử <AllowUnspecifiedParameters> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
         <Query>[true|false]</Query>
         <Cookie>[true|false]</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây sẽ định cấu hình chính sách không thành công nếu tham số tiêu đề, truy vấn hoặc cookie được chỉ định trong yêu cầu không được xác định trong Quy cách OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
         <Query>false</Query>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Định cấu hình hành vi của chính sách nếu có các tham số tiêu đề trong yêu cầu không được xác định trong Quy cách OpenAPI.

Để cho phép chỉ định các tham số tiêu đề trong yêu cầu không được xác định trong Quy cách OpenAPI, hãy đặt tham số này thành true. Nếu không, hãy đặt tham số này thành false để khiến quá trình thực thi chính sách không thành công.

Giá trị mặc định true
Bắt buộc? Boolean
Loại Loại phức tạp
Phần tử mẹ <AllowUnspecifiedParameters>
Phần tử con Không có

Cú pháp

Phần tử <Header> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>[true|false]</Header>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây sẽ định cấu hình chính sách không thành công nếu một tham số tiêu đề được chỉ định trong yêu cầu không được xác định trong Quy cách OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Header>false</Header>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Query> (thành phần con của <AllowUnspecifiedParameters>)

Định cấu hình hành vi của chính sách nếu có các tham số truy vấn trong yêu cầu không được xác định trong Thông số kỹ thuật OpenAPI.

Để cho phép chỉ định các tham số truy vấn trong yêu cầu không được xác định trong Quy cách OpenAPI, hãy đặt tham số này thành true. Nếu không, hãy đặt tham số này thành false để khiến quá trình thực thi chính sách không thành công.

Giá trị mặc định true
Bắt buộc? Boolean
Loại Loại phức tạp
Phần tử mẹ <AllowUnspecifiedParameters>
Phần tử con Không có

Cú pháp

Phần tử <Query> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây định cấu hình chính sách để không thành công nếu một tham số truy vấn được chỉ định trong yêu cầu không được xác định trong Quy cách OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>false</Query>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

Định cấu hình hành vi của chính sách nếu có các tham số cookie trong yêu cầu không được xác định trong Quy cách OpenAPI.

Để cho phép chỉ định các tham số cookie trong yêu cầu không được xác định trong Quy cách OpenAPI, hãy đặt tham số này thành true. Nếu không, hãy đặt tham số này thành false để khiến quá trình thực thi chính sách không thành công.

Giá trị mặc định true
Bắt buộc? Boolean
Loại Loại phức tạp
Phần tử mẹ <AllowUnspecifiedParameters>
Phần tử con Không có

Cú pháp

Phần tử <Cookie> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Query>[true|false]</Query>
      </AllowUnspecifiedParameters>
   </Options>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây định cấu hình chính sách để không thành công nếu một tham số truy vấn được chỉ định trong yêu cầu không được xác định trong Quy cách OpenAPI.

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Options>
      <AllowUnspecifiedParameters>
         <Cookie>false</Cookie>
      </AllowUnspecifiedParameters>
   </Options>
</OASValidation>

<Source>

Thông báo JSON sẽ được đánh giá dựa trên các cuộc tấn công tải trọng JSON. Thông thường, bạn sẽ đặt giá trị này thành request, vì thường thì bạn sẽ cần đánh giá các yêu cầu đến từ ứng dụng khách. Đặt thành response để đánh giá thông báo phản hồi. Đặt thành message để tự động đánh giá thông báo yêu cầu khi chính sách được đính kèm vào luồng yêu cầu và thông báo phản hồi khi chính sách được đính kèm vào luồng phản hồi.

Giá trị mặc định request
Bắt buộc? Không bắt buộc
Loại Chuỗi
Phần tử mẹ <Source>
Phần tử con Không có

Cú pháp

Phần tử <Source> sử dụng cú pháp sau:

<OASValidation name="policy_name">
   <OASResource>oas://specname[.json|.yaml|.yml]</OASResource>
   <Source>[message|request|response]</Source>
   ...
</OASValidation>

Ví dụ:

Ví dụ sau đây tự động đánh giá thông báo yêu cầu khi chính sách được đính kèm vào luồng yêu cầu và thông báo phản hồi khi chính sách được đính kèm vào luồng phản hồi:

<OASValidation name="myoaspolicy">
   <OASResource>oas://my-spec.yaml</OASResource>
   <Source>message</Source>
</OASValidation>

Phần tử <Source> không có thuộc tính hoặc phần tử con nào.

Giản đồ

Mỗi loại chính sách được xác định bằng một lược đồ XML (.xsd). Để tham khảo, bạn có thể xem lược đồ chính sách trên GitHub.

Mã 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 Cause
steps.oasvalidation.Failed 500 Request message body cannot be validated against the provided OpenAPI Specification.
steps.oasvalidation.SourceMessageNotAvailable 500

Variable specified in the <Source> element of the policy is either out of scope or cannot be resolved.
steps.oasvalidation.NotMessageVariable 500

<Source> element is set to a variable that is not of type message.

Deployment errors

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

Error name Cause
ResourceDoesNotExist OpenAPI Specification referenced in the <OASResource> element does not exist.
ResourceCompileFailed OpenAPI Specification that is included in the deployment contains errors that prevent it from being compiled. This generally indicates that the specification is not a well-formed OpenAPI Specification 3.0.
BadResourceURL OpenAPI Specification referenced in the <OASResource> element cannot be processed. This can occur if the file is not a JSON or YAML file or the file URL is not specified correctly.

Fault variables

These variables are set when this policy triggers an error at runtime. 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 "ResourceDoesNotExist"
oasvalidation.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oasvalidation.myoaspolicy.failed = true

Các tính năng Quy cách OpenAPI được hỗ trợ

Chính sách OASValidation hỗ trợ các tính năng của Quy cách OpenAPI được tóm tắt theo danh mục trong bảng sau. Các tính năng không được hỗ trợ cũng được liệt kê.

Danh mục Có thể làm Không được hỗ trợ
Định dạng loại dữ liệu boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 tệp nhị phân
byte
mật khẩu
Đối tượng phân biệt ánh xạ
thuộc tính 		Không áp dụng
Đối tượng loại nội dung nghe nhìn giản đồ ví dụ về mã hoá
ví dụ
Đối tượng hoạt động tham số
requestBody
phản hồi
bảo mật (hỗ trợ một phần) 		lệnh gọi lại
máy chủ
không dùng nữa
Đối tượng tham số allowEmptyValue
trong (query, header, path)
bắt buộc
phản hồi
giản đồ
kiểu (deepObject, form, formmatrix, label, pipeDelimited, simple, spaceDelimited)

Lưu ý: deepObject chỉ hỗ trợ các tham số chuỗi; không hỗ trợ mảng và đối tượng lồng nhau. 		allowReserved
deprecated
example
examples
content
Đối tượng đường dẫn delete
get
head
options
parameters
patch
post
put
trace
variables 		máy chủ
Đối tượng nội dung yêu cầu application/json
application/hal+json
application/x-www-form-urlencoded (không hỗ trợ đối tượng encoding)
content
bắt buộc 		application/xml
multipart/form-data
text/plain
text/xml
Đối tượng phản hồi application/json
application/hal+json
application/x-www-form-urlencoded (không hỗ trợ đối tượng encoding)
content
tiêu đề 		application/xml
links
text/plain
text/xml
Đối tượng phản hồi mặc định
Mã trạng thái HTTP 		Không áp dụng
Đối tượng giản đồ $ref
additionalProperties (chỉ biến thể cờ boolean)
allOf (bỏ qua nếu additionalProperties là false)
anyOf
enum
exclusiveMaximum/exclusiveMinimum
format
items
maximum/minimum
maxItems/minItems
maxLength/minLength
maxProperties/minProperties
multipleOf
not
nullable
oneOf
pattern
properties
required
title
type
uniqueItems 		không dùng nữa
ví dụ
readOnly
writeOnly
xml
Đối tượng lược đồ bảo mật trong (header, query) (bỏ qua nếu type là http)
tên
loại (apiKey, http) 		luồng
bearerFormat
openIdConnectUrl
mưu đồ
Đối tượng máy chủ Biến url
 Nhiều định nghĩa máy chủ

Chủ đề có liên quan