Skip to content

Commit 2a59aac

Browse files
sheriff-rhsheriff-rh
authored
Merge pull request #93489 from openshift-cherrypick-robot/cherry-pick-92245-to-serverless-docs-1.36
2 parents ce5ecef + d0dee1b commit 2a59aac

9 files changed

+608
-7
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -113,11 +113,12 @@
113113
:ServerlessOperatorName: OpenShift Serverless Operator
114114
:ServerlessLogicOperatorName: OpenShift Serverless Logic Operator
115115
:FunctionsProductName: OpenShift Serverless Functions
116-
:ServerlessProductVersion: 1.35.0
117-
:ServerlessLogicQuarkusVersion: 3.8.6.redhat-00004
118-
:ServerlessLogicOrgKieVersion: 9.102.0.redhat-00005
119-
:ServerlessLogicRegistryVersion: registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel8:1.35.0
120-
:ServerlessLogic-DDL-Script-url: link:https://maven.repository.redhat.com/ga/org/kie/kogito/kogito-ddl/9.102.0.redhat-00005/kogito-ddl-9.102.0.redhat-00005-db-scripts.zip[kogito-ddl-9.102.0.redhat-00005-db-scripts.zip]
116+
:ServerlessProductVersion: 1.36.0
117+
:ServerlessLogicQuarkusVersion: 3.15.4.redhat-00001
118+
:ServerlessLogicOrgKieVersion: 9.103.0.redhat-00003
119+
:ServerlessLogicOauthDependencyVersion: 2.9.0-lts
120+
:ServerlessLogicRegistryVersion: registry.redhat.io/openshift-serverless-1/logic-swf-builder-rhel8:1.36.0
121+
:ServerlessLogic-DDL-Script-url: link:https://maven.repository.redhat.com/ga/org/kie/kogito/kogito-ddl/9.103.0.redhat-00003/kogito-ddl-9.103.0.redhat-00003-db-scripts.zip[kogito-ddl-9.103.0.redhat-00003-db-scripts.zip]
121122
//service mesh v2
122123
:product-dedicated: Red Hat OpenShift Dedicated
123124
:SMProductName: Red Hat OpenShift Service Mesh

‎modules/serverless-logic-security-config-auth-credentials-openapi.adoc

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
// Module included in the following assemblies:
2+
// serverles-logic/serverless-logic-authentication-openapi-services
3+
4+
:_mod-docs-content-type: PROCEDURE
5+
[id="serverless-logic-security-config-auth-credentials-openapi_{context}"]
6+
= Configuring authentication credentials for OpenAPI services
7+
8+
To invoke OpenAPI service operations secured by authentication schemes, you must configure the corresponding credentials and parameters in your application. {ServerlessLogicProductName} uses these configurations to authenticate with the external services during workflow execution.
9+
10+
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.
11+
12+
[NOTE]
13+
====
14+
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.
15+
====
16+
17+
.Prerequisites
18+
19+
* You have access to a {ServerlessLogicProductName} project with the appropriate roles and permissions to create applications and other workloads in {ocp-product-title}.
20+
* Your OpenAPI specification includes one or more security schemes.
21+
* You have access to the OpenAPI specification files.
22+
* You have identified the schemes you want to configure `http-basic-example` or `api-key-example`.
23+
* You have access to the `application.properties` file, the workflow `ConfigMap`, or the `SonataFlow` CR.
24+
25+
.Procedure
26+
27+
* Use the following format to compose your property keys:
28+
+
29+
[source,text]
30+
----
31+
quarkus.openapi-generator.[filename].auth.[security_scheme_name].[auth_property_name]
32+
----
33+
+
34+
** `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.
35+
** `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.
36+
** `auth_property_name` is the name of the property to configure, such as username. This property depends on the defined security scheme type.
37+
+
38+
[NOTE]
39+
====
40+
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.
41+
====
42+
43+
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:
44+
45+
.Example of configuring the credentials by using the `application.properties` file
46+
[source,text]
47+
----
48+
quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=myuser
49+
quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=mypassword
50+
----
51+
52+
.Example of configuring the credentials by using the workflow `ConfigMap`
53+
[source,yaml]
54+
----
55+
apiVersion: v1
56+
data:
57+
application.properties: |
58+
quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=myuser
59+
quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=mypassword
60+
kind: ConfigMap
61+
metadata:
62+
labels:
63+
app: example-workflow
64+
name: example-workflow-props
65+
namespace: example-namespace
66+
----
67+
68+
[NOTE]
69+
====
70+
If the name of the workflow is `example-workflow`, the name of the `ConfigMap` with the user defined properties must be `example-workflow-props`.
71+
====
72+
73+
.Example of configuring the credentials by using environment variables in the `SonataFlow` CR
74+
[source,yaml]
75+
----
76+
apiVersion: sonataflow.org/v1alpha08
77+
kind: SonataFlow
78+
metadata:
79+
name: example-workflow
80+
namespace: example-namespace
81+
annotations:
82+
sonataflow.org/description: Example Workflow
83+
sonataflow.org/version: 0.0.1
84+
sonataflow.org/profile: preview
85+
spec:
86+
podTemplate:
87+
container:
88+
env:
89+
- name: QUARKUS_OPENAPI_GENERATOR_SECURITY_EXAMPLE_JSON_AUTH_HTTP_BASIC_EXAMPLE_USERNAME
90+
value: myuser
91+
- name: QUARKUS_OPENAPI_GENERATOR_SECURITY_EXAMPLE_JSON_AUTH_HTTP_BASIC_EXAMPLE_PASSWORD
92+
value: mypassowrd
93+
----

‎modules/serverless-logic-security-example-api-key-authentication.adoc

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
// serverles-logic/serverless-logic-authentication-openapi-services
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="serverless-logic-security-example-api-key-authentication_{context}"]
6+
= Example of API key authentication
7+
8+
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.
9+
10+
.Example OpenAPI specification with API key authentication
11+
[source,json]
12+
----
13+
{
14+
"openapi": "3.1.0",
15+
"info": {
16+
"title": "Api Key Scheme Example",
17+
"version": "1.0"
18+
},
19+
"paths": {
20+
"/hello-with-api-key": {
21+
"get": {
22+
"operationId": "sayHelloApiKey",
23+
"responses": {
24+
"200": {
25+
"description": "OK",
26+
"content": {
27+
"text/plain": {
28+
"schema": {
29+
"type": "string"
30+
}
31+
}
32+
}
33+
}
34+
},
35+
"security": [{"api-key-example" : []}]
36+
}
37+
}
38+
},
39+
"components": {
40+
"securitySchemes": {
41+
"api-key-example": {
42+
"type": "apiKey",
43+
"name": "api-key-name",
44+
"in": "header"
45+
}
46+
}
47+
}
48+
}
49+
----
50+
51+
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.
52+
53+
[id="serverless-logic-security-supported-config-properties-api-key_{context}"]
54+
== Supported configuration properties for API key authentication
55+
56+
You can use the following configuration property to configure the API key:
57+
58+
[cols="2,1,1",options="header"]
59+
|====
60+
|Description
61+
|Property key
62+
|Example
63+
64+
|API Key
65+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].api-key`
66+
|`quarkus.openapi-generator.security_example_json.auth.api_key_example.api-key=MY_KEY`
67+
68+
|====
69+
70+
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`.
71+
72+
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.
73+
74+
* When the value is `header`, the key is passed as an HTTP request parameter.
75+
76+
* When the value is `cookie`, the key is passed as an HTTP cookie.
77+
78+
* When the value is `query`, the key is passed as an HTTP query parameter.
79+
80+
In the example, the key is passed in the HTTP header as `api-key-name: MY_KEY`.
81+
82+
{ServerlessLogicProductName} manages this internally, so no additional configuration is required beyond setting the property value.

‎modules/serverless-logic-security-example-auth-token-propagation.adoc

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Module included in the following assemblies:
2+
// serverles-logic/serverless-logic-authentication-openapi-services
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="serverless-logic-security-example-auth-token-propagation_{context}"]
6+
= Example of authorization token propagation
7+
8+
{ServerlessLogicProductName} 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.
9+
10+
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.
11+
12+
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:
13+
14+
.Example OpenAPI specification with token propagation
15+
[source,json]
16+
----
17+
{
18+
"openapi": "3.1.0",
19+
"info": {
20+
"title": "Oauth2 Scheme Example",
21+
"version": "1.0"
22+
},
23+
"paths": {
24+
"/hello-with-oauth2": {
25+
"get": {
26+
"operationId": "sayHelloOauth2",
27+
"responses": {
28+
"200": {
29+
"description": "OK",
30+
"content": {
31+
"text/plain": {
32+
"schema": {
33+
"type": "string"
34+
}
35+
}
36+
}
37+
}
38+
},
39+
"security": [
40+
{
41+
"oauth-example": []
42+
}
43+
]
44+
}
45+
}
46+
},
47+
"components": {
48+
"securitySchemes": {
49+
"oauth-example": {
50+
"type": "oauth2",
51+
"flows": {
52+
"clientCredentials": {
53+
"authorizationUrl": "https://example.com/oauth",
54+
"tokenUrl": "https://example.com/oauth/token",
55+
"scopes": {}
56+
}
57+
}
58+
}
59+
}
60+
}
61+
}
62+
----
63+
64+
[id="serverless-logic-security-supported-config-properties-token-propagation_{context}"]
65+
== Supported configuration properties for authorization token propagation
66+
67+
You can use the following configuration keys to enable and customize token propagation:
68+
69+
[NOTE]
70+
====
71+
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.
72+
====
73+
74+
[cols="2,1,1",options="header"]
75+
|====
76+
|Property key
77+
|Example
78+
|Description
79+
80+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].token-propagation`
81+
|`quarkus.openapi-generator.security_example_json.auth.oauth_example.token-propagation=true`
82+
|Enables token propagation for all operations secured with the given scheme. Default is `false`.
83+
84+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].header-name`
85+
|`quarkus.openapi-generator.security_example_json.auth.oauth_example.header-name=MyHeaderName`
86+
|(Optional) Overrides the default Authorization header with a custom header name to read the token from.
87+
88+
|====
89+
90+
You can replace `[filename]` with the sanitized OpenAPI file name `security_example_json` and `[security_scheme_name]` with the sanitized scheme name `oauth_example`.

‎modules/serverless-logic-security-example-basic-http-authentication.adoc

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Module included in the following assemblies:
2+
// serverles-logic/serverless-logic-authentication-openapi-services
3+
4+
:_mod-docs-content-type: REFERENCE
5+
[id="serverless-logic-security-example-basic-http-authentication_{context}"]
6+
= Example of basic HTTP authentication
7+
8+
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.
9+
10+
.Example OpenAPI specification with HTTP basic authentication
11+
[source,json]
12+
----
13+
{
14+
"openapi": "3.1.0",
15+
"info": {
16+
"title": "Http Basic Scheme Example",
17+
"version": "1.0"
18+
},
19+
"paths": {
20+
"/hello-with-http-basic": {
21+
"get": {
22+
"operationId": "sayHelloBasic",
23+
"responses": {
24+
"200": {
25+
"description": "OK",
26+
"content": {
27+
"text/plain": {
28+
"schema": {
29+
"type": "string"
30+
}
31+
}
32+
}
33+
}
34+
},
35+
"security": [{"http-basic-example" : []}]
36+
}
37+
}
38+
},
39+
"components": {
40+
"securitySchemes": {
41+
"http-basic-example": {
42+
"type": "http",
43+
"scheme": "basic"
44+
}
45+
}
46+
}
47+
}
48+
----
49+
50+
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.
51+
52+
[id="serverless-logic-security-supported-config-properties-basic-http_{context}"]
53+
== Supported configuration properties for basic HTTP authentication
54+
55+
You can use the following configuration keys to provide authentication credentials for the `http-basic-example` scheme:
56+
57+
[cols="2,1,1",options="header"]
58+
|====
59+
|Description
60+
|Property key
61+
|Example
62+
63+
|Username credentials
64+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].username`
65+
|`quarkus.openapi-generator.security_example_json.auth.http_basic_example.username=MY_USER`
66+
67+
|Password credentials
68+
|`quarkus.openapi-generator.[filename].auth.[security_scheme_name].password`
69+
|`quarkus.openapi-generator.security_example_json.auth.http_basic_example.password=MY_PASSWD`
70+
71+
|====
72+
73+
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`.
74+

0 commit comments

Comments
 (0)