#926: inject configurable policy subjects into policies via new added JWT evaluating policy action

Jenkinsfile_multibranch_pipeline

@@ -43,7 +43,7 @@ pipeline {
             }
             steps {
                 configFileProvider([configFile(fileId: 'mvn-bdc-settings', variable: 'MVN_SETTINGS')]) {
-                    sh "mvn -s $MVN_SETTINGS clean deploy source:jar " +
+                    sh "mvn -s $MVN_SETTINGS clean deploy javadoc:jar source:jar " +
                                "-T1C --batch-mode --errors " +
                                "-Pbuild-documentation,ditto " +
                                "-Drevision=${theVersion} " +

deployment/docker/docker-compose.yml

@@ -132,7 +132,7 @@ services:
       - TZ=Europe/Berlin
       - INSTANCE_INDEX=1
       - BIND_HOSTNAME=0.0.0.0
-      - ENABLE_DUMMY_AUTH=true
+      - ENABLE_PRE_AUTHENTICATION=true
       - OPENJ9_JAVA_OPTIONS=-XX:+ExitOnOutOfMemoryError -Xtune:virtualized -Xss512k -XX:MaxRAMPercentage=80 -Dakka.coordinated-shutdown.exit-jvm=on -Dakka.cluster.shutdown-after-unsuccessful-join-seed-nodes=120s
       # You may use the environment for setting the devops password
       #- DEVOPS_PASSWORD=foobar

deployment/docker/sandbox/docker-compose.yml

@@ -116,7 +116,7 @@ services:
       - TZ=Europe/Berlin
       - INSTANCE_INDEX=1
       - BIND_HOSTNAME=0.0.0.0
-      - ENABLE_DUMMY_AUTH=true
+      - ENABLE_PRE_AUTHENTICATION=true
       - DEVOPS_SECURE_STATUS=false
       - OPENJ9_JAVA_OPTIONS=-XX:+ExitOnOutOfMemoryError -Xtune:virtualized -Xss512k -XX:MaxRAMPercentage=80 -Dakka.coordinated-shutdown.exit-jvm=on -Dakka.cluster.shutdown-after-unsuccessful-join-seed-nodes=120s
 

deployment/kubernetes/ditto/ditto-cluster.yaml

@@ -355,7 +355,7 @@ spec:
           timeoutSeconds: 3
           failureThreshold: 4
         env:
-        - name: ENABLE_DUMMY_AUTH
+        - name: ENABLE_PRE_AUTHENTICATION
           value: "true"
         - name: INSTANCE_INDEX
           valueFrom:

deployment/openshift/ditto/ditto-cluster.yaml

@@ -437,7 +437,7 @@ spec:
             # cpu: "" no cpu limit to avoid CFS scheduler limits see https://doc.akka.io/docs/akka/snapshot/additional/deploy.html#in-kubernetes
             memory: "512Mi"
         env:
-        - name: ENABLE_DUMMY_AUTH
+        - name: ENABLE_PRE_AUTHENTICATION
           value: "true"
         - name: INSTANCE_INDEX
           valueFrom:

documentation/src/main/resources/_posts/2021-01-22-policy-subject-activate-token-integration.md

@@ -0,0 +1,190 @@
+---
+title: "Policy actions: token based subject activation"
+published: true
+permalink: 2021-01-22-policy-subject-activate-token-integration.html
+layout: post
+author: thomas_jaeckle
+tags: [blog]
+hide_sidebar: true
+sidebar: false
+toc: true
+---
+
+The upcoming version of Eclipse Ditto **2.0.0** will be enhanced with the ability to 
+[alter policies based on policy actions](basic-policy.html#actions).
+
+## Policy actions
+
+This new concept of [Policy actions](basic-policy.html#actions) allows upfront defined modifications to policies without 
+the need for the one invoking the action to have "WRITE" permissions granted on the policy.
+
+## Token based activation of subject
+
+Together with the concept of actions, a first action named 
+[`activateTokenIntegration`](basic-policy.html#action-activatetokenintegration) is added.  
+This action
+* only works when using <a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jwt}}">JWT</a> 
+  based authentication issued by Google or other OpenID Connect providers as 
+  [documented in the installation/operation guide](installation-operating.html#openid-connect)
+* checks whether the [authenticated subjects](basic-auth.html#authenticated-subjects) which invoked the action have the 
+  permission to `EXECUTE` the action on a policy entry
+* checks whether the [authenticated subjects](basic-auth.html#authenticated-subjects) which invoked the action have at 
+  least some kind of `READ` permission to any `thing:/` resource in a policy entry
+
+When all the conditions were met for a policy entry, the action will inject a new [subject](basic-policy.html#subjects) 
+into the matched policy entry which by default (the 
+[pattern is configurable](basic-policy.html#action-activatetokenintegration)) is the following.
+This syntax uses [placeholders](basic-placeholders.html) in order to extract information from the authenticated JWT and 
+the policy entry:
+```
+{%raw%}
+integration:{{policy-entry:label}}:{{jwt:aud}}
+{%endraw%}
+```
+
+The value of the injected subject will contain the [expiry](basic-policy.html#expiring-policy-subjects) timestamp 
+copied from the JWT `"exp"` (the expiration time of the token) claim.
+
+## Example use case
+
+Assuming that you have configured a custom OpenID Connect provider `some-openid-connect-provider` as
+[documented in the installation/operation guide](installation-operating.html#openid-connect):
+```
+ditto.gateway.authentication {
+  oauth {
+    openid-connect-issuers = {
+      some-openid-connect-provider = "https://some-openid-connect-provider.com"
+    }
+  }
+}
+```
+
+Let's describe our scenario:  
+* It is required to enable that a Ditto [connection](basic-connections.html) (e.g. an 
+[HTTP connection](connectivity-protocol-bindings-http.html) invoking an HTTP webhook) shall receive events whenever 
+the temperature of a twin is modified
+* For security reasons however, the webhook shall not receive events longer than the expiration time of the JWT which 
+was used in order to activate the webhook
+* The webhook can be extended by invoking the action again before the "expiry" time was reached
+
+The underlying [policy](basic-policy.html) shall be the following one:
+```json
+{
+  "policyId": "my.namespace:policy-a",
+  "entries": {
+    "owner": {
+      "subjects": {
+        "some-openid-connect-provider:some-admin-id": {
+          "type": "authenticated via OpenID connect provider <some-openid-connect-provider>"
+        }
+      },
+      "resources": {
+        "thing:/": {
+          "grant": ["READ", "WRITE"],
+          "revoke": []
+        },
+        "policy:/": {
+          "grant": ["READ", "WRITE"],
+          "revoke": []
+        }
+      }
+    },
+    "temperature-observer": {
+      "subjects": {
+        "some-openid-connect-provider:some-user-id": {
+          "type": "authenticated via OpenID connect provider <some-openid-connect-provider>"
+        }
+      },
+      "resources": {
+        "thing:/features/temperature": {
+          "grant": ["READ"],
+          "revoke": []
+        },
+        "policy:/entries/temperature-observer/actions/activateTokenIntegration": {
+          "grant": ["EXECUTE"],
+          "revoke": []
+        }
+      }
+    }
+  }
+}
+```
+
+The policy entry `"temperature-observer"` above describes that:
+* the user "some-user-id" may `READ` the `"temperature"` feature of things using this policy
+* is allowed to `EXECUTE` the `activateTokenIntegration` action in order to inject a subject derived from his provided 
+  JWT
+
+Let's assume that the authenticated JWT used for executing the action contained the following claims:
+```json
+{
+  "iss": "https://some-openid-connect-provider.com",
+  "sub": "some-user-id",
+  "exp": 1622802633,
+  "aud": "some-specific-audience-0815"
+}
+```
+
+The "exp" field contains the token expiry timestamp (seconds since epoch) and resolves to: 
+`Friday, June 4, 2021 10:30:33 AM`.
+
+Once the HTTP API 
+[POST /api/2/policies/{policyId}/entries/{label}/actions/activateTokenIntegration](/http-api-doc.html#/Policies/post_policies__policyId__entries__label__actions_activateTokenIntegration), with `policyId=my.namespace:policy-a` and `label=temperature-observer`,  
+is invoked (without any payload), a new subject will be injected when the 
+[described prerequisites](basic-policy.html#action-activatetokenintegration) were enforced successfully.
+
+As a simplification, all possible policy entries may be injected with the subject by invoking the top level action  
+[POST /api/2/policies/{policyId}/actions/activateTokenIntegration](/http-api-doc.html#/Policies/post_policies__policyId__actions_activateTokenIntegration), with `policyId=my.namespace:policy-a`.
+
+The value of the injected subject will contain the expiration timestamp from the JWT, so the injected policy subject 
+`integration:temperature-observer:some-specific-audience-0815` will result in a modified policy:
+```json
+{
+  "policyId": "my.namespace:policy-a",
+  "entries": {
+    "owner": { // unchanged ... },
+    "temperature-observer": {
+      "subjects": {
+        "some-openid-connect-provider:some-user-id": {
+          "type": "authenticated via OpenID connect provider <some-openid-connect-provider>"
+        },
+        "integration:temperature-observer:some-specific-audience-0815": {
+          "type": "added via action <activateTokenIntegration>",
+          "expiry": "2021-06-04T10:30:33Z"
+        }
+      },
+      "resources": {
+        "thing:/features/temperature": {
+          "grant": ["READ"],
+          "revoke": []
+        },
+        "policy:/entries/temperature-observer/actions/activateTokenIntegration": {
+          "grant": ["EXECUTE"],
+          "revoke": []
+        }
+      }
+    }
+  }
+}
+```
+
+When we now have a 
+managed HTTP connection which [configures the `authorizationContext`](basic-connections.html#authorization) to include
+the subject `integration:temperature-observer:some-specific-audience-0815` for a 
+[connection target](basic-connections.html#targets), this connection is allowed to publish changes to the temperature of 
+all things using the above policy until the `"expiry"` timestamp was reached.  
+Afterwards, publishing changes automatically stops, unless the action is invoked again with a JWT having a longer "exp"
+time prolonging the injected policy subject.
+
+
+## Feedback?
+
+Please [get in touch](feedback.html) if you have feedback or questions towards this new token based subject activation
+for policies.  
+Or do you have other use cases in mind you might be able to solve with this feature? Please let us know.
+
+<br/>
+<br/>
+{% include image.html file="ditto.svg" alt="Ditto" max-width=500 %}
+--<br/>
+The Eclipse Ditto team

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

@@ -3459,6 +3459,68 @@ paths:
                 $ref: '#/components/schemas/AdvancedError'
         '412':
           $ref: '#/components/responses/PreconditionFailed'
+  '/policies/{policyId}/actions/activateTokenIntegration':
+    post:
+      summary: Activate subjects for this policy derived from the token
+      description: |-
+        **This action only works when authenticated with a Json Web Token (JWT).**
+
+        Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
+        * the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
+        * one of the subject IDs is contained in the authenticated token
+        * at least one `READ` permission to a `thing:/` resource path is granted
+
+        a new subject is **injected into the matched policy entry** calculated with information extracted from the
+        authenticated JWT.
+
+        The injected subjects expire when the JWT expires.
+      tags:
+        - Policies
+      parameters:
+        - $ref: '#/components/parameters/PolicyIdPathParam'
+      responses:
+        '204':
+          description: The request was successful. Subjects were injected into authorized policy entries.
+        '400':
+          description: The request could not be completed because the authentication was not performed with a JWT.
+        '403':
+          description: |-
+            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
+            entries of the policy.
+        '404':
+          description: |-
+            The request could not be completed because no policy entry matched the following conditions:
+            * containing a a subject ID matching the JWT's authenticated subject
+            * containing a `READ` permission granted to a `thing:/` resource path
+  '/policies/{policyId}/actions/deactivateTokenIntegration':
+    post:
+      summary: Deactivate subjects for this policy derived from the token
+      description: |-
+        **This action only works when authenticated with a Json Web Token (JWT).**
+
+        Based on the authenticated token (JWT), **for each policy entry** matching those conditions:
+        * the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
+        * one of the subject IDs is contained in the authenticated token
+
+        the calculated subject with information extracted from the authenticated JWT is **removed
+        from the matched policy entry**.
+      tags:
+        - Policies
+      parameters:
+        - $ref: '#/components/parameters/PolicyIdPathParam'
+      responses:
+        '204':
+          description: The request was successful. Subjects were removed from authorized policy entries.
+        '400':
+          description: The request could not be completed because the authentication was not performed with a JWT.
+        '403':
+          description: |-
+            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on any
+            entries of the policy.
+        '404':
+          description: |-
+            The request could not be completed because no policy entry matched the following conditions:
+            * containing a a subject ID matching the JWT's authenticated subject
   '/policies/{policyId}/entries':
     get:
       summary: Retrieve the entries of a specific policy
@@ -3863,6 +3925,68 @@ paths:
                 $ref: '#/components/schemas/AdvancedError'
         '412':
           $ref: '#/components/responses/PreconditionFailed'
+  '/policies/{policyId}/entries/{label}/actions/activateTokenIntegration':
+    post:
+      summary: Activate a subject for this policy entry derived from the token
+      description: |-
+        **This action only works when authenticated with a Json Web Token (JWT).**
+
+        Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
+        * the authenticated token is granted the `EXECUTE` permission to perform the `activateTokenIntegration` action
+        * one of the subject IDs is contained in the authenticated token
+        * at least one `READ` permission to a `thing:/` resource path is granted
+
+        When all conditions match, a new subject is **injected into this policy entry** calculated with information
+        extracted from the authenticated JWT.
+
+        The injected subjects expire when the JWT expires.
+      tags:
+        - Policies
+      parameters:
+        - $ref: '#/components/parameters/PolicyIdPathParam'
+        - $ref: '#/components/parameters/LabelPathParam'
+      responses:
+        '204':
+          description: The request was successful. The subject was injected.
+        '400':
+          description: The request could not be completed because the authentication was not performed with a JWT.
+        '403':
+          description: |-
+            The request could not be completed because the authenticated JWT did not have the `EXECUTE` permission on this
+            policy entry.
+        '404':
+          description: |-
+            The request could not be completed because this policy entry did not match the following conditions:
+            * containing a a subject ID matching the JWT's authenticated subject
+            * containing a `READ` permission granted to a `thing:/` resource path
+  '/policies/{policyId}/entries/{label}/actions/deactivateTokenIntegration':
+    post:
+      summary: Deactivate a subject for this policy entry derived from the token
+      description: |-
+        **This action only works when authenticated with a Json Web Token (JWT).**
+
+        Based on the authenticated token (JWT), **this policy entry** is checked to match those conditions:
+        * the authenticated token is granted the `EXECUTE` permission to perform the `deactivateTokenIntegration` action
+        * one of the subject IDs is contained in the authenticated token
+
+        When all conditions match, the calculated subject with information extracted from the authenticated JWT is **removed
+        from this policy entry**.
+      tags:
+        - Policies
+      parameters:
+        - $ref: '#/components/parameters/PolicyIdPathParam'
+        - $ref: '#/components/parameters/LabelPathParam'
+      responses:
+        '204':
+          description: The request was successful. The subject was removed.
+        '400':
+          description: The request could not be completed because the authentication was not performed with a JWT.
+        '403':
+          description: The request could not be completed because the user did not have the `EXECUTE` permission on this policy entry.
+        '404':
+          description: |-
+            The request could not be completed because this policy entry did not match the following conditions:
+            * containing a a subject ID matching the JWT's authenticated subject
   '/policies/{policyId}/entries/{label}/subjects':
     get:
       summary: Retrieve all Subjects for a specific Label of a specific policy

documentation/src/main/resources/openapi/sources/api-2-index.yml

@@ -101,10 +101,18 @@ paths:
   ###
   '/policies/{policyId}':
     $ref: "./paths/policies/policy.yml"
+  '/policies/{policyId}/actions/activateTokenIntegration':
+    $ref: "./paths/policies/activateTokenIntegration.yml"
+  '/policies/{policyId}/actions/deactivateTokenIntegration':
+    $ref: "./paths/policies/deactivateTokenIntegration.yml"
   '/policies/{policyId}/entries':
     $ref: "./paths/policies/entries.yml"
   '/policies/{policyId}/entries/{label}':
     $ref: "./paths/policies/entry.yml"
+  '/policies/{policyId}/entries/{label}/actions/activateTokenIntegration':
+    $ref: "./paths/policies/activateTokenIntegrationForEntry.yml"
+  '/policies/{policyId}/entries/{label}/actions/deactivateTokenIntegration':
+    $ref: "./paths/policies/deactivateTokenIntegrationForEntry.yml"
   '/policies/{policyId}/entries/{label}/subjects':
     $ref: "./paths/policies/subjects.yml"
   '/policies/{policyId}/entries/{label}/subjects/{subjectId}':