Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 4. Managing security

4.1. Authentication for OpenAPI services
Copy link

To secure an OpenAPI service operation, define a Security Scheme by using the OpenAPI specification. These schemes are in the securitySchemes section of the OpenAPI specification file. You must configure the operation by adding a Security Requirement that refers to that Security Scheme. When a workflow invokes such operation, that information is used to determine the required authentication configuration.

This section outlines the supported authentication types and demonstrates how to configure them to access secured OpenAPI service operations within your workflows.

4.1.1. Overview of OpenAPI service authentication
Copy link

In OpenShift Serverless Logic, you can secure OpenAPI service operations using the Security Schemes defined in the OpenAPI specification file. These schemes help define the authentication requirements for operations invoked within a workflow.

The Security Schemes are declared in the securitySchemes section of the OpenAPI document. Each scheme specifies the type of authentication to apply, such as HTTP Basic, API key, and so on.

When a workflow calls a secured operation, it references these defined schemes to determine the required authentication configuration.

Example security scheme definitions

"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

If the OpenAPI file defines Security Schemes, but does not include Security Requirements for operations, the generator can be configured to create them by default. These defaults apply to operations without explicitly defined requirements.

To configure that scheme, you must use the quarkus.openapi-generator.codegen.default-security-scheme property. The default-security-scheme property is used only at code generation time and not during the runtime. The value must match any of the available schemes in securitySchemes section, such as http-basic-example or api-key-example:

For Example

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

To invoke OpenAPI service operations secured by authentication schemes, you must configure the corresponding credentials and parameters in your application. OpenShift Serverless Logic uses these configurations to authenticate with the external services during workflow execution.

This section describes how to define and apply the necessary configuration properties for security schemes declared in the OpenAPI specification file. You can use either application.properties, the ConfigMap associated with your workflow, or environment variables in the SonataFlow CR to provide these credentials.

Note

The security schemes defined in an OpenAPI specification file are global to all the operations that are available in the same file. This means that the configurations set for a particular security scheme also apply to the other secured operations.

Prerequisites

  • You have access to a OpenShift Serverless Logic project with the appropriate roles and permissions to create applications and other workloads in OpenShift Container Platform.
  • Your OpenAPI specification includes one or more security schemes.
  • You have access to the OpenAPI specification files.
  • You have identified the schemes you want to configure http-basic-example or api-key-example.
  • You have access to the application.properties file, the workflow ConfigMap, or the SonataFlow CR.

Procedure

  • Use the following format to compose your property keys: 

    quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]
    Copy to Clipboard Toggle word wrap
    • filename is the sanitized name of the file containing the OpenAPI specification, such as security_example_json. To sanitize this name, you must replace all non-alphabetic characters with _ underscores.
    • security_scheme_name is the sanitized name of the security scheme object definition in the OpenAPI specification file, such as http_basic_example or api_key_example. To sanitize this name, you must replace all non-alphabetic characters with _ underscores.

    • auth_property_name is the name of the property to configure, such as username. This property depends on the defined security scheme type.

      Note

      When you are using environment variables to configure properties, follow the MicroProfile environment variable mapping rules. You can replace all non-alphabetic characters in the property key with underscores _, and convert the entire key to uppercase.

The following examples show how to provide these configuration properties using application.properties, the ConfigMap associated with your workflow, or environment variables defined in the SonataFlow CR:

Example of configuring the credentials by using the application.properties file

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

Example of configuring the credentials by using the workflow 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

Note

If the name of the workflow is example-workflow, the name of the ConfigMap with the user defined properties must be example-workflow-props.

Example of configuring the credentials by using environment variables in the 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. Example of basic HTTP authentication
Copy link

The following example shows how to secure a workflow operation using the HTTP basic authentication scheme. The security-example.json file defines an OpenAPI service with a single operation, sayHelloBasic, which uses the http-basic-example security scheme. You can configure credentials using application properties, the worfklow ConfigMap, or environment variables.

Example OpenAPI specification with HTTP basic authentication

{
  "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

In this example, the sayHelloBasic operation is secured using the http-basic-example scheme defined in the securitySchemes section. When invoking this operation in a workflow, you must configure the appropriate credentials.

You can use the following configuration keys to provide authentication credentials for the http-basic-example scheme:

Expand
DescriptionProperty keyExample

Username credentials

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

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

Password credentials

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

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

You can replace [filename] with the sanitized OpenAPI file name security_example_json and [security_scheme_name] with the sanitized scheme name http_basic_example.

4.1.4. Example of Bearer token authentication
Copy link

The following example shows how to secure an OpenAPI operation using the HTTP Bearer authentication scheme. The security-example.json file defines an OpenAPI service with the sayHelloBearer operation, which uses the http-bearer-example scheme for authentication. To access the secured operation during workflow execution, you must configure a Bearer token using application properties, the workflow ConfigMap, or environment variables.

Example OpenAPI specification with Bearer token authentication

{
  "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

In this example, the sayHelloBearer operation is protected by the http-bearer-example scheme. You must define a valid Bearer token in your configuration to invoke this operation successfully.

You can use the following configuration property key to provide the Bearer token:

Expand
DescriptionProperty keyExample

Bearer token

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

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

You can replace [filename] with the sanitized OpenAPI file name security_example_json and [security_scheme_name] with the sanitized scheme name http_bearer_example.

4.1.5. Example of API key authentication
Copy link

The following example shows how to secure an OpenAPI service operation using the apiKey authentication scheme. The security-example.json file defines the sayHelloApiKey operation, which uses the api-key-example security scheme. You can configure the API key using application properties, the workflow ConfigMap, or environment variables.

Example OpenAPI specification with API key authentication

{
  "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

In this example, the sayHelloApiKey operation is protected by the api-key-example security scheme, which uses an API key passed in the HTTP request header.

You can use the following configuration property to configure the API key:

Expand
DescriptionProperty keyExample

API Key

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

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

You can replace [filename] with the sanitized OpenAPI file name security_example_json and [security_scheme_name] with the sanitized scheme name api_key_example.

The apiKey scheme type contains an additional name property that configures the key name to use when the Open API service is invoked. Also, the format to pass the key depends on the value of the in property.

  • When the value is header, the key is passed as an HTTP request parameter.
  • When the value is cookie, the key is passed as an HTTP cookie.
  • When the value is query, the key is passed as an HTTP query parameter.

In the example, the key is passed in the HTTP header as api-key-name: MY_KEY.

OpenShift Serverless Logic manages this internally, so no additional configuration is required beyond setting the property value.

The following example shows how to secure an OpenAPI operation using the OAuth 2.0 clientCredentials flow. The OpenAPI specification defines the sayHelloOauth2 operation, which uses the oauth-example security scheme. Unlike simpler authentication methods, such as HTTP Basic or API keys, OAuth 2.0 authentication requires additional integration with the Quarkus OpenID Connect (OIDC) Client.

Example OpenAPI specification with OAuth 2.0

{
  "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

In this example, the sayHelloOauth2 operation is protected by the oauth-example security scheme, which uses the clientCredentials flow for token-based authentication.

OAuth 2.0 token management is handled by a Quarkus OidcClient. To enable this integration, you must add the Quarkus OIDC Client Filter, and the Quarkus OpenApi Generator OIDC extensions to your project as shown in the following examples:

Example of adding extensions using 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

Example of adding extensions using gitops profile

Ensure that you configure the QUARKUS_EXTENSIONS build argument with the following value when building the workflow image: 

$ --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

Example of adding extensions using preview profile

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

Note

The extensions that are added in the SonataFlowPlatform CR are included for all the workflows that you deploy in that namespace with the preview profile.

4.1.6.2. OidcClient configuration
Copy link

To access the secured operation, define an OidcClient configuration in your application.properties file. The configuration uses the sanitized security scheme name from the OpenAPI specification, in this case, oauth_example as follows: 

# 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

In this configuration:

  • oauth_example matches the sanitized name of the oauth-example scheme in the OpenAPI file. The link between the sanitized scheme name and the corresponding OidcClient is achieved by using that simple naming convention.
  • The OidcClient handles token generation and renewal automatically during workflow execution.

4.1.7. Example of authorization token propagation
Copy link

OpenShift Serverless Logic supports token propagation for OpenAPI operations that use the oauth2 or http bearer security scheme types. Token propagation enables your workflow to forward the authorization token it receives during workflow creation to downstream services.This feature is useful when your workflow needs to interact with third-party services on behalf of the client that initiated the request.

You must configure token propagation individually for each security scheme. After it is enabled, all OpenAPI operations secured using the same scheme uses the propagated token unless explicitly overridden.

The following example defines the sayHelloOauth2 operation in the security-example.json file. This operation uses the oauth-example security scheme with the clientCredentials flow:

Example OpenAPI specification with token propagation

{
  "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

You can use the following configuration keys to enable and customize token propagation:

Note

The tokens are automatically passed to downstream services while the workflow is active. When the workflow enters a waiting state, such as a timer or event-based pause, the token propagation stops. After the workflow resumes, tokens are not re-propagated automatically. You must manage re-authentication if needed.

Expand
Property keyExampleDescription

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

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

Enables token propagation for all operations secured with the given scheme. Default is false.

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

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

(Optional) Overrides the default Authorization header with a custom header name to read the token from.

You can replace [filename] with the sanitized OpenAPI file name security_example_json and [security_scheme_name] with the sanitized scheme name oauth_example.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat