Authentication for OpenAPI services in SonataFlow
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:
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 |
|
|
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:
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 assecurity_example_json
. -
security_scheme_name
is the sanitized name of the security scheme object definition in the OpenAPI specification file, such ashttp_basic_example
orapi_key_example
. -
auth_property_name
is the name of the property to configure, such asusername
. 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:
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:
Description | Property key | Example |
---|---|---|
Username credentials |
|
|
Password credentials |
|
|
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:
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:
Description | Property key | Example |
---|---|---|
Bearer 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:
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:
Description | Property key | Example |
---|---|---|
API 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:
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:
<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
|
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:
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:
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:
Property key | Example |
---|---|
|
|
|
|
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. |
Found an issue?
If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!