PEX: Documentation on how a Policy maps Constraint Field IDs

Author: reinkrul

docs/pages/deployment/pex.rst

@@ -22,71 +22,82 @@ To use file-based configuration, you need to define the path to a directory that
 .. code-block:: yaml
 
     policy:
-        directory: /path/to/directory
+      directory: /path/to/directory
 
 All JSON files in the directory will be loaded and used to define the mapping between scopes and presentation definitions.
 
 To use a policy backend, you need to add the address of the policy backend to the configuration:
 
 .. code-block:: yaml
 
-	policy:
-		address: http://localhost:8080
+    policy:
+	  address: http://localhost:8080
 
 You cannot define both the directory and the address in the configuration. If both are defined, an error will be raised at startup.
 
-File-based configuration
-************************
+Policy Structure
+****************
 
-JSON files used for file-based configuration must have the following structure:
+JSON documents used for policies must have the following structure:
 
 .. code-block:: json
 
-	{
-		"example_scope": {
-			"organization": {
-				"id": "example",
-				"format": {
-					"ldp_vc": {
-						"proof_type": ["JsonWebSignature2020"]
-					},
-					"ldp_vp": {
-						"proof_type": ["JsonWebSignature2020"]
-					}
-				},
-				"definition": {
-					"input_descriptors": [
-						{
-							"id": "1",
-							"constraints": {
-								"fields": [
-									{
-										"path": ["$.type"],
-										"filter": {
-											"type": "string",
-											"const": "ExampleCredential"
-										}
-									}
-								]
-							}
-						}
-					]
-				}
-			}
-		}
-	}
-
-Where `example_scope` is the scope that the presentation definition is associated with.
-The `presentation_definition` object contains the presentation definition that should be used for the given scope.
-The `wallet_owner_type` field is used to determine the audience type of the presentation definition, valid values are `organization` and `user`.
+  {
+    "example_scope": {
+      "organization": {
+        "id": "example",
+        "format": {
+          "ldp_vc": {
+            "proof_type": ["JsonWebSignature2020"]
+          },
+          "ldp_vp": {
+            "proof_type": ["JsonWebSignature2020"]
+          }
+        },
+        "definition": {
+          "input_descriptors": [
+            {
+              "id": "1",
+              "constraints": {
+                "fields": [
+                  {
+                    "id": "example_credential_type",
+                    "path": ["$.type"],
+                    "filter": {
+                      "type": "string",
+                      "const": "ExampleCredential"
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  }
+
+Where ``example_scope`` is the scope that the presentation definition is associated with.
+The ``presentation_definition`` object contains the presentation definition that should be used for the given scope.
+The ``wallet_owner_type`` field is used to determine the audience type of the presentation definition, valid values are ``organization`` and ``user``.
+
+OAuth2 Token Introspection field mapping
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The fields that contain an ``id`` property (e.g., ``example_credential_type`` in the example above) are returned in the OAuth2 Token Introspection response.
+The value of the Verifiable Credential that the matched field constraint are included in the response as claims.
+Writer of policies should take into consideration:
+- fields that are intended to be used for logging or authorization decisions should have a distinct identifier.
+- claims ideally map a registered claim name.
+- overwriting properties already defined in the token introspection endpoint response is forbidden.
 
 Policy backend API definition
 *****************************
 
 The policy backend API is defined in the `OpenAPI 3.x <https://spec.openapis.org/oas/latest.html>`_ format.
 The API must have the following endpoint:
 
-- `GET /presentation_definitions?scope=X&authorizer=Y`: Get the presentation definition for a given scope and tenant.
+- ``GET /presentation_definitions?scope=X&authorizer=Y``: Get the presentation definition for a given scope and tenant.
 
 The full API definition can be downloaded `here <../../_static/policy/v1.yaml>`_.