From fd91c8a6f5d571b626d36e24a5e5f1cb5421e1c2 Mon Sep 17 00:00:00 2001 From: Nander Stabel Date: Fri, 30 Aug 2024 18:01:54 +0200 Subject: [PATCH] docs: update JIT Credential issuance documentation --- agent_application/docker/README.md | 27 ------------- agent_event_publisher_http/README.md | 57 ++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 27 deletions(-) diff --git a/agent_application/docker/README.md b/agent_application/docker/README.md index e25559f2..6f493e0a 100644 --- a/agent_application/docker/README.md +++ b/agent_application/docker/README.md @@ -49,30 +49,3 @@ variables: UNICORE__SECRET_MANAGER__ISSUER_DID: UNICORE__SECRET_MANAGER__ISSUER_FRAGMENT: ``` - -## Leveraging Just-in-Time Data Request Events - -UniCore facilitates dynamic integration with external systems through just-in-time data request events, dispatched seamlessly via an HTTP Event Publisher. This enables real-time data retrieval and on-demand generation, enhancing flexibility and efficiency in your SSI ecosystem. - -### Example Scenarios - -**Custom Credential Signing** - -UniCore facilitates the utilization of just-in-time data request events for customized credential signing workflows. This approach enables users to manage the signing process independently, offering greater control over credential issuance. When UniCore verifies a Credential Request from a Wallet, it triggers the `CredentialRequestVerified` event. By utilizing the HTTP Event Publisher, this event, containing essential identifiers like `offer_id` and `subject_id`, can be dispatched to external systems. Subsequently, external systems leverage these identifiers to generate and sign credentials, which are then submitted to UniCore's `/v0/credentials` endpoint. - -To integrate just-in-time data request events into your workflow, adhere to the following steps: - -1. Configure the HTTP Event Publisher to listen for the `CredentialRequestVerified` event. Refer to the [HTTP Event Publisher documentation](../../agent_event_publisher_http/README.md) for detailed configuration instructions: - - ```yaml - target_url: &target_url "https://my-domain.example.org/ssi-event-subscriber" - - offer: - { target_url: *target_url, target_events: [CredentialRequestVerified] } - ``` - -2. Upon initiation of the OpenID4VCI flow by a Wallet, the CredentialRequestVerified event is triggered, containing relevant identifiers. -3. The HTTP Event Publisher dispatches the event to the external system. Leveraging the provided identifiers, the external system generates and signs the credential, then submits it to UniCore's `/v0/credentials` endpoint. Refer to the [API specification](../../agent_api_rest/README.md)) for additional details on endpoint usage. - -By default, UniCore will wait up to 1000 ms for the signed credential to arrive. This parameter can be changed by -setting the `AGENT_API_REST_EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS` environment variable. diff --git a/agent_event_publisher_http/README.md b/agent_event_publisher_http/README.md index 2fa08dbf..52465e79 100644 --- a/agent_event_publisher_http/README.md +++ b/agent_event_publisher_http/README.md @@ -77,3 +77,60 @@ AuthorizationRequestObjectSigned SIOPv2AuthorizationResponseVerified OID4VPAuthorizationResponseVerified ``` + +## Leveraging Just-in-Time Data Request Events + +UniCore facilitates dynamic integration with external systems through just-in-time data request events, dispatched seamlessly via the HTTP Event Publisher. This enables real-time data retrieval and on-demand generation, enhancing flexibility and efficiency in your SSI ecosystem. + +### Example Scenarios + +**Custom Credential Signing** + +UniCore facilitates the utilization of just-in-time data request events for customized credential signing workflows. This approach enables users to manage the signing process independently, offering greater control over credential issuance. When UniCore verifies a Credential Request from a Wallet, it triggers the `CredentialRequestVerified` event. By utilizing the HTTP Event Publisher, this event, containing essential identifiers like `offer_id` and `subject_id`, can be dispatched to external systems. Subsequently, external systems leverage these identifiers to generate and sign credentials, which are then submitted to UniCore's `/v0/credentials` endpoint. + +To integrate just-in-time data request events into your workflow, adhere to the following steps: + +1. Configure the HTTP Event Publisher to listen for the `CredentialRequestVerified` event. The following configuration + can be added to your `config.yaml` file: + ```yaml + event_publishers: + http: + enabled: true + target_url: "https://your-server.org/event-subscriber" + events: + offer: [CredentialRequestVerified] + ``` +2. The above configuration makes sure that whenever a Wallet sends a Credential Request, the HTTP Event Publisher will + dispatch the `CredentialRequestVerified` event to the specified URL once it successfully verified the Credential + Request, e.g: + ```json + POST /event-subscriber HTTP/1.1 + Host: https://your-server.org + Content-Type: application/json + Content-Length: 328 + { + "CredentialRequestVerified": { + "offer_id": "001", + "subject_id": "did:jwk:eyJhbGciOiJFUzI1NiIsImNydiI6IlAtMjU2Iiwia2lkIjoieERDQVBRbHRVa2JZMnByTkdpT0ItNWJ2T0pnZnQ0NVJqYjM2RWNjSWNGdyIsImt0eSI6IkVDIiwieCI6Im02b3EySFF6NmluSk8xbzg1VUM5VVEyamxJRFJld0ROVS0ybUktVThKN1UiLCJ5Ijoia0NwbTcwbXpCT3Y0OWFPdHdmRUdxVW1fSkllWXlZeWdWSXpKaFpXY1ZnTSJ9" + } + } + ``` +3. Now your system can apply its own logic and create and sign a Credential based on the data received from the Event. + The signed Credential can then be submitted to UniCore's `/v0/credentials` endpoint, e.g: + ```json + POST /v0/credentials HTTP/1.1 + Host: https://unicore-server.org + Content-Type: application/json + Content-Length: 328 + { + "offerId": "001", + "credential": "", + "isSigned": true, + "credentialConfigurationId": "" + } + ``` +4. Once UniCore receives the signed Credential, it will finalize the issuance process by embedding the signed Credential + into the Credential Response to the Wallet. + +By default, UniCore will wait up to 1000 ms for the signed credential to arrive. This parameter can be changed by +setting the `AGENT_API_REST_EXTERNAL_SERVER_RESPONSE_TIMEOUT_MS` environment variable.