Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

removal of state management hacks, readme update #815

Merged
merged 13 commits into from
Nov 7, 2024
Merged

removal of state management hacks, readme update #815

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1630ec2
fix various code links,
severinstampler Nov 4, 2024
2141a67
fix project links
severinstampler Nov 4, 2024
eb5e5a0
update readme with information about credential generation utility fu…
severinstampler Nov 4, 2024
c8aa9cf
update readme
severinstampler Nov 4, 2024
6064fc6
update readme
severinstampler Nov 4, 2024
f21ce8d
update readme
severinstampler Nov 4, 2024
2bbf55b
Merge branch 'main' into 98-refactor-openid4vc-library-2
severinstampler Nov 4, 2024
a82994f
finalize removal of session management hacks, some code cleanup tbd
severinstampler Nov 6, 2024
5ca5e81
remove abstract issuer class and redundant tests, fix and reactivate …
severinstampler Nov 6, 2024
67d1f73
code cleanup
severinstampler Nov 6, 2024
7812823
move issuance session data class to issuer-api service and extend par…
severinstampler Nov 6, 2024
c575d48
git ignore update
severinstampler Nov 7, 2024
081360f
Merge branch 'main' of github.com:walt-id/waltid-identity into 98-ref…
severinstampler Nov 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,3 +185,5 @@ iOSInjectionProject/
/waltid-openid4vc/root-ca-cert.pem
/waltid-openid4vc/root-ca-priv.pem
/waltid-openid4vc/root-ca-pub.pem
/waltid-services/waltid-issuer-api/k8s/cert-device-potential.pem
/waltid-services/waltid-issuer-api/k8s/ec_device_key.pem
1 change: 1 addition & 0 deletions docker-compose/docker-compose.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ services:
- .env
extra_hosts:
- "host.docker.internal:host-gateway"
- "wase:host-gateway"
volumes:
- ./wallet-api/config:/waltid-wallet-api/config
- ./wallet-api/walt.yaml:/waltid-wallet-api/walt.yaml
Expand Down
63 changes: 44 additions & 19 deletions waltid-libraries/protocols/waltid-openid4vc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,9 @@ business logic, for processing the OpenID4VC protocols.
The examples are based on **JVM** and make use of the following libraries:
- [**ktor**](https://ktor.io/) for the HTTP server endpoints and client-side request
handling
- [**waltid-crypto**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-crypto) for cryptographic operations
- [**waltid-crypto**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/crypto/waltid-crypto) for cryptographic operations
- [**waltid-did**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-did) for DID-related operations
- [**waltid-verifiable-credentials**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-verifiable-credentials) for credential and presentation handling
- [**waltid-verifiable-credentials**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-verifiable-credentials) for credential and presentation handling

### Issuer

Expand All @@ -84,7 +84,7 @@ For the full demo issuer implementation, refer to `/src/jvmTest/kotlin/id/walt/o

For the OpenID4VCI issuance protocol, implement the following endpoints:

**Well-defined endpoints:**
##### Well-defined endpoints:

These endpoints are well-defined, and need to be available under this exact path, relative to your issuer base URL:

Expand All @@ -95,9 +95,11 @@ These endpoints are well-defined, and need to be available under this exact path
Returns the
issuer [provider metadata](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L147-L152
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L167-L172

**Other required endpoints**
See also [here](#configuration-of-issuance-provider) for details about **creating the provider metadata**, required for these endpoints.

#### Other required endpoints

These endpoints can have any path, according to your requirements or preferences, but need to be referenced in the provider metadata,
returned by the well-defined configuration endpoints listed above.
Expand All @@ -108,7 +110,7 @@ returned by the well-defined configuration endpoints listed above.
Endpoint to receive [pushed authorization requests](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-pushed-authorization-reques), referenced in the provider metadata as `pushed_authorization_request_endpoint`,
see [here](https://www.rfc-editor.org/rfc/rfc9126.html#name-authorization-server-metada).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L153-L161
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L173-L181

* `GET /authorize`

Expand All @@ -117,58 +119,81 @@ in provider metadata as `authorization_endpoint`, see [here](https://www.rfc-edi

Not required for the pre-authorized issuance flow.

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L162-L206
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L182-L226

* `POST /token`

[Token endpoint](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-token-endpoint), referenced in provider
metadata as `token_endpoint`, see [here](https://www.rfc-editor.org/rfc/rfc8414.html#section-2).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L207-L216
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L227-L236

* `POST /credential`

[Credential endpoint](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-endpoint) to fetch the issued credential, after authorization flow is completed. Referenced in provider metadata as `credential_endpoint`, as
defined [here](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-p).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L217-L229
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L237-L249

See also [here](#crypto-operations-and-credential-issuance) for details about **generating credentials** using the library.

* `POST /credential_deferred`

[Deferred credential endpoint](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-deferred-credential-endpoin),
to fetch issued credential if issuance is deferred. Referenced in provider metadata as `deferred_credential_endpoint` (missing in spec).
to fetch issued credential if issuance is deferred. Referenced in provider metadata as `deferred_credential_endpoint`, as
defined [here](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-p).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L230-L245
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L250-L265

* `POST /batch_credential`

[Batch credential endpoint](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-batch-credential-endpoint) to
fetch multiple issued credentials. Referenced in provider metadata as `batch_credential_endpoint`, as
defined [here](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-credential-issuer-metadata-p).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L246-L258
**Note:** The batch credential endpoint has been removed from the latest OpenID4VCI specification. Support for the new specification (credentials array in `/credential` response object) is yet to be implemented.

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L266-L278

#### Business logic

For the business logic, implement the abstract issuance provider
in `src/commonMain/kotlin/id/walt/oid4vc/providers/OpenIDCredentialIssuer.kt`, providing session and cache management, as well, as
cryptographic operations for issuing credentials.

* **Configuration of issuance provider**
##### Configuration of issuance provider

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L49-L66

**Provider metadata**

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L54-L71
To **create the provider metadata** object for the well-defined [metadata endpoints](#well-defined-endpoints), you may make use of the helper function in the OpenID4VCI utility object:
[OpenID4VCI::createDefaultProviderMetadata](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/commonMain/kotlin/id/walt/oid4vc/OpenID4VCI.kt#L307),
which creates the metadata based on the issuer base URL, describing the standard API endpoints, response types and signing algorithms.

* **Simple session management example**
**Note**, that this utility function does NOT add supported credential types, as it is up to the implementer, which credential types they can support.
See [here](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/commonMain/kotlin/id/walt/oid4vc/providers/OpenIDCredentialIssuer.kt#L42) for an example how to load the list of supported credentials from a configuration.


##### Simple session management example

Here we implement a simplistic in-memory session management:

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L73-L78
https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L68-L81

##### Crypto operations and credential issuance

Token signing and credential issuance based on [**waltid-crypto**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/crypto/waltid-crypto), [**waltid-did**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-did) and [**waltid-verifiable-credentials**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/credentials/waltid-verifiable-credentials).

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L83-L160

* **Crypto operations and credential issuance**
**Credential generation**

Token signing and credential issuance based on [**waltid-crypto**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-crypto), [**waltid-did**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-did) and [**waltid-verifiable-credentials**](https://github.com/walt-id/waltid-identity/tree/main/waltid-libraries/waltid-verifiable-credentials).
For generating W3C or SD-Jwt-VC credentials, as required for the `/credential` endpoint, the library provides two helper functions in the OpenID4VCI utility object:
* [OpenID4VCI.generateSdJwtVC](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/commonMain/kotlin/id/walt/oid4vc/OpenID4VCI.kt#L386)
* [OpenID4VCI.generateW3CJwtVC](https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/protocols/waltid-openid4vc/src/commonMain/kotlin/id/walt/oid4vc/OpenID4VCI.kt#L439)

https://github.com/walt-id/waltid-identity/blob/main/waltid-libraries/waltid-openid4vc/src/jvmTest/kotlin/id/walt/oid4vc/CITestProvider.kt#L80-L139
For an example how to use the utility functions, see [here](https://github.com/walt-id/waltid-identity/blob/main/waltid-services/waltid-issuer-api/src/main/kotlin/id/walt/issuer/issuance/CIProvider.kt#L266-L271).

### Verifier

Expand Down
Loading
Loading