[eclipse-ditto#926] Mention in documentation the requirement for READ…

… permission granted on things by the policy action activateTokenIntegration.

Signed-off-by: Yufei Cai <yufei.cai@bosch.io>

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -3464,8 +3464,8 @@ paths:
       summary: Activate token integration subjects for this policy
       description: |-
         Only possible with JWT authentication.
-        For each entry the user is granted the EXECUTE permission, inject a subject calculated according to the JWT
-        with which the user is authenticated.
+        For each entry the user is granted the EXECUTE permission and contains a READ permission granted to
+        a things resource path, inject a subject calculated according to the JWT with which the user is authenticated.
         This subject is configurable.
         The injected subjects expire when the JWT expires.
       tags:
@@ -3911,8 +3911,9 @@ paths:
       summary: Activate the token integration subject for this policy entry
       description: |-
         Only possible with JWT authentication.
-        If the user is granted the EXECUTE permission for this entry, inject a subject calculated according to the JWT
-        with which the user is authenticated.
+        If this entry contains a READ permission granted to a things resource path
+        and the user is granted the EXECUTE permission for this entry,
+        inject a subject calculated according to the JWT with which the user is authenticated.
         This subject is configurable.
         The injected subject expires when the JWT expires.
       tags:

documentation/src/main/resources/openapi/sources/paths/policies/activateTokenIntegration.yml

@@ -12,8 +12,8 @@ post:
   summary: Activate token integration subjects for this policy
   description: |-
     Only possible with JWT authentication.
-    For each entry the user is granted the EXECUTE permission, inject a subject calculated according to the JWT
-    with which the user is authenticated.
+    For each entry the user is granted the EXECUTE permission and contains a READ permission granted to
+    a things resource path, inject a subject calculated according to the JWT with which the user is authenticated.
     This subject is configurable.
     The injected subjects expire when the JWT expires.
   tags:

documentation/src/main/resources/openapi/sources/paths/policies/activateTokenIntegrationForEntry.yml

@@ -12,8 +12,9 @@ post:
   summary: Activate the token integration subject for this policy entry
   description: |-
     Only possible with JWT authentication.
-    If the user is granted the EXECUTE permission for this entry, inject a subject calculated according to the JWT
-    with which the user is authenticated.
+    If this entry contains a READ permission granted to a things resource path
+    and the user is granted the EXECUTE permission for this entry,
+    inject a subject calculated according to the JWT with which the user is authenticated.
     This subject is configurable.
     The injected subject expires when the JWT expires.
   tags:

documentation/src/main/resources/pages/ditto/basic-policy.md

@@ -76,6 +76,9 @@ to the following HTTP routes:
 - [POST /api/2/policies/{policy-id}/entries/{label}/actions/deactivateTokenIntegration](/http-api-doc.html#/Policies/post_policies__policyId__entries__label__actions_deactivateTokenIntegration)<br/>
   Remove the token integration subject from 1 policy entry.
 
+The action `activateTokenIntegration` only injects the token integration subject into policy entries containing
+a granted `READ` permission for a thing resource path.
+
 To configure the token integration subject, set the path
 ```
 ditto.gateway.authentication.oauth.token-integration-subject