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

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

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

Chính sách OASValidation (Xác thực theo quy cách OpenAPI) cho phép bạn xác thực một thông báo yêu cầu hoặc phản hồi đến dựa trên Quy cách OpenAPI 3.0 (JSON hoặc YAML). Xem Nội dung nào được xác thực?

Chính sách OASValidation chỉ định tên của OpenAPI Specification dùng để xác thực khi bước mà chính sách được đính kèm thực thi. OpenAPI Specification đượ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. Quy cách OpenAPI phải có tiện ích .json, .yml, .yaml.

Thêm một OpenAPI Specification 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 xác thực theo chính sách OASValidation, theo thành phần.

Thành phần Yêu cầu xác thực
Basepath Xác thực đường dẫn cơ sở do API proxy 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ừ basepath) khớp với một trong các mẫu đường dẫn được xác định trong OpenAPI Specification.
Độ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ư 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).
  • Bạn có thể xác thực nội dung thông báo dựa trên giản đồ nội dung yêu cầu của thao tác trong Đặc tả OpenAPI. Định cấu hình lựa chọn này bằng cách sử dụng <ValidateMessageBody>

Lưu ý: Chính sách này chỉ xác thực nội dung thông báo yêu cầu dựa trên OpenAPI Specification nếu Content-Type được đặt thành application/json. Nếu loại nội dung không được đặt thành application/json, thì quá trình xác thực nội dung thông báo yêu cầu sẽ tự động chuyển (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 OpenAPI Specification.
  • 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 lựa chọn này bằng cách sử dụng <AllowUnspecifiedParameters>

Bảng sau đây tóm tắt nội dung thông báo phản hồi được xác thực theo chính sách OASValidation, 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ừ basepath) khớp với một trong các mẫu đường dẫn được xác định trong OpenAPI Specification.
Độ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ông báo 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 các tiêu đề phản hồi trong Đặc tả 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 đồ.
  • Bạn có thể xác thực nội dung thư dựa trên giản đồ nội dung phản hồi của thao tác trong Đặc tả OpenAPI. Định cấu hình lựa chọn này bằng cách sử dụng <ValidateMessageBody>

Mẫu

Các ví dụ sau đây minh hoạ 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 dựa trên một 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 đây, chính sách myoaspolicy xác thực nội dung của thông báo yêu cầu dựa vào 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, thì lỗi policies.oasvalidation.Failed sẽ được trả về.

Xác thực các tham số

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ố tiêu đề, truy vấn hoặc cookie được chỉ định trong yêu cầu không được xác định trong Đặc tả 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 quy cách 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 các chế độ cài đặt mặc định khi bạn thêm chính sách Xác thực OAS vào quy trình của mình 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.

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

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

<DisplayName>

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value n/a
Required? Optional. If you omit <DisplayName>, the value of the policy's name attribute is used
Type String
Parent Element <PolicyElement>
Child Elements None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

<OASResource>

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

  • Tại phạm vi proxy API trong /apiproxy/resources/oas trong gói proxy API
  • Trong phần 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 phần Quản lý tài nguyên.

Bạn có thể chỉ định Đặc tả OpenAPI bằng một 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 luồng 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 tin nhắn.

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 đây tham chiếu đến quy cách 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.

<Options> (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 lựa chọn cho chính sách. Mỗi lựa 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ó nên xác thực nội dung thông báo dựa trên giản đồ nội dung yêu cầu của thao tác trong Đặc tả 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ông báo:

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

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 định cấu hình chính sách để không thành công nếu một 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 Đặc tả 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 Thông số kỹ thuật 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 đị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 OpenAPI Specification.

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

<Query> (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 Đặc tả 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 Thông số kỹ thuật 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 Đặc tả 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 Thông số kỹ thuật 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 bằ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 sẽ 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.

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 được hỗ trợ trong Quy cách OpenAPI

Chính sách OASValidation hỗ trợ các tính năng của OpenAPI Specification được tóm tắt trong bảng sau, theo danh mục. 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 kiểu dữ liệu boolean
date
date-time
double
email
float
int32/int64
ipv4/ipv6
md5
sha1/sha256/sha512
string
uri
uri-template
uuid
 binary
byte
password
Đối tượng phân biệt mapping
propertyName 		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 Operations parameters
requestBody
responses
security (hỗ trợ một phần) 		callbacks
deprecated
servers
Đối tượng tham số allowEmptyValue
in (query, header, path)
required
responses
schema
style (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
required 		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
headers 		application/xml
links
text/plain
text/xml
Đối tượng phản hồi default
Mã trạng thái HTTP 		Không áp dụng
Đối tượng giản đồ $ref
additionalProperties (chỉ có biến thể cờ boolean)
allOf (bị 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 		deprecated
example
readOnly
writeOnly
xml
Đối tượng lược đồ bảo mật trong (header, query) (bị bỏ qua nếu type là http)
name
type (apiKey, http) 		bearerFormat
flows
openIdConnectUrl
scheme
Đối tượng máy chủ url
variables 		Nhiều định nghĩa về máy chủ

Chủ đề có liên quan