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 如何与租户链接。 -
apiKey
和openIdConnect/oauth2
是支持的安全方案。
OpenID Connect 和 OAuth2 限制
要在 OpenAPI 规格中配置 3scale,您必须在 OpenAPI 自定义资源(CR)中提供以下数据:
OpenID Connect (OIDC)
issuerType
:-
定义签发者类型,默认为
rest
。您可以在 OpenAPI CR 中覆盖此参数。
-
定义签发者类型,默认为
将
issuerEndpoint
issuerEndpointRef
secret。-
如果您在 CR 中定义
issuerEndpoint
普通值,它优先于issuerEndpointRef
secret。 -
issuerEndpoint
格式取决于 OpenID 提供程序设置。对于 Red Hat Single Sign-On,它是https://<CLIENT_ID>:<CLIENT_SECRET>@:/auth/realms/<REALM_NAME>
。
-
如果您在 CR 中定义
流对象:
-
当您定义
oauth2
安全方案时,OpenAPI 文档包含流。但是,当安全方案是 OpenID Connect 时,OpenAPI 文档不提供流。在这种情况下,OpenAPI CR 可以提供它们。
-
当您定义
7.6.1. 部署 3scale OpenAPI 自定义资源,从 secret 中导入 OAS 文档
部署 OpenAPI
自定义资源 (CR),以便您可以创建 3scale 后端和产品。
Operator 只读取 secret 中的内容。Operator 不读取 secret 中的字段名称。
先决条件
流程
定义包含 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"
创建 secret.例如:
$ oc create secret generic myoasdoc1 --from-file myoasdoc1.yaml secret/myoasdoc1 created
定义
OpenAPI
CR。确保指定包含 OAS 文档的 secret 的引用。例如,您可以创建myopenapicr1.yaml
文件:apiVersion: capabilities.3scale.net/v1beta1 kind: OpenAPI metadata: name: myopenapicr1 spec: openapiRef: secretRef: name: myoasdoc1
创建您刚刚定义的资源。例如:
$ 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 支持apiKey
和openIdConnect/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.privateAPIHostHeader
和 spec.privateAPISecretToken
字段来设置。
ActiveDocs
不会创建 3scale ActiveDoc。
3scale 产品策略链
3scale 策略链是默认 3scale 创建的。
3scale 部署模式
默认情况下,配置的 3scale 部署模式将为 APIcast 3scale 管理。但是,当 spec.productionPublicBaseURL
或 spec.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 获取。
流程
使用以下内容创建 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
使用以下命令应用 secret:
$ oc apply -f my-secret.yaml
为 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
使用以下命令为 OIDC 和 OAuth2 应用 OpenAPI CR:
$ oc apply -f <openapi-cr-file>.yaml
- OIDC 字段在 OpenAPI CR 中是可选的,仅适用于 OpenID Connect。
-
issuerEndpointRef
应该引用包含issuerEndpoint
的 secret
字段 | 必需 | 描述 |
| 否 |
有效值: [ |
| 否 |
|
| 否 |
包含 |
| 否 |
带有包含 clientID 的 ClientID 的 JSON Web 令牌(JWT)声明。默认为 |
| 否 |
|
| 否 |
流对象:当安全方案为 OAuth2 时,流由 OpenAPI 文档提供。但是,对于 OIDC 安全方案,OpenAPI 文档不提供流。在这种情况下,OpenAPI CR 可以提供这些 CR。OIDC 只有 4 个流参数: |
| 否 | 指定错误的自定义网关响应。请参阅 GatewayResponseSpec。 |
-
在 OIDC 规格中定义
issuerEndpointRef
或issuerEndpoint
,但您可以定义这两个字段。 -
如果在 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 OAuth2authorizationCode
is defined -
如果定义了 OAuth2 隐式,则
implicit
FlowEnabled -
如果定义了 OAuth2
客户端Credentials
,则serviceAccountsEnabled
为 true 如果定义了 OAuth2
密码
,则directAccessGrantsEnabled
为 trueOAS
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 实例中某一租户的凭据。
-
流程
- 在 OpenShift 帐户中,进入到 Operators > Installed operators。
- 点 3scale operator。
- 选择 YAML 选项卡。
创建
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
-
点击 Save。3scale 操作器需要几秒钟时间来创建
OpenAPI
CR。
验证
-
在 OpenShift 中,在 3scale Product Overview 页面中,确认 Synced 条件被标记为
True
。 - 进入 3scale 帐户。
-
确认存在 OAS 文档。对于上例,您会看到一个名为
openapi1
的新 OAS 文档。