From 0778ce55d6fedfa0bedf50a558f46b6921425731 Mon Sep 17 00:00:00 2001 From: Sebastian Mahr Date: Fri, 4 Jul 2025 07:38:49 +0200 Subject: [PATCH 1/8] feat: add documentation for oicd, jwtBearer --- _docs_operate/configuration.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 1748cd0ae..ad35a1b82 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -239,6 +239,9 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT - **apiKey** `required` + For an productive connector one or more of the three configs (**apiKey**, **oicd**, **jwtBearer**) is required + {: .notice--info} + Define the API-Key the Connector should use to authenticate requests. The API-Key can be chosen arbitrarily and has to be sent with every request in the `X-API-KEY` HTTP-Header. @@ -247,6 +250,22 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT The API-Key protects your Connector from unauthorized access and should therefore be kept secret. +- **oicd** `required` + + Defines the setting for the connection to you OICD server. + + The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) + + Because the oicd process requires an redirect this type of authentication is only available when the user cales the connector via browser + +- **jwtBearer** `required` + + Defines the setting for the oauth2 jwt bearer authorization. + + The full configuration can be found [here](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) + + The jwt token from the oauth provider needs to be send via the "Authorizaion" header with the Bearer prefix. + - **helmetOptions** `default: depending on the Connector mode` Configure the [helmet](https://helmetjs.github.io/) middleware. @@ -361,6 +380,7 @@ It is not recommended to use this Module for production scenarios. Here you can define multiple brokers to which the Connector should publish messages. Each broker consists of a `type` (string) and a `configuration` object. The `type` specifies the type of the broker (e.g. `AMQP` or `PubSub`) and the `configuration` object contains the configuration for the broker. + - type `AMQP` **example** @@ -376,6 +396,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` - the URL of the AMQP broker @@ -404,6 +425,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` the URL of the MQTT broker @@ -426,6 +448,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - projectId `string, required` the project id of the Google Cloud project @@ -452,6 +475,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` the URL of the broker @@ -518,6 +542,7 @@ It is not recommended to use this Module for production scenarios. **OAuth2** The OAuth2 authentication type is used to authenticate the request to the webhook using the client credentials flow of OAuth2. The Connector will send a bearer token as part of the request in its Authentication header. The OAuth2 authentication is configured using the following parameters: + - **type** `"OAuth2", required` The type of the authentication. @@ -541,6 +566,7 @@ It is not recommended to use this Module for production scenarios. **ApiKey** The ApiKey authentication type is used to authenticate the request to the webhook using an API key. The Connector will send the API key as part of the request using a header. The ApiKey authentication is configured using the following parameters: + - **type** `"ApiKey", required` The type of the authentication. From d14386978903fd9218e66d26cdfe1c7e6fa81eb2 Mon Sep 17 00:00:00 2001 From: Sebastian Mahr Date: Fri, 4 Jul 2025 07:42:02 +0200 Subject: [PATCH 2/8] prettier --- _docs_operate/configuration.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index ad35a1b82..4031ecb4c 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -380,7 +380,6 @@ It is not recommended to use this Module for production scenarios. Here you can define multiple brokers to which the Connector should publish messages. Each broker consists of a `type` (string) and a `configuration` object. The `type` specifies the type of the broker (e.g. `AMQP` or `PubSub`) and the `configuration` object contains the configuration for the broker. - - type `AMQP` **example** @@ -396,7 +395,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` - the URL of the AMQP broker @@ -425,7 +423,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` the URL of the MQTT broker @@ -448,7 +445,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - projectId `string, required` the project id of the Google Cloud project @@ -475,7 +471,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` the URL of the broker @@ -542,7 +537,6 @@ It is not recommended to use this Module for production scenarios. **OAuth2** The OAuth2 authentication type is used to authenticate the request to the webhook using the client credentials flow of OAuth2. The Connector will send a bearer token as part of the request in its Authentication header. The OAuth2 authentication is configured using the following parameters: - - **type** `"OAuth2", required` The type of the authentication. @@ -566,7 +560,6 @@ It is not recommended to use this Module for production scenarios. **ApiKey** The ApiKey authentication type is used to authenticate the request to the webhook using an API key. The Connector will send the API key as part of the request using a header. The ApiKey authentication is configured using the following parameters: - - **type** `"ApiKey", required` The type of the authentication. From 2a88a5694ad580b3718fa182a81d66a3d5dec4e3 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 4 Jul 2025 13:48:40 +0000 Subject: [PATCH 3/8] fix: oicd --- _docs_operate/configuration.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 4031ecb4c..2ed862b1a 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -239,7 +239,7 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT - **apiKey** `required` - For an productive connector one or more of the three configs (**apiKey**, **oicd**, **jwtBearer**) is required + For an productive connector one or more of the three configs (**apiKey**, **oidc**, **jwtBearer**) is required {: .notice--info} Define the API-Key the Connector should use to authenticate requests. @@ -250,13 +250,13 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT The API-Key protects your Connector from unauthorized access and should therefore be kept secret. -- **oicd** `required` +- **oidc** `required` - Defines the setting for the connection to you OICD server. + Defines the setting for the connection to you OIDC server. The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) - Because the oicd process requires an redirect this type of authentication is only available when the user cales the connector via browser + Because the oidc process requires an redirect this type of authentication is only available when the user cales the connector via browser - **jwtBearer** `required` @@ -380,6 +380,7 @@ It is not recommended to use this Module for production scenarios. Here you can define multiple brokers to which the Connector should publish messages. Each broker consists of a `type` (string) and a `configuration` object. The `type` specifies the type of the broker (e.g. `AMQP` or `PubSub`) and the `configuration` object contains the configuration for the broker. + - type `AMQP` **example** @@ -395,6 +396,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` - the URL of the AMQP broker @@ -423,6 +425,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` the URL of the MQTT broker @@ -445,6 +448,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - projectId `string, required` the project id of the Google Cloud project @@ -471,6 +475,7 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** + - url `string, required` the URL of the broker @@ -537,6 +542,7 @@ It is not recommended to use this Module for production scenarios. **OAuth2** The OAuth2 authentication type is used to authenticate the request to the webhook using the client credentials flow of OAuth2. The Connector will send a bearer token as part of the request in its Authentication header. The OAuth2 authentication is configured using the following parameters: + - **type** `"OAuth2", required` The type of the authentication. @@ -560,6 +566,7 @@ It is not recommended to use this Module for production scenarios. **ApiKey** The ApiKey authentication type is used to authenticate the request to the webhook using an API key. The Connector will send the API key as part of the request using a header. The ApiKey authentication is configured using the following parameters: + - **type** `"ApiKey", required` The type of the authentication. From ce86a5dc12599bc50f794ebe9e38e5b225df8489 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 4 Jul 2025 13:50:26 +0000 Subject: [PATCH 4/8] fix: missing punctuation --- _docs_operate/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 2ed862b1a..d373c7b12 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -239,7 +239,7 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT - **apiKey** `required` - For an productive connector one or more of the three configs (**apiKey**, **oidc**, **jwtBearer**) is required + For an productive connector one or more of the three configs (**apiKey**, **oidc**, **jwtBearer**) is required. {: .notice--info} Define the API-Key the Connector should use to authenticate requests. @@ -262,7 +262,7 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT Defines the setting for the oauth2 jwt bearer authorization. - The full configuration can be found [here](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) + The full configuration can be found [here](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html). The jwt token from the oauth provider needs to be send via the "Authorizaion" header with the Bearer prefix. From 98bab6c2ee7c645d1f5cf7aeb69190415a42395c Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 4 Jul 2025 14:07:58 +0000 Subject: [PATCH 5/8] fix: required configuration parameters --- _docs_operate/configuration.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index d373c7b12..e072f677d 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -237,9 +237,9 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT configure the CORS middleware. Valid options can be found [here](https://github.com/expressjs/cors#configuration-options). -- **apiKey** `required` +- **apiKey** `optional` - For an productive connector one or more of the three configs (**apiKey**, **oidc**, **jwtBearer**) is required. + For a productive Connector at least one of the three configuration parameters **apiKey**, **oidc** and **jwtBearer** must be set. {: .notice--info} Define the API-Key the Connector should use to authenticate requests. @@ -250,21 +250,21 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT The API-Key protects your Connector from unauthorized access and should therefore be kept secret. -- **oidc** `required` +- **oidc** `optional` - Defines the setting for the connection to you OIDC server. + Defines the setting for the connection to your OIDC server. - The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) + The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html). - Because the oidc process requires an redirect this type of authentication is only available when the user cales the connector via browser + Because the OIDC process requires an redirect this type of authentication is only available when the user cales the Connector via browser. -- **jwtBearer** `required` +- **jwtBearer** `optional` - Defines the setting for the oauth2 jwt bearer authorization. + Defines the setting for the OAuth 2.0 JWT bearer authorization. The full configuration can be found [here](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html). - The jwt token from the oauth provider needs to be send via the "Authorizaion" header with the Bearer prefix. + The JWT from the OAuth 2.0 provider needs to be send via the `Authorizaion` header with the Bearer prefix. - **helmetOptions** `default: depending on the Connector mode` From 1113551aa375d3be64c0b101b9b5ff5295c63ef8 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 4 Jul 2025 14:08:41 +0000 Subject: [PATCH 6/8] feat: add info text to other configuration parameters as well --- _docs_operate/configuration.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index e072f677d..dbfe03222 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -252,6 +252,9 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT - **oidc** `optional` + For a productive Connector at least one of the three configuration parameters **apiKey**, **oidc** and **jwtBearer** must be set. + {: .notice--info} + Defines the setting for the connection to your OIDC server. The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html). @@ -260,6 +263,9 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT - **jwtBearer** `optional` + For a productive Connector at least one of the three configuration parameters **apiKey**, **oidc** and **jwtBearer** must be set. + {: .notice--info} + Defines the setting for the OAuth 2.0 JWT bearer authorization. The full configuration can be found [here](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html). From e7eb6df113fb17108b8e2de9b1556635f36b8ace Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 4 Jul 2025 14:25:06 +0000 Subject: [PATCH 7/8] fix: formatting --- _docs_operate/configuration.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index dbfe03222..19b7e984d 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -386,7 +386,6 @@ It is not recommended to use this Module for production scenarios. Here you can define multiple brokers to which the Connector should publish messages. Each broker consists of a `type` (string) and a `configuration` object. The `type` specifies the type of the broker (e.g. `AMQP` or `PubSub`) and the `configuration` object contains the configuration for the broker. - - type `AMQP` **example** @@ -402,7 +401,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` - the URL of the AMQP broker @@ -431,7 +429,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` the URL of the MQTT broker @@ -454,7 +451,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - projectId `string, required` the project id of the Google Cloud project @@ -481,7 +477,6 @@ It is not recommended to use this Module for production scenarios. ``` **configuration** - - url `string, required` the URL of the broker @@ -548,7 +543,6 @@ It is not recommended to use this Module for production scenarios. **OAuth2** The OAuth2 authentication type is used to authenticate the request to the webhook using the client credentials flow of OAuth2. The Connector will send a bearer token as part of the request in its Authentication header. The OAuth2 authentication is configured using the following parameters: - - **type** `"OAuth2", required` The type of the authentication. @@ -572,7 +566,6 @@ It is not recommended to use this Module for production scenarios. **ApiKey** The ApiKey authentication type is used to authenticate the request to the webhook using an API key. The Connector will send the API key as part of the request using a header. The ApiKey authentication is configured using the following parameters: - - **type** `"ApiKey", required` The type of the authentication. From 29097ecbadc6e97639174227af523a81ce6c174f Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 11 Jul 2025 14:37:25 +0000 Subject: [PATCH 8/8] fix: typo --- _docs_operate/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 19b7e984d..c1edbd359 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -259,7 +259,7 @@ The HTTP server is the base for the `coreHttpApi` Module. It opens an express HT The full configuration can be found [here](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html). - Because the OIDC process requires an redirect this type of authentication is only available when the user cales the Connector via browser. + Because the OIDC process requires a redirect this type of authentication is only available when the user cales the Connector via browser. - **jwtBearer** `optional`