Dynamic bridge endpoint

README.md

@@ -29,6 +29,10 @@ You operate a service and want to allow your users to sign in using Verifiable
 Credentials from a mobile wallet. But building that takes considerable time and
 expertise.
 
+Additionally, you may need an easy solution to dynamically request additional
+Verifiable Credentials from a user during a session (i.e., "incremental
+authorization"). That would once again require a completely custom solution.
+
 ### The Solution
 
 A service provider can run this dockerized bridge software that acts as a normal
@@ -38,7 +42,7 @@ Verifiable Credentials. When setting up the bridge software, you can configure
 what Verifiable Credentials are accepted and how the data within is put into
 `id_token` or `access_token`.
 
-As a contribution to Gaia-X infrastructure, the ultimate goal here is to enable
+As a contribution to Gaia-X infrastructure, the main goal here is to enable
 users to use their Gaia-X Participant Credentials to access systems while making
 integration simpler through the use of established SSO protocols. The bridge can
 also be configured to use other Verifiable Credentials.
@@ -147,6 +151,69 @@ sequenceDiagram
  Client->>Browser: Provide access to protected service
 ```
 
+## Incremental Authorization Flow
+
+Independent of an OIDC session, a service provider can request additional VCs
+from a user. For example, this can be used to incrementally authorize a user to
+interact with more parts of a service. An example is that users of a mobility
+platform could, at any point in time, unlock the car sharing aspect by
+presenting an additional driver's license VC.
+
+From a technical perspective, the service provider backend initiates the request
+by sending a login policy to a specific endpoint to create a temporary new
+authorization endpoint within the bridge. This has the advantage of reusing the
+bridge's existing verification and powerful policy system. A high-level flow
+looks like this:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant Wallet
+    participant B as SSI-to-OIDC Bridge
+    participant SP as Service Provider
+
+    SP ->> B: POST /api/dynamic/createTempAuthorization
+    B-->>SP: Return UUID, qrCodeString
+
+    SP->>User: Send Auth. page containing QR code
+
+    SP->>B: GET /api/dynamic/getAuthResponse
+    User->>Wallet: Scan QR code
+    Wallet->>B: GET /api/dynamic/presentCredentialById
+    B-->>Wallet: Return metadata
+    Wallet-->>User: Prompt user
+
+    User ->>Wallet: Select VC(s)
+    Wallet->>B: POST /api/dynamic/presentCredentialById
+    B-->>Wallet: Success
+
+    B-->>SP: Return Auth Response
+```
+
+### API Documentation
+
+This documentation provides all the necessary information to interact with the
+dynamic API endpoints used for incremental authorization. The API is documented
+using Swagger, which provides a user-friendly interface to explore and test the
+API.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> To access the Swagger documentation, run the bridge in development mode and
+> navigate to `http://localhost:5002/api-docs`.
+
+To authenticate requests to the dynamic API in Swagger, an API secret must first
+be set in the `.env` file in the `vclogin` folder with the key name
+`INCR_AUTH_API_SECRET`.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> To authenticate requests to the dynamic API in Swagger, first click on
+> the "Authorize" button in the top right corner of the Swagger UI. Then, enter
+> the API key in the "Value" field with the format `INCR_AUTH_API_SECRET <api_key>`
+> and click on the "Authorize" button.
+
 ## Running a Local Deployment
 
 A local deployment is a great way to test the bridge and to use it for
@@ -175,10 +242,13 @@ proper domain has to be set up.
    `/vclogin/.env` with key `PEX_DESCRIPTOR_OVERRIDE` if direct control over
    what wallets are asked for is desired (example for quick testing:
    `./__tests__/testdata/pex/descriptorEmailFromAltme.json`)
-6. at this point, it needs to be ensured that the container for the vclogin
+6. OPTIONAL: to be able to use or test incremental authorization, set an API key
+   in the `.env` file in the `vclogin` folder with the key
+   `INCR_AUTH_API_SECRET`.
+7. at this point, it needs to be ensured that the container for the vclogin
    service is freshly built with the new env file:
    `docker compose down && docker compose build`
-7. `$ docker compose up`
+8. `$ docker compose up`
 
 To validate the running bridge with a simple OIDC client:
 
@@ -246,6 +316,7 @@ PEX_DESCRIPTOR_OVERRIDE=./__tests__/testdata/pex/descriptorAnything.json
 HYDRA_ADMIN_URL=http://localhost:5001
 REDIS_HOST=localhost
 REDIS_PORT=6379
+API_KEY=<api-key>
 ```
 
 _Note: The PEX_DESCRIPTOR_OVERRIDE is optional and provides a way to override
@@ -261,7 +332,7 @@ refer to the end of the previous section.
 
 ## Running Tests
 
-This repository includes unit tests with `jest` and end-to-end tests with
+This repository includes unit tests with `vitest` and end-to-end tests with
 `playwright`. You may run them as follows:
 
 ```bash
@@ -278,7 +349,7 @@ credential, while forwarding all subject fields to the `id_token`:
 ```JSON
 [
   {
-    "credentialID": "credential1",
+    "credentialID": "1",
     "patterns": [
       {
         "issuer": "*",
@@ -323,7 +394,7 @@ use of this could look like this:
 ```json
 [
   {
-    "credentialId": "one",
+    "credentialId": "1",
     "patterns": [
       {
         "issuer": "did:web:app.altme.io:issuer",
@@ -384,9 +455,109 @@ logical operators that can combine multiple constraints:
 - _or_ Takes two constraint objects `a` and `b`.
 - _not_ Takes one constraint object `a`
 
+### Multiple Expected Credentials
+
+The bridge supports multiple expected credentials in a policy file. This allows
+for more complex scenarios where multiple credentials are needed to perform
+authorization. An example of such a policy file is:
+
+```json
+[
+  {
+    "credentialId": "cred_email",
+    "type": "EmailPass",
+    "patterns": [
+      {
+        "issuer": "did:web:app.altme.io:issuer",
+        "claims": [
+          {
+            "claimPath": "$.credentialSubject.email"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "credentialId": "cred_id",
+    "type": "VerifiableId",
+    "patterns": [
+      {
+        "issuer": "did:web:app.altme.io:issuer",
+        "claims": [
+          {
+            "claimPath": "$.credentialSubject.id"
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+<!-- prettier-ignore -->
+> [!IMPORTANT]
+> Each `credentialId` should be unique across all expected credentials in a policy,
+> and should only consist of alphanumeric characters and underscores. Similarly,
+> claim values should never be given colliding `newPath` values to avoid overwriting
+> token data.
+
+<!-- prettier-ignore -->
+> [!NOTE]
+> The expected credentials are matched to the submitted VCs solely on the basis of
+> required fields and constraints. If very similar VCs are required by a policy,
+> it should have constraints that make the matching unambiguous. Otherwise,
+> extracted claims may be switched up.
+
+When having multiple expected credentials, it is possible to define constraints
+for each as defined in [Constraints](#constraints). This is especially powerful
+since it is possible to refer to other expected credentials:
+
+```json
+[
+  {
+    "credentialId": "1",
+    "type": "EmailPass",
+    "patterns": [
+      {
+        "issuer": "did:web:app.altme.io:issuer",
+        "claims": [
+          {
+            "claimPath": "$.credentialSubject.email"
+          }
+        ],
+        "constraint": {
+          "op": "equalsDID",
+          "a": "$VP.proof.verificationMethod",
+          "b": "$1.credentialSubject.id"
+        }
+      }
+    ]
+  },
+  {
+    "credentialId": "2",
+    "type": "VerifiableId",
+    "patterns": [
+      {
+        "issuer": "did:web:app.altme.io:issuer",
+        "claims": [
+          {
+            "claimPath": "$.credentialSubject.id"
+          }
+        ],
+        "constraint": {
+          "op": "equals",
+          "a": "$2.credentialSubject.id",
+          "b": "$1.credentialSubject.id"
+        }
+      }
+    ]
+  }
+]
+```
+
 ## Token Introspection
 
-Look into the access token like this:
+Look into the Ory Hydra access token like this:
 
 ```bash
 $ docker run --rm -it \
@@ -420,6 +591,5 @@ service in `compose.yaml`:
 
 - [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
 - [OpenID for Verifiable Presentations](https://openid.net/specs/openid-4-verifiable-presentations-1_0-ID2.html)
-- [Self-Issued OpenID Provider v2](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html)
 - [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/)
 - [DIF Presentation Definition](https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition)

test_client.sh

@@ -1,31 +1,31 @@
 #!/bin/bash
 client=$(docker run --rm -it \
-    --network ory-hydra-net \
-    oryd/hydra:v2.2.0 \
-    create client --skip-tls-verify \
-    --name testclient \
-    --secret some-secret \
-    --grant-type authorization_code \
-    --response-type token,code,id_token \
-    --scope openid \
-    --redirect-uri http://localhost:9010/callback \
-    -e http://hydra:4445 \
-    --format json )
+  --network ory-hydra-net \
+  oryd/hydra:v2.2.0 \
+  create client --skip-tls-verify \
+  --name testclient \
+  --secret some-secret \
+  --grant-type authorization_code \
+  --response-type token,code,id_token \
+  --scope openid \
+  --redirect-uri "http://localhost:9010/callback" \
+  -e http://hydra:4445 \
+  --format json)
 
-echo $client
+echo "$client"
 
-client_id=$(echo $client | jq -r '.client_id')
+client_id=$(echo "$client" | jq -r ".client_id")
 
 docker run --rm -it \
-    --network ory-hydra-net \
-    -p 9010:9010 \
-    oryd/hydra:v2.2.0 \
-    perform authorization-code --skip-tls-verify \
-    --port 9010 \
-    --client-id $client_id \
-    --client-secret some-secret \
-    --redirect http://localhost:9010/callback \
-    --scope openid \
-    --auth-url http://localhost:5004/oauth2/auth \
-    --token-url http://hydra:4444/oauth2/token \
-    -e http://hydra:4444
+  --network ory-hydra-net \
+  -p 9010:9010 \
+  oryd/hydra:v2.2.0 \
+  perform authorization-code --skip-tls-verify \
+  --port 9010 \
+  --client-id "$client_id" \
+  --client-secret some-secret \
+  --redirect "http://localhost:9010/callback" \
+  --scope openid \
+  --auth-url http://localhost:5004/oauth2/auth \
+  --token-url http://hydra:4444/oauth2/token \
+  -e http://hydra:4444

vclogin/.env.test

@@ -1,2 +1,4 @@
 LOGIN_POLICY=./__tests__/testdata/policies/acceptAnything.json
 DID_KEY_JWK={"kty":"OKP","crv":"Ed25519","x":"cwa3dufHNLg8aQb2eEUqTyoM1cKQW3XnOkMkj_AAl5M","d":"me03qhLByT-NKrfXDeji-lpADSpVOKWoaMUzv5EyzKY"}
+EXTERNAL_URL=http://example.com
+INCR_AUTH_API_SECRET=verysecret

vclogin/__tests__/testdata/pex/descriptorVerifiableIDFromAltme.json

@@ -0,0 +1,18 @@
+[
+  {
+    "id": "verifiableId",
+    "name": "Input descriptor for login credential",
+    "purpose": "Please provide your VerifiableId credential to sign-in.",
+    "constraints": {
+      "fields": [
+        {
+          "path": ["$.credentialSubject.type"],
+          "filter": {
+            "type": "string",
+            "pattern": "VerifiableId"
+          }
+        }
+      ]
+    }
+  }
+]

vclogin/__tests__/testdata/policies/acceptAnything.json

@@ -1,6 +1,6 @@
 [
   {
-    "credentialId": "credential1",
+    "credentialId": "1",
     "patterns": [
       {
         "issuer": "*",

vclogin/__tests__/testdata/policies/acceptAnythingMisconfigured.json

@@ -0,0 +1,15 @@
+[
+  {
+    "credentialId": "some random string with spaces!",
+    "patterns": [
+      {
+        "issuer": "*",
+        "claims": [
+          {
+            "claimPath": "$.credentialSubject.id"
+          }
+        ]
+      }
+    ]
+  }
+]