Authentication for OpenAPI services in Kogito Serverless Workflow

This document describes the supported authentication types and how to configure them to access the OpenAPI service operations that are used in workflows.

For information about orchestrating and configuring the OpenAPI based services, you must see the following documents:

The OpenAPI support for a workflow is based on the Quarkus OpenAPI generator extension. For more information about Quarkus OpenAPI generator, see Quarkus - OpenAPI Generator.

Overview of OpenAPI services authentication

According to the OpenAPI specification, you can secure an OpenAPI service operation by using a security scheme. These security schemes are defined in the Security Scheme Object definitions of the OpenAPI specification file.

The security scheme type defined for an OpenAPI service operation is used to identify the required configuration, when a workflow invokes the same operation.

The following shows the example of security scheme definitions:

Example security-example.json file
"securitySchemes": {
  "http-basic-example": {
    "type": "http",
    "scheme": "basic"
  }
  "api-key-example": {
    "type": "apiKey",
    "name": "my-example-key",
    "in": "header"
  }
}

If the OpenAPI specification file contains securitySchemes definitions, but not the Security Requirement Object definitions, the generator is configured to create the security requirement objects by default. In this case, for all the operations without a security requirement, the default one is created. Note that the property value must match the name of a security scheme object definition, such as http-basic-example or api-key-example in the previous securitySchemes list.

Description Property key Example

Create security for the referenced security scheme

quarkus.openapi-generator.codegen.default.security.scheme

quarkus.openapi-generator.codegen.default.security.scheme=http-basic-example

To configure the credentials that are used to access the secured OpenAPI service operations and related parameters, you must use the application properties that are related to the security schemes.

To compose the configuration keys, use the following format:

Format for configuration keys
quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]

The previous format includes the following parameters:

  • filename is the sanitized name of the file containing the OpenAPI specification, such as security_example_json.

  • 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.

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

To sanitize the previous parameters, you can follow the Environment Variables Mapping Rules from Microprofile Configuration. In the mapping rules, any non-alphabetic character is replaced by an underscore (_).

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.

You can use the alternatives defined in the Quarkus configuration reference guide to configure the required properties. A common usage is to define environment variables to set the authentication secrets.

For a complete example, see Orchestration of third-party services using OAuth 2.0 authentication.

Example of basic HTTP authentication

The following example shows security-example.json file, defining a sayHelloBasic operation, which is secured using the http-basic-example security scheme and supported configurations:

Example security-example.json file for HTTP 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"
      }
    }
  }
}

The following table shows the supported configurations that are used to secure the sayHelloBasic operation in the previous example:

Table 1. Supported configuration examples for HTTP authentication
Description Property key Example

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

Example of Bearer Token authentication

The following example shows security-example.json file, defining a sayHelloBearer operation, which is secured using the http-bearer-example security scheme and supported configurations:

Example security-example.json file for 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"
      }
    }
  }
}

The following table shows the supported configurations that are used to secure the sayHelloBearer operation in the previous example:

Table 2. Supported configuration examples for Bearer Token authentication
Description Property key Example

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

Example of API key authentication

The following example shows security-example.json file, defining a sayHelloApiKey operation, which is secured using the api-key-example security scheme and supported configurations:

Example security-example.json file for 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"
      }
    }
  }
}

The following table shows the supported configurations that are used to secure the sayHelloApiKey operation in the previous example:

Table 3. Supported configuration examples for API key authentication
Description Property key Example

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

The API key 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.

However, this is automatically managed without additional configurations.

Following the previous example, the API key is passed as an http request parameter, such as api-key-name with the value MY_KEY.

Example of OAuth 2.0 authentication

The following example shows security-example.json file, defining a sayHelloOauth2 operation, which is secured using the oauth-example security scheme and supported configurations:

Example security-example.json file for OAuth 2.0 authentication
{
  "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": {
            }
          }
        }
      }
    }
  }
}

Unlike the http basic, http bearer, and apiKey security schemes, the OAuth 2.0 authentication relies on the Quarkus OpenId Connect (OIDC) and OAuth 2.0 Clients and Filters. Therefore, you must add the Quarkus OIDC Client Filter Extension to your project as shown in the following example:

Example of adding Quarkus OIDC client filter extension
<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc-client-filter</artifactId>
</dependency>

You can also add the Quarkus OIDC client filter extension using the Quarkus CLI as shown in the following example:

Add Quarkus OIDC client filter extension
$ quarkus extension add quarkus-oidc-client-filter

The token management operations are delegated to a Quarkus OidcClient using a simple naming convention.

In the previous example, the token management operations that are used to access the sayHelloOauth2 operation are delegated to the OidcClient that is oauth_example.

You can configure the OidcClient as shown in the following example:

Example of configuring an OidcClient
quarkus.oidc-client.oauth_example.auth-server-url=https://example.com/oauth
quarkus.oidc-client.oauth_example.token-path=/tokens
quarkus.oidc-client.oauth_example.discovery-enabled=false
quarkus.oidc-client.oauth_example.client-id=kogito-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

The suffix (quarkus.oidc-client.oauth_example) used in the previous configuration example is exclusive for the security scheme defined in the OpenAPI service specification file and the scheme name is sanitized using the mapping rules.

Example of authorization token propagation

You can use the authorization token propagation with OpenAPI operations that are secured using the oauth2 or http bearer security scheme type. When the configuration is set, you can propagate the authorization tokens that are passed to your workflow during the workflow creation.

The propagations must be configured individually for each security scheme, which enables you to configure the invocations that must propagate the token.

Similar to other security scheme configurations, the token propagation applies to all the OpenAPI operations that are secured using the same security scheme.

The following example shows security-example.json file, defining a sayHelloOauth2 operation, which is secured using the oauth-example security scheme and supported configurations:

Example security-example.json file for authorization 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": {
            }
          }
        }
      }
    }
  }
}

The following table shows the supported configurations that are used to secure the sayHelloOauth2 operation in the previous example:

Table 4. Supported configuration examples for token propagation
Property key Example

quarkus.openapi-generator.[filename].auth.[security_scheme_name].token-propagation=[true,false]

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

Enables the token propagation for all the operations that are secured using the oauth-example scheme in the security-example.json file. By default, the standard HTTP authorization header is propagated.

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

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

States that the authorization token is read from the MyHeaderName header instead of the standard HTTP authorization header.

The authorization tokens are propagated till the workflow does not reach its waiting state. When the same workflow is resumed, the tokens will not be propagated.

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!