Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

第 4 章 管理安全性

4.1. OpenAPI 服务的身份验证
复制链接

要保护 OpenAPI 服务操作，请使用 OpenAPI 规格定义安全方案。这些方案位于 OpenAPI 规格文件的 securitySchemes 部分中。您必须通过添加一个指向该安全方案的 Security Requirement 来配置 操作。当工作流调用此类操作时，会使用该信息来确定所需的身份验证配置。

本节概述支持的验证类型，并演示了如何将它们配置为访问工作流中的安全 OpenAPI 服务操作。

4.1.1. OpenAPI 服务身份验证概述
复制链接

在 OpenShift Serverless Logic 中，您可以使用 OpenAPI 规格文件中定义的 Security Schemes 保护 OpenAPI 服务操作。这些方案有助于定义工作流中调用的操作的身份验证要求。

安全方案 在 OpenAPI 文档的 securitySchemes 部分中声明。每个方案都指定要应用的验证类型，如 HTTP Basic、API 密钥等。

当工作流调用安全操作时，它会引用这些定义的方案来确定所需的身份验证配置。

安全方案定义示例

"securitySchemes": {
  "http-basic-example": {
    "type": "http",
    "scheme": "basic"
  },
  "api-key-example": {
    "type": "apiKey",
    "name": "my-example-key",
    "in": "header"
  }
}
Copy to Clipboard Toggle word wrap

如果 OpenAPI 文件定义了 Security Schemes，但不包含操作的安全要求，则默认可以将生成器配置为创建它们。这些默认值适用于没有明确定义的要求的操作。

要配置该方案，您必须使用 quarkus.openapi-generator.codegen.default-security-scheme 属性。default-security-scheme 属性仅在代码生成时使用，而不在运行时使用。该值必须与 securitySchemes 部分中的任何可用方案匹配，如 http-basic-example 或 api-key-example ：

例如

$ quarkus.openapi-generator.codegen.default-security-scheme=http-basic-example
Copy to Clipboard Toggle word wrap

4.1.2. 为 OpenAPI 服务配置身份验证凭据
复制链接

要调用由身份验证方案保护的 OpenAPI 服务操作，您必须在应用程序中配置对应的凭证和参数。OpenShift Serverless Logic 在工作流执行过程中使用这些配置与外部服务进行身份验证。

本节论述了如何在 OpenAPI 规格文件中定义并应用声明的安全方案所需的配置属性。您可以使用 application.properties、与工作流关联的 ConfigMap 或 SonataFlow CR 中的环境变量来提供这些凭证。

注意

OpenAPI 规格文件中定义的安全方案对同一文件中所有可用的操作是全局的。这意味着为特定安全方案设置的配置也适用于其他安全操作。

先决条件

  • 您可以使用适当的角色和权限访问 OpenShift Serverless Logic 项目，以便在 OpenShift Container Platform 中创建应用程序和其他工作负载。
  • 您的 OpenAPI 规格包括一个或多个安全方案。
  • 您可以访问 OpenAPI 规格文件。
  • 您已确定了您要配置 http-basic-example 或 api-key-example 的方案。
  • 您可以访问 application.properties 文件、工作流 ConfigMap 或 SonataFlow CR。

流程

  • 使用以下格式组成您的属性键： 

    quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]
    Copy to Clipboard Toggle word wrap
    • filename 是包含 OpenAPI 规格的文件清理的名称，如 security_example_json。要清理此名称，您必须将所有非字母字符替换为 _ 下划线。
    • security_scheme_name 是 OpenAPI 规格文件中安全方案对象定义的清理名称，如 http_basic_example 或 api_key_example。要清理此名称，您必须将所有非字母字符替换为 _ 下划线。

    • auth_property_name 是要配置的属性的名称，如 username。此属性取决于定义的安全方案类型。

      注意

      当您使用环境变量来配置属性时，请遵循 MicroProfile 环境变量映射规则。您可以将属性键中的所有非字母字符替换为下划线 _，并将整个键转换为大写。

以下示例演示了如何使用 application.properties、与工作流关联的 ConfigMap 或 SonataFlow CR 中定义的环境变量提供这些配置属性：

使用 application.properties 文件配置凭证的示例

quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=myuser
quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=mypassword
Copy to Clipboard Toggle word wrap

使用工作流 ConfigMap配置凭证示例

apiVersion: v1
data:
  application.properties: |
    quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=myuser
    quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=mypassword
kind: ConfigMap
metadata:
  labels:
    app: example-workflow
  name: example-workflow-props
  namespace: example-namespace
Copy to Clipboard Toggle word wrap

注意

如果工作流名称为 example-workflow，则带有用户定义属性的 ConfigMap 的名称必须是 example-workflow-props。

使用 SonataFlow CR 中的环境变量配置凭证示例

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlow
metadata:
  name: example-workflow
  namespace: example-namespace
  annotations:
    sonataflow.org/description: Example Workflow
    sonataflow.org/version: 0.0.1
    sonataflow.org/profile: preview
spec:
  podTemplate:
    container:
      env:
        - name: QUARKUS_OPENAPI_GENERATOR_SECURITY_EXAMPLE_JSON_AUTH_HTTP_BASIC_EXAMPLE_USERNAME
          value: myuser
        - name: QUARKUS_OPENAPI_GENERATOR_SECURITY_EXAMPLE_JSON_AUTH_HTTP_BASIC_EXAMPLE_PASSWORD
          value: mypassowrd
Copy to Clipboard Toggle word wrap

4.1.3. 基本 HTTP 验证示例
复制链接

以下示例演示了如何使用 HTTP 基本身份验证方案保护工作流操作。security-example.json 文件定义了带有单个操作的 OpenAPI 服务，sayHelloBasic，它使用 http-basic-example 安全方案。您可以使用应用程序属性、worfklow ConfigMap 或环境变量来配置凭证。

带有 HTTP 基本身份验证的 OpenAPI 规格示例

{
  "openapi": "3.1.0",
  "info": {
    "title": "Http Basic Scheme Example",
    "version": "1.0"
  },
  "paths": {
    "/hello-with-http-basic": {
      "get": {
        "operationId": "sayHelloBasic",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [{"http-basic-example" : []}]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "http-basic-example": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

在本例中，sayHelloBasic 操作使用 securitySchemes 部分中定义的 http-basic-example 方案进行保护。在工作流中调用此操作时，您必须配置适当的凭证。

4.1.3.1. 支持的基本 HTTP 身份验证配置属性
复制链接

您可以使用以下配置密钥为 http-basic-example 方案提供身份验证凭据：

Expand
描述属性键Example

用户名凭证

quarkus.openapi-generator.[filename].auth.[security_scheme_name].username

quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=MY_USER

密码凭证

quarkus.openapi-generator.[filename].auth.[security_scheme_name].password

quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=MY_PASSWD

您可以将 [filename] 替换为 sanitized OpenAPI 文件名 security_example_json，将 [security_scheme_name] 替换为 sanitized scheme 名称 http_basic_example。

4.1.4. Bearer 令牌身份验证示例
复制链接

以下示例演示了如何使用 HTTP Bearer 身份验证方案保护 OpenAPI 操作。security-example.json 文件使用 sayHelloBearer 操作定义 OpenAPI 服务，它使用 http-bearer-example 方案进行身份验证。要在工作流执行期间访问安全操作，您必须使用应用属性、工作流 ConfigMap 或环境变量配置 Bearer 令牌。

带有 Bearer 令牌身份验证的 OpenAPI 规格示例

{
  "openapi": "3.1.0",
  "info": {
    "title": "Http Bearer Scheme Example",
    "version": "1.0"
  },
  "paths": {
    "/hello-with-http-bearer": {
      "get": {
        "operationId": "sayHelloBearer",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "http-bearer-example": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "http-bearer-example": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

在本例中，sayHelloBearer 操作受 http-bearer-example 方案的保护。您必须在配置中定义有效的 Bearer 令牌，才能成功调用此操作。

4.1.4.1. Bearer 令牌身份验证支持的配置属性
复制链接

您可以使用以下配置属性键来提供 Bearer 令牌：

Expand
描述属性键Example

bearer 令牌

quarkus.openapi-generator.[filename].auth.[security_scheme_name].bearer-token

quarkus.openapi-generator.security_example_json.auth.http_bearer_example.bearer-token=MY_TOKEN

您可以将 [filename] 替换为 sanitized OpenAPI 文件名 security_example_json，将 [security_scheme_name] 替换为 sanitized scheme 名称 http_bearer_example。

4.1.5. API 密钥身份验证示例
复制链接

以下示例演示了如何使用 apiKey 身份验证方案保护 OpenAPI 服务操作。security-example.json 文件定义 sayHelloApiKey 操作，它使用 api-key-example 安全方案。您可以使用应用程序属性、工作流 ConfigMap 或环境变量配置 API 密钥。

带有 API 密钥身份验证的 OpenAPI 规格示例

{
  "openapi": "3.1.0",
  "info": {
    "title": "Api Key Scheme Example",
    "version": "1.0"
  },
  "paths": {
    "/hello-with-api-key": {
      "get": {
        "operationId": "sayHelloApiKey",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [{"api-key-example" : []}]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "api-key-example": {
        "type": "apiKey",
        "name": "api-key-name",
        "in": "header"
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

在本例中，sayHelloApiKey 操作由 api-key-example 安全方案保护，它使用 HTTP 请求标头中传递的 API 密钥。

4.1.5.1. 支持的 API 密钥身份验证配置属性
复制链接

您可以使用以下配置属性配置 API 密钥：

Expand
描述属性键Example

API 密钥

quarkus.openapi-generator.[filename].auth.[security_scheme_name].api-key

quarkus.openapi-generator.security_example_json.auth.api_key_example.api-key=MY_KEY

您可以将 [filename] 替换为 sanitized OpenAPI 文件名 security_example_json，将 [security_scheme_name] 替换为 sanitized scheme 名称 api_key_example。

apiKey 方案类型包含一个额外的 name 属性，用于配置在调用 Open API 服务时要使用的密钥名称。另外，传递密钥的格式取决于属性 中的值。

  • 当值为 标头 时，密钥将作为 HTTP 请求参数传递。
  • 当值为 cookie 时，密钥将作为 HTTP cookie 传递。
  • 当值为 query 时，键将作为 HTTP 查询参数传递。

在示例中，密钥在 HTTP 标头中传递，作为 api-key-name: MY_KEY。

OpenShift Serverless Logic 在内部管理此功能，因此除了设置属性值外，不需要额外的配置。

4.1.6. clientCredentials OAuth 2.0 身份验证示例
复制链接

以下示例演示了如何使用 OAuth 2.0 客户端Credentials 流保护 OpenAPI 操作。OpenAPI 规格定义 sayHelloOauth2 操作，它使用 oauth-example 安全方案。与更简单的身份验证方法（如 HTTP Basic 或 API 密钥）不同，OAuth 2.0 身份验证需要额外的与 Quarkus OpenID Connect (OIDC)客户端集成。

使用 OAuth 2.0 的 OpenAPI 规格示例

{
  "openapi": "3.1.0",
  "info": {
    "title": "Oauth2 Scheme Example",
    "version": "1.0"
  },
  "paths": {
    "/hello-with-oauth2": {
      "get": {
        "operationId": "sayHelloOauth2",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth-example": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth-example": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "authorizationUrl": "https://example.com/oauth",
            "tokenUrl": "https://example.com/oauth/token",
            "scopes": {}
          }
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

在本例中，sayHelloOauth2 操作由 oauth-example 安全方案保护，它使用 clientCredentials 流进行基于令牌的身份验证。

OAuth 2.0 令牌管理由 Quarkus OidcClient 处理。要启用此集成，您必须在项目中添加 Quarkus OIDC Client Filter 和 Quarkus OpenApi Generator OIDC 扩展，如下例所示：

使用 Maven 添加扩展示例

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc-client-filter</artifactId>
  <version>3.15.4.redhat-00001</version>
</dependency>

<dependency>
  <groupId>io.quarkiverse.openapi.generator</groupId>
  <artifactId>quarkus-openapi-generator-oidc</artifactId>
  <version>2.9.0-lts</version>
</dependency>
Copy to Clipboard Toggle word wrap

使用 gitops 配置集添加扩展示例

在构建工作流镜像时，请确保使用以下值配置 QUARKUS_EXTENSIONS 构建参数： 

$ --build-arg=QUARKUS_EXTENSIONS=io.quarkus:quarkus-oidc-client-filter:3.15.4.redhat-00001,io.quarkiverse.openapi.generator:quarkus-openapi-generator-oidc:2.9.0-lts
Copy to Clipboard Toggle word wrap

使用 preview 配置集添加扩展示例

apiVersion: sonataflow.org/v1alpha08
kind: SonataFlowPlatform
metadata:
  name: sonataflow-platform-example
  namespace: example-namespace
spec:
  build:
    template:
      buildArgs:
        - name: QUARKUS_EXTENSIONS
          value: io.quarkus:quarkus-oidc-client-filter:3.15.4.redhat-00001,io.quarkiverse.openapi.generator:quarkus-openapi-generator-oidc:2.9.0-lts
Copy to Clipboard Toggle word wrap

注意

在 SonataFlowPlatform CR 中添加的扩展会包括在该命名空间中使用 preview 配置集部署的所有工作流。

4.1.6.2. OidcClient 配置
复制链接

要访问安全操作，请在 application.properties 文件中定义 OidcClient 配置。配置使用 OpenAPI 规格中清理的安全方案名称，本例中为 oauth_example，如下所示： 

# adjust these configurations according with the authentication service.
quarkus.oidc-client.oauth_example.auth-server-url=https://example.com/oauth
quarkus.oidc-client.oauth_example.token-path=/token
quarkus.oidc-client.oauth_example.discovery-enabled=false
quarkus.oidc-client.oauth_example.client-id=example-app
quarkus.oidc-client.oauth_example.grant.type=client
quarkus.oidc-client.oauth_example.credentials.client-secret.method=basic
quarkus.oidc-client.oauth_example.credentials.client-secret.value=secret
Copy to Clipboard Toggle word wrap

在这个配置中：

  • oauth_example 与 OpenAPI 文件中的 oauth-example 方案的清理名称匹配。清理方案名称和对应的 OidcClient 之间的链接通过使用该简单命名规则来实现。
  • OidcClient 在工作流执行过程中自动处理令牌生成和续订。

4.1.7. 授权令牌传播示例
复制链接

OpenShift Serverless Logic 支持使用 oauth2 或 http bearer 安全方案类型的 OpenAPI 操作的令牌传播。通过令牌传播，您的工作流可以将它在工作流创建过程中收到的授权令牌转发到下游服务。当您的工作流需要代表发起请求的客户端与第三方服务交互时，此功能很有用。

您必须为每个安全方案单独配置令牌传播。启用后，所有使用相同方案保护的 OpenAPI 操作都使用传播令牌，除非被显式覆盖。

以下示例在 security-example.json 文件中定义 sayHelloOauth2 操作。此操作使用带有 clientCredentials 流的 oauth-example 安全方案：

使用令牌传播的 OpenAPI 规格示例

{
  "openapi": "3.1.0",
  "info": {
    "title": "Oauth2 Scheme Example",
    "version": "1.0"
  },
  "paths": {
    "/hello-with-oauth2": {
      "get": {
        "operationId": "sayHelloOauth2",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth-example": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth-example": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "authorizationUrl": "https://example.com/oauth",
            "tokenUrl": "https://example.com/oauth/token",
            "scopes": {}
          }
        }
      }
    }
  }
}
Copy to Clipboard Toggle word wrap

4.1.7.1. 支持的授权令牌传播配置属性
复制链接

您可以使用以下配置密钥启用和自定义令牌传播：

注意

在工作流处于活跃状态时，令牌会自动传递给下游服务。当工作流进入等待状态时，如计时器或基于事件的暂停，令牌传播将停止。在工作流恢复后，令牌不会被自动传播。如果需要，您必须管理重新身份验证。

Expand
属性键Example描述

quarkus.openapi-generator.[filename].auth.[security_scheme_name].token-propagation

quarkus.openapi-generator.security_example_json.auth.oauth_example.token-propagation=true

为给定方案保护的所有操作启用令牌传播。默认为 false。

quarkus.openapi-generator.[filename].auth.[security_scheme_name].header-name

quarkus.openapi-generator.security_example_json.auth.oauth_example.header-name=MyHeaderName

（可选）使用自定义标头名称覆盖默认的 Authorization 标头，以便从中读取令牌。

您可以将 [filename] 替换为 sanitized OpenAPI 文件名 security_example_json，将 [security_scheme_name] 替换为 sanitized scheme 名称 oauth_example。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

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

让开源更具包容性

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

關於紅帽

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

Theme

© 2025 Red Hat