From 04b42d13384c7fc67c3ea66fd514ba7971dd51db Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Wed, 27 Aug 2025 15:50:52 +0000 Subject: [PATCH 01/12] fix: unprecise description of wildcard * --- _docs_operate/configuration.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index c61c11918..e10f15cfe 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -353,8 +353,11 @@ The `apiKey` authentication method is used to authenticate requests using an API An optional array of strings that defines roles, specifying the permissions granted to anyone using the API key. By default, administrator rights are assigned, represented explicitly by `"**"`, providing unrestricted access. Roles can also be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. - A wildcard `"*"` can be used within a namespace to allow access to every resource in that namespace. - For instance, `core:*` allows access to `core:messages`, `core:relationships`, and any other resources within the `core` namespace. + A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. + For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. + However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. + To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. + For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. ###### jwtBearer From ffd4ff9c80c34e0b06f922e1f91f92f49806bc45 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Wed, 27 Aug 2025 16:00:33 +0000 Subject: [PATCH 02/12] feat: add list of top-level namespaces --- _docs_operate/configuration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index e10f15cfe..6abbaff52 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -358,6 +358,7 @@ The `apiKey` authentication method is used to authenticate requests using an API However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. + Overall, there are the `core`, `debug`, and `monitoring` top-level namespaces. ###### jwtBearer From 36c17a55561a9de76d34d1b5c09b4ab5d87aff6b Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Thu, 28 Aug 2025 16:39:46 +0000 Subject: [PATCH 03/12] feat: add complete list of sub-resources and omit debug namespace --- _docs_operate/configuration.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 6abbaff52..1e23d1f10 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -358,7 +358,10 @@ The `apiKey` authentication method is used to authenticate requests using an API However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. - Overall, there are the `core`, `debug`, and `monitoring` top-level namespaces. + + Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: + - `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. + - `monitoring:requests`, `monitoring:support` and `monitoring:version`. ###### jwtBearer From 96f3f3fbbfa55aa4ad81ca285c1f06505c986b97 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 29 Aug 2025 14:54:13 +0000 Subject: [PATCH 04/12] feat: introduce auth property of JWT Bearer and rolesPath property of OIDC --- _docs_operate/configuration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 1e23d1f10..531e386b1 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -391,6 +391,10 @@ The `jwtBearer` authentication method is used to authenticate requests using JSO The audience of the JWT. This is the identifier of the Connector in your identity server. +- **auth** `optional` + + In the `scope` of the `payload` of the `auth`, roles can be defined. + For more sophisticated use cases, please refer to the [JWT documentation page](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) where all possibilities are explained in detail. ###### oidc @@ -431,6 +435,10 @@ The `oidc` authentication method is used to authenticate requests using the Open The secret(s) of the Connector used to derive an encryption key for the user identity in a stateless session cookie. +- **rolesPath** `optional` + + With the `rolesPath`, it can be specified where the roles are defined within the OIDC `user` info. + For more sophisticated use cases, please refer to the [OIDC documentation page](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) where all possibilities are explained in detail. ### modules From 946681181ddd345868adec067be515df68f59b25 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 29 Aug 2025 15:37:54 +0000 Subject: [PATCH 05/12] refactor: move permission model to own section --- _docs_operate/configuration.md | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 531e386b1..5e2076a6b 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -351,17 +351,8 @@ The `apiKey` authentication method is used to authenticate requests using an API - **scopes** `optional` An optional array of strings that defines roles, specifying the permissions granted to anyone using the API key. + These roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to control which resources are available. By default, administrator rights are assigned, represented explicitly by `"**"`, providing unrestricted access. - Roles can also be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. - A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. - For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. - However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. - To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. - For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. - - Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: - - `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. - - `monitoring:requests`, `monitoring:support` and `monitoring:version`. ###### jwtBearer @@ -393,7 +384,9 @@ The `jwtBearer` authentication method is used to authenticate requests using JSO - **auth** `optional` - In the `scope` of the `payload` of the `auth`, roles can be defined. + The roles that determine the permissions granted to anyone authenticated with the JWT bearer token are defined within `auth.payload.scope`. + These roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to control which resources are available. + By default, no rights are assigned, providing limited access. For more sophisticated use cases, please refer to the [JWT documentation page](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) where all possibilities are explained in detail. @@ -437,10 +430,26 @@ The `oidc` authentication method is used to authenticate requests using the Open - **rolesPath** `optional` - With the `rolesPath`, it can be specified where the roles are defined within the OIDC `user` info. + The JSON path inside the OIDC `user` object where the list of roles assigned to the authenticated user can be found. + The extracted roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to determine what resources the user is allowed to access. + By default, no rights are assigned, providing limited access. For more sophisticated use cases, please refer to the [OIDC documentation page](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) where all possibilities are explained in detail. +###### Permission Model of the Connector + +Roles across different [authentication](#authentication) methods for the Connector are defined in a consistent format, specifying how they map to the Connector’s permission model. +Roles can be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. +A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. +For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. +However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. +To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. +For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. +Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: + +- `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. +- `monitoring:requests`, `monitoring:support` and `monitoring:version`. + ### modules Every Module can be enabled or disabled by passing true / false to `enabled`. Read more about the Module by clicking on the icon in each title. From e89d9a6c1bd0b9026dd2035b7d193f7e7d571b9a Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 29 Aug 2025 15:41:27 +0000 Subject: [PATCH 06/12] feat: add information that config of roles vary between IDPs --- _docs_operate/configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 5e2076a6b..318b38fc2 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -384,7 +384,8 @@ The `jwtBearer` authentication method is used to authenticate requests using JSO - **auth** `optional` - The roles that determine the permissions granted to anyone authenticated with the JWT bearer token are defined within `auth.payload.scope`. + The roles that determine the permissions granted to anyone authenticated with the JWT bearer token can be defined within `auth.payload.scope`. + This may vary between identity providers. These roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to control which resources are available. By default, no rights are assigned, providing limited access. From c6911c25a25f40fe5b21615d6ac496c3d1bfb772 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Fri, 29 Aug 2025 15:45:06 +0000 Subject: [PATCH 07/12] feat: mention possibility of custom structure for roles --- _docs_operate/configuration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 318b38fc2..f7f6d3698 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -451,6 +451,8 @@ Overall, there are the `core` and `monitoring` top-level namespaces with the fol - `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. - `monitoring:requests`, `monitoring:support` and `monitoring:version`. +However, it is possible to assign roles following a custom structure for custom functionality. + ### modules Every Module can be enabled or disabled by passing true / false to `enabled`. Read more about the Module by clicking on the icon in each title. From 91f0e10ef8dc8f2ab5ac694a941ac596ea10cd08 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Mon, 1 Sep 2025 11:40:41 +0000 Subject: [PATCH 08/12] refactor: omit workaround --- _docs_operate/configuration.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index f7f6d3698..5adcebf6c 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -429,12 +429,6 @@ The `oidc` authentication method is used to authenticate requests using the Open The secret(s) of the Connector used to derive an encryption key for the user identity in a stateless session cookie. -- **rolesPath** `optional` - - The JSON path inside the OIDC `user` object where the list of roles assigned to the authenticated user can be found. - The extracted roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to determine what resources the user is allowed to access. - By default, no rights are assigned, providing limited access. - For more sophisticated use cases, please refer to the [OIDC documentation page](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) where all possibilities are explained in detail. ###### Permission Model of the Connector From 4486270c5f1f6bff816db9d622e647d99027f740 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Mon, 1 Sep 2025 15:32:48 +0000 Subject: [PATCH 09/12] refactor: move permission model to security section --- _docs_operate/configuration.md | 20 ++------------------ _docs_operate/security-considerations.md | 16 ++++++++++++++++ 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 5adcebf6c..52f852366 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -351,7 +351,7 @@ The `apiKey` authentication method is used to authenticate requests using an API - **scopes** `optional` An optional array of strings that defines roles, specifying the permissions granted to anyone using the API key. - These roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to control which resources are available. + These roles are matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are available. By default, administrator rights are assigned, represented explicitly by `"**"`, providing unrestricted access. ###### jwtBearer @@ -386,7 +386,7 @@ The `jwtBearer` authentication method is used to authenticate requests using JSO The roles that determine the permissions granted to anyone authenticated with the JWT bearer token can be defined within `auth.payload.scope`. This may vary between identity providers. - These roles are matched against the [Connector’s permission model](#permission-model-of-the-connector) to control which resources are available. + These roles are matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are available. By default, no rights are assigned, providing limited access. For more sophisticated use cases, please refer to the [JWT documentation page](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) where all possibilities are explained in detail. @@ -431,22 +431,6 @@ The `oidc` authentication method is used to authenticate requests using the Open For more sophisticated use cases, please refer to the [OIDC documentation page](https://auth0.github.io/express-openid-connect/interfaces/ConfigParams.html) where all possibilities are explained in detail. -###### Permission Model of the Connector - -Roles across different [authentication](#authentication) methods for the Connector are defined in a consistent format, specifying how they map to the Connector’s permission model. -Roles can be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. -A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. -For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. -However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. -To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. -For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. -Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: - -- `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. -- `monitoring:requests`, `monitoring:support` and `monitoring:version`. - -However, it is possible to assign roles following a custom structure for custom functionality. - ### modules Every Module can be enabled or disabled by passing true / false to `enabled`. Read more about the Module by clicking on the icon in each title. diff --git a/_docs_operate/security-considerations.md b/_docs_operate/security-considerations.md index aa33cc160..d416a292c 100644 --- a/_docs_operate/security-considerations.md +++ b/_docs_operate/security-considerations.md @@ -102,6 +102,22 @@ End user authentication, e.g. business users accessing the system, should be don It is important to ensure that API-keys are secure and cannot be easily compromised. One of the key aspects of API-key security is regular rotation and expiration which we recommend. If an API-key is not rotated or expired, it can potentially be used by an attacker who has obtained the key through unauthorized means. +### Permission Model of the Connector + +Roles across different [authentication]({% link _docs_operate/configuration.md %}#authentication) methods for the Connector are defined in a consistent format, specifying how they map to the Connector’s permission model. +Roles can be limited to specific resources, for example, `"core:messages"` allows access only to the Connector routes related to messages. +A wildcard `"*"` can be used within a namespace to allow access to all top-level resources in that namespace. +For instance, `core:*` allows access to `core:messages`, `core:requests`, and any other top-level resources within the `core` namespace. +However, it does not grant access to deeper sub-resources such as `core:requests:incoming`. +To allow access to a resource and all of its sub-resources recursively, `"**"` can be utilized. +For example, `core:**` grants access to `core:requests`, `core:requests:incoming`, and any other deeper sub-resources under the `core` namespace. +Overall, there are the `core` and `monitoring` top-level namespaces with the following sub-resources: + +- `core:account`, `core:announcements`, `core:attributes`, `core:backboneNotifications`, `core:challenges`, `core:files`, `core:identityMetadata`, `core:messages`, `core:requests`, `core:requests:incoming`, `core:requests:outgoing`, `core:relationshipTemplates`, `core:relationships` and `core:tokens`. +- `monitoring:requests`, `monitoring:support` and `monitoring:version`. + +However, it is possible to assign roles following a custom structure for custom functionality. + ## Kernel Dumps Kernel dumps can be a useful tool for diagnosing and troubleshooting system issues. However, they can also be a security risk if they contain sensitive information such as encryption keys. If an attacker gains access to a kernel dump file, they may be able to extract this information and use it to compromise the security of your system. From fbbf9db15662c4e93b57e8b2f9a17fa0730001de Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Mon, 1 Sep 2025 15:34:35 +0000 Subject: [PATCH 10/12] fix: outdated sentence --- _docs_operate/security-considerations.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/_docs_operate/security-considerations.md b/_docs_operate/security-considerations.md index d416a292c..51225c2ad 100644 --- a/_docs_operate/security-considerations.md +++ b/_docs_operate/security-considerations.md @@ -94,8 +94,6 @@ Certificate pinning adds additional effort to the Connector administrators, as f So far, the Connector supports API-key authentication to securely authenticate technical users. These API-Keys are random character strings with a high entropy and should be kept confidential at all times. Each internal system communicating with the Connector should receive its own API-Key. -There is no authorization set up, thus every API-key can call any API of the Connector API. - End user authentication, e.g. business users accessing the system, should be done on the respective business system. Usually, there is no need for end users to access the Connector and thus they should not have access to the Connector (from a network and authentication perspective). ### API-key rotation From a6ccf8ec802d76d849297eb0d6736f487d87e30c Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Wed, 3 Sep 2025 11:03:21 +0000 Subject: [PATCH 11/12] refactor: move jwtBearer scope text --- _docs_operate/configuration.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index 52f852366..ca33ea555 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -368,7 +368,13 @@ The `apiKey` authentication method is used to authenticate requests using an API } ``` -The `jwtBearer` authentication method is used to authenticate requests using JSON Web Tokens (JWT). To configure this authentication method, you need to provide at least the following parameters: +The `jwtBearer` authentication method is used to authenticate requests using JSON Web Tokens (JWT). +The permissions available to anyone authenticated with a JWT bearer token are determined by its scope. +The scope is a space-separated list of segments, and each segment is treated as a role. +Depending on the identity provider, the roles may be stored within `auth.payload.scope` or a different field. +These roles are then matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are accessible. +By default, no rights are assigned, providing limited access. +To configure the `jwtBearer` authentication method, you need to provide at least the following parameters: - **enabled** `default: true (if other options are configured)` @@ -382,13 +388,6 @@ The `jwtBearer` authentication method is used to authenticate requests using JSO The audience of the JWT. This is the identifier of the Connector in your identity server. -- **auth** `optional` - - The roles that determine the permissions granted to anyone authenticated with the JWT bearer token can be defined within `auth.payload.scope`. - This may vary between identity providers. - These roles are matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are available. - By default, no rights are assigned, providing limited access. - For more sophisticated use cases, please refer to the [JWT documentation page](https://auth0.github.io/node-oauth2-jwt-bearer/interfaces/AuthOptions.html) where all possibilities are explained in detail. ###### oidc From d4b39195ed0ed403db8d37a1755f847153f182cc Mon Sep 17 00:00:00 2001 From: Britta Stallknecht Date: Wed, 3 Sep 2025 14:16:40 +0000 Subject: [PATCH 12/12] refactor: rephrase jwtBearer scope explanation --- _docs_operate/configuration.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_docs_operate/configuration.md b/_docs_operate/configuration.md index ca33ea555..4c2b889aa 100644 --- a/_docs_operate/configuration.md +++ b/_docs_operate/configuration.md @@ -369,9 +369,8 @@ The `apiKey` authentication method is used to authenticate requests using an API ``` The `jwtBearer` authentication method is used to authenticate requests using JSON Web Tokens (JWT). -The permissions available to anyone authenticated with a JWT bearer token are determined by its scope. -The scope is a space-separated list of segments, and each segment is treated as a role. -Depending on the identity provider, the roles may be stored within `auth.payload.scope` or a different field. +The permissions available to anyone authenticated with a JWT bearer token are determined by the scope of the JWT payload. +Depending on the identity provider, roles may be provided in a different way and need to be mapped into the scope. These roles are then matched against the [Connector’s permission model]({% link _docs_operate/security-considerations.md %}#permission-model-of-the-connector) to control which resources are accessible. By default, no rights are assigned, providing limited access. To configure the `jwtBearer` authentication method, you need to provide at least the following parameters: