7.6. 部署 3scale API Management OpenAPI 自定义资源


OpenAPI 自定义资源(CR)是导入 OpenAPI 规格(OAS)文档的一种方法,您可以在 Developer Portal 中用于 ActiveDocs。OAS 是一个标准,不会将您绑定到使用与 API 使用一个特定的编程语言。人工和计算机可以更轻松地了解 API 产品的功能,而无需源代码访问、文档或网络流量检查。

先决条件

  • 具有 3scale 2.14 On-Premises 实例的管理员特权的用户帐户。
  • 定义 API 的 OAS 文档。
  • 了解 OpenAPI CR 如何与租户链接。
  • apiKeyopenIdConnect/oauth2 是支持的安全方案。

OpenID Connect 和 OAuth2 限制

要在 OpenAPI 规格中配置 3scale,您必须在 OpenAPI 自定义资源(CR)中提供以下数据:

  • OpenID Connect (OIDC) issuerType:

    • 定义签发者类型,默认为 rest。您可以在 OpenAPI CR 中覆盖此参数。
  • issuerEndpoint 定义为普通值 URL,或使用 issuerEndpoint URL 定义 issuerEndpointRef secret。

  • 流对象:

    • 当您定义 oauth2 安全方案时,OpenAPI 文档包含流。但是,当安全方案是 OpenID Connect 时,OpenAPI 文档不提供流。在这种情况下,OpenAPI CR 可以提供它们。

7.6.1. 部署 3scale OpenAPI 自定义资源,从 secret 中导入 OAS 文档

部署 OpenAPI 自定义资源 (CR),以便您可以创建 3scale 后端产品

注意

Operator 只读取 secret 中的内容。Operator 不读取 secret 中的字段名称。

流程

  1. 定义包含 OAS 文档的 secret。例如,您可以使用以下内容创建 myoasdoc1.yaml

    openapi: "3.0.2"
    info:
      title: "some title"
      description: "some description"
      version: "1.0.0"
    paths:
      /pet:
        get:
          operationId: "getPet"
          responses:
            405:
              description: "invalid input"
  2. 创建 secret.例如:

    $ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml
    
    secret/myoasdoc1 created
  3. 定义 OpenAPI CR。确保指定包含 OAS 文档的 secret 的引用。例如,您可以创建 myopenapicr1.yaml 文件:

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: myopenapicr1
    spec:
      openapiRef:
        secretRef:
          name: myoasdoc1
  4. 创建您刚刚定义的资源。例如:

    $ oc create -f myopenapicr1.yaml

    对于给定示例,输出为:

    $ openapi.capabilities.3scale.net/myopenapicr1 created

7.6.2. 3scale API Management OpenAPI 自定义资源定义的功能

了解 OpenAPI 自定义资源定义(CRD)部署功能将有助于您配置 3scale 产品、后端并为开发者门户创建 ActiveDocs。

  • OAS 文档可以从以下项读取:

    • Kubernetes secret。
    • http 和 https 格式的 URL。
  • 在 OAS 文档中,info.title 设置不能超过 215 个字符。Operator 使用此设置来创建 OpenShift 对象名称,其长度限制。
  • 只有服务器列表中的第一个 server[0].url 元素将解析为私有 URL。OpenAPI 规格(OAS)使用其 server[0].url 元素的 basePath 组件。
  • OpenAPI CRD 支持单个顶层安全要求,但它不支持操作级别的安全性。
  • OpenAPI CRD 支持 apiKeyopenIdConnect/oauth2 安全方案。

7.6.3. 定义 OpenAPI 自定义资源时导入规则

导入规则指定当为 3scale 部署设置 OpenAPI 文档时,OpenAPI 规格(OAS)如何与 3scale 一起工作。

产品名称

默认产品系统名称通过 OpenAPI 文档中的 info.title 字段获取。要覆盖 OpenAPI 文档中的产品名称,在 OpenAPI 自定义资源(CR)中指定 spec.productSystemName 字段。

私有基本 URL

私有基础 URL 从 OpenAPI CR servers[0].url 字段读取。您可以使用 OpenAPI CR 中的 spec.privateBaseURL 字段来覆盖它。

3scale 方法

导入 OpenAPI 文档中定义的每个操作都会转换为产品级别的一个 3scale 方法。方法名称从操作对象的 operationId 字段读取。

3scale 映射规则

导入 OpenAPI 文档中定义的每个操作都会转换为产品级别的 3scale 映射规则。以前,现有映射规则由使用 OpenAPI CR 导入的用户替代。

在 OpenAPI 文档中,paths 对象提供了用于操作动词和模式属性的映射规则。3scale 方法相应地与 operationId 关联。

delta 值硬编码为 1

默认情况下配置严格匹配策略。可以使用 OpenAPI CRD 的 spec.PrefixMatching 字段切换到前缀匹配

身份验证

只支持一个顶级安全要求。不支持操作级别的安全要求。

支持的安全方案是 apiKey

apiKey 安全方案类型:

  • 凭证位置 将从安全方案对象的 in 字段中的 OpenAPI 文档读取。
  • Auth user 键将从安全方案对象的 OpenAPI 文档的 name 字段中读取。

以下是 OAS 3.0.2 部分带有 apiKey 安全要求的部分示例:

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header

当 OpenAPI 文档没有指定任何安全要求时,会应用以下内容:

  • 产品身份验证将为 apiKey 配置。
  • 凭证位置 将默认为 3scale 值 As query parameters (GET) or body parameters (POST/PUT/DELETE)
  • Auth user 密钥默认为 3scale 值 user_key

3scale Authentication Security 可以使用 OpenAPI CRD 的 spec.privateAPIHostHeaderspec.privateAPISecretToken 字段来设置。

ActiveDocs

不会创建 3scale ActiveDoc。

3scale 产品策略链

3scale 策略链是默认 3scale 创建的。

3scale 部署模式

默认情况下,配置的 3scale 部署模式将为 APIcast 3scale 管理。但是,当 spec.productionPublicBaseURLspec.stagingPublicBaseURL 或两个字段都位于 OpenAPI CR 中时,产品的部署模式是 APIcast 自我管理的。

带有自定义公共基础 URL 的 OpenAPI CR 示例:

apiVersion: capabilities.3scale.net/v1beta1
kind: OpenAPI
metadata:
  name: openapi1
spec:
  openapiRef:
    url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
  productionPublicBaseURL: "https://production.my-gateway.example.com"
  stagingPublicBaseURL: "https://staging.my-gateway.example.com"

7.6.4. 配置 OpenID Connect 和 OAuth2

Red Hat 3scale API Management 需要没有包括在 OpenAPI 规格(OAS)中的附加信息。您必须在 OpenAPI 自定义资源(CR)中提供此信息,特别是:

  • OpenID Connect Issuer Type

    默认为 rest,但可以从 OpenAPI CR 覆盖。

  • OpenID Connect Issuer Endpoint Reference (Secret)

    3scale 要求签发者 URL 包含客户端 secret。

  • 流对象

    当安全方案是 OAuth2 时,流由 OpenAPI 文档提供。但是,对于 OpenID Connect (OIDC)安全方案,OpenAPI 文档不提供流。

    OIDC 有 4 个流参数:

    • standardFlowEnabled
    • implicitFlowEnabled
    • serviceAccountsEnabled
    • directAccessGrantsEnabled.

OIDC 签发者 secret

  • 您之前已设置 Issuer Client。RHSSO/keycloak 域和客户端在 secret 示例中使用它。
  • issuerEndpoint 格式为 https://<client-id>:<client-secret>@<host>:<port>/auth/realms/<realm-name>。格式在 3scale 门户/产品页面中描述 - AUTHENTICATION SETTINGS - OpenID Connect Issuer
  • <client-secret> 值从 Realm/Clients/ClientID/Credentials/Secret 中的 Issuer Client 获取。

流程

  1. 使用以下内容创建 secret,如 my-secret.yaml

    kind: Secret
    apiVersion: v1
    metadata:
      name: my-secret
      namespace: 3scale-test
    data:
      issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore
    type: Opaque
  2. 使用以下命令应用 secret:

    $ oc apply -f my-secret.yaml
  3. 为 OIDC 和 OAuth2 创建 OpenAPI CR,如 openapi-example.yaml,其内容如下:

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      generation: 1
      name: openapi-example
    spec:
      openapiRef:
        url: "https://example.com/petstore.yaml"
      privateAPISecretToken: "xxxx"
      oidc:
        issuerType: keycloak
        issuerEndpointRef:
          name: my-secret
        jwtClaimWithClientID: azp
        jwtClaimWithClientIDType: plain
        authenticationFlow:
          standardFlowEnabled: true
          implicitFlowEnabled: true
          serviceAccountsEnabled: true
          directAccessGrantsEnabled: true
        gatewayResponse:
          errorStatusAuthFailed: 403
  4. 使用以下命令为 OIDC 和 OAuth2 应用 OpenAPI CR:

    $ oc apply -f <openapi-cr-file>.yaml
注意
  • OIDC 字段在 OpenAPI CR 中是可选的,仅适用于 OpenID Connect。
  • issuerEndpointRef 应该引用包含 issuerEndpoint的 secret
表 7.1. OIDC 规格字段描述

字段

必需

描述

issuerType

有效值: [keycloak,rest]。默认为 rest

issuerEndpoint

issuerEndpoint 可以在 issuerEndpointRef 或 plain 值中定义。此端点的格式在 OpenID 供应商设置上决定。对于 Red Hat single sign-on: https://<client-id>:<client-secret>@<host>:<port>/auth/realms/<realm-name>

issuerEndpointRef

包含 issuerEndpoint 的 secret。

jwtClaimWithClientID

带有包含 clientID 的 ClientID 的 JSON Web 令牌(JWT)声明。默认为 azp

jwtClaimWithClientIDType

jwtClaimWithClientIDType 设置,以处理 ClientID Token Claim 值作为字符串或作为 liquid 模板。有效值: plain, liquid。默认值为 plain

authenticationFlow

流对象:当安全方案为 OAuth2 时,流由 OpenAPI 文档提供。但是,对于 OIDC 安全方案,OpenAPI 文档不提供流。在这种情况下,OpenAPI CR 可以提供这些 CR。OIDC 只有 4 个流参数: standardFlowEnabled,implicitFlowEnabled,serviceAccountsEnabled,directAccessGrantsEnabled

gatewayResponse

指定错误的自定义网关响应。请参阅 GatewayResponseSpec

  • 在 OIDC 规格中定义 issuerEndpointRefissuerEndpoint,但您可以定义这两个字段。
  • 如果在 CR 中定义 issuerEndpoint 普通值,它将优先于 issuerEndpointRef secret。
  • issuerEndpoint 的格式在 OpenID 提供程序设置上决定:

    • 在 3scale 管理门户中,导航到 [Your_product_name] > Integration > Settings。在 Authentication 下,单击 OpenID Connect Issuer 选项。检查 OpenID Connect Issuer 类型

      • 以下是一个 OpenAPI CR 示例,其中 issuerEndpoint 定义为 plain value 和 secret。使用 plain 值:

        apiVersion: capabilities.3scale.net/v1beta1
        kind: OpenAPI
        metadata:
          generation: 1
          name: openapi-example
        spec:
          openapiRef:
            url: "https://example.com/petstore.yaml"
          oidc:
            issuerType: keycloak
            issuerEndpoint: https://3scale-zync:some-secret@keycloak-rhsso-test.example.com/auth/realms/petstore
            issuerEndpointRef:
              name: my-secret
            jwtClaimWithClientID: azp
            jwtClaimWithClientIDType: plain
            authenticationFlow:
              standardFlowEnabled: true
              implicitFlowEnabled: true
              serviceAccountsEnabled: true
              directAccessGrantsEnabled: true
  • 如果 OpenAPI CR 规格是 OIDC,但 OAS 中的 securitySchemes 类型是 oauth2,则 CR OIDC Authentication Flows 参数将被忽略,产品 OIDC Authentication Flows 将被设置为与 OAS 中定义的 oauth2 流匹配:

    • standardFlowEnabled is true if OAuth2 authorizationCode is defined
    • 如果定义了 OAuth2 隐式,则 implicit FlowEnabled 为 true
    • 如果定义了 OAuth2 客户端Credentials,则 serviceAccountsEnabled 为 true
    • 如果定义了 OAuth2 密码,则 directAccessGrantsEnabled 为 true

      OAS securitySchemes 定义示例,允许选择所有产品 OIDC 身份验证流。注: 在 OpenAPI CR 中定义 OIDC :

      securitySchemes:
        myOauth:
          description: This API uses OAuth 2 with the implicit grant flow.
            link:https://api.example.com/docs/auth:[More information]
          flows:
            password:
              scopes:
                read_pets: read your pets
                write_pets: modify pets in your account
              tokenUrl: https://api.example.com/oauth2/token
            implicit:
              authorizationUrl: https://example.com/api/oauth/dialog
              scopes:
                write_pets: modify pets in your account
                read_pets: read your pets
            authorizationCode:
              authorizationUrl: https://example.com/api/oauth/dialog
              tokenUrl: https://example.com/api/oauth/token
              scopes:
                write_pets: modify pets in your account
                read_pets: read your pets
            clientCredentials:
              tokenUrl: https://example.com/api/oauth/token
              scopes:
                write_pets: modify pets in your account
                read_pets: read your pets
          type: oauth2

其他资源

7.6.5. 部署 3scale API Management OpenAPI 自定义资源,从 URL 中导入 OAS 文档

您可以部署从您指定的 URL 中导入 OAS 文档的 OpenAPI 自定义资源。然后,您可以在 Developer Portal 中使用此 OAS 文档作为您的 API 的 ActiveDocs 的基础。

先决条件

  • 如果您要创建一个 OpenAPI 自定义资源,它没有链接到同一命名空间中的 3scale 实例中默认租户,则该命名空间将包含 OpenAPI CR 的 secret 包含一个用于标识 OpenAPI CR 链接的租户。secret 的名称是以下之一:

    • threescale-provider-account
    • 用户定义

    此机密包含 3scale 实例的 URL 和令牌,其中包含用于访问 3scale 实例中某一租户的凭据。

流程

  1. 在 OpenShift 帐户中,进入到 Operators > Installed operators
  2. 点 3scale operator。
  3. 选择 YAML 选项卡。
  4. 创建 OpenAPI 自定义资源(CR)。例如:

    apiVersion: capabilities.3scale.net/v1beta1
    kind: OpenAPI
    metadata:
      name: openapi1
    spec:
      openapiRef:
        url: "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml"
      providerAccountRef:
        name: mytenant
  5. 点击 Save。3scale 操作器需要几秒钟时间来创建 OpenAPI CR。

验证

  1. 在 OpenShift 中,在 3scale Product Overview 页面中,确认 Synced 条件被标记为 True
  2. 进入 3scale 帐户。
  3. 确认存在 OAS 文档。对于上例,您会看到一个名为 openapi1 的新 OAS 文档。

7.6.6. 其他资源

Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.