Add documentation for JWT Bearer authorization

_docs_operate/configuration.md

@@ -351,10 +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]({% 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.
-    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.
 
 ###### jwtBearer
 
@@ -370,7 +368,12 @@ 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 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:
 
 - **enabled** `default: true (if other options are configured)`
 

_docs_operate/security-considerations.md

@@ -94,14 +94,28 @@ 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
 
 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.