Skip to content

Commit

Permalink
up issuer & verifier
Browse files Browse the repository at this point in the history
  • Loading branch information
@BastienLopez
BastienLopez committed Oct 22, 2024
1 parent b15e99a commit 0a661e1
Show file tree
Hide file tree
Showing 2 changed files with 150 additions and 80 deletions.
140 changes: 92 additions & 48 deletions docs/wallet/issuer_configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Issuer configuration

Updated the 18th of October 2024.
Updated the 21st of October 2024.

The wallets support most of the VC options of the OIDC4VCI standard for issuer configuration.

Expand All @@ -12,58 +12,63 @@ OIDC4VCI has evolved rapidly between 2022 (Draft 10/11) and 2024 (Draft >= 13).

Specifications of the different Drafts are available here:

* [Draft 10](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-10.html) supported
* [Draft 11](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-11.html) supported
* [Draft 12](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-12.html) not supported
* [Draft 13](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-13.html) supported
* [Draft 14](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-14.html) soon supported
- [Draft 10](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-10.html) supported
- [Draft 11](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-11.html) supported
- [Draft 12](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-12.html) not supported
- [Draft 13](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-13.html) supported
- [Draft 14](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0-14.html) soon supported

## OIDC4VCI flow and features

Wallets support:

* credential offer by value and by reference,
* pre authorized code (by default), authorized code flow, push authorization request, PKCE,
* [Attestation based client authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/),
* `tx_code` with`input_mode` `text`or`numeric`, `lenght`and`description`,
* `authorization_details` and `scope`. Tune with OIDCVC settings or wallet provider backend to use `scope`.,
* authorization server as a standalone server associated to one VC type,
* dynamic credential request,
* client secret post, client secret basic and public client authentication,
* bearer credential (no crypto binding),
* proof types as `jwt` or `ldp_vc`,
* proof of possession header with `kid` or `jwk`,
* deferred endpoint,
* key identifiers as jwk thumbprint of DID,
* keys as EdDSA, P-256, seckp256k1.
- credential offer by value and by reference,
- pre authorized code (by default), authorized code flow, push authorization request, PKCE,
- [Attestation based client authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/),
- `tx_code` with`input_mode` `text`or`numeric`, `lenght`and`description`,
- `authorization_details` and `scope`. Tune with OIDCVC settings or wallet provider backend to use `scope`.,
- authorization server as a standalone server associated to one VC type,
- dynamic credential request,
- client secret post, client secret basic and public client authentication,
- bearer credential (no crypto binding),
- proof types as `jwt` or `ldp_vc`,
- proof of possession header with `kid` or `jwk`,
- deferred endpoint,
- key identifiers as jwk thumbprint of DID,
- keys as EdDSA, P-256, seckp256k1.

Wallets do not support:

* notification endpoint,
* batch endpoint of Draft 13,
* DPoP for code and token,
* encrypted credentials.
- notification endpoint,
- batch endpoint of Draft 13,
- DPoP for code and token,
- encrypted credentials.

## Invocation schemes for issuance

Wallet support different invocation schemes:

* openid-credential-offer://,
* haip://,
* https://app.altme.io/app/download/oidc4vc,
* https://app.talao.co/app/download/oidc4vc
- openid-credential-offer://,
- haip://,
- https://app.altme.io/app/download/oidc4vc,
- https://app.talao.co/app/download/oidc4vc

Those schemes can be displayed as QR code for wallet app scanner, smartphone camera or as a deeplink/universal link (a button in a html page for the smartphone browser).
Those schemes can be displayed as QR code for wallet app scanner, smartphone camera or as a deeplink / universal link (a button in a html page for the smartphone browser).

# Support of Universal Links and App Links

For security reasons Talao wallets use Universal Links and App Links to redirect to wallet authorization endpoints and callback endpoints. However those links are not supported by default by all browsers. We suggest to use **Safari for IOS** phones and **Chrome for Android**. You may need to setup browser options manually to allow Universal links or App Links with Firefox, Brave, Samsung explorer or even Chrome on IOS.

## Dynamic Credential Request

Dynamic Credential Requiest is an option to operate a VP presentation for user authentication inside an authorization code flow. In practice this approach provides a better UX than a VP presentation followed by a pre authorization code flow.
Dynamic Credential Request is an option to operate a VP presentation for user authentication inside an authorization code flow.

In order to manage that combination wallet must provide its own authorization code flow to the issuer. Right now, our wallets support the "EBSI V3.x implementation" way with a `client_metadata` argument added to the authorization request and push authorization request.
The differences between this process and the use of a VP authentication step (OIDC4VP) followed by the issuance of a VC by pre authorized code flow (OIDC4VCI) are multiple:

- the VP(s) requested from the user depend on the VC requested by the user,
- the integration and the UX are simpler.

In order to manage that combination wallet must provide its own authorization endpoint to the issuer. Right now, our wallets support the "EBSI V3.x implementation" way with a `client_metadata` argument added to the authorization request and push authorization request.

Example of client_metadata:

Expand All @@ -84,19 +89,19 @@ Example of client_metadata:
```

Here is a script of the issuance of a VC in using anothere VC as a mean of authentication:
Here is a script of the issuance of a VC in using another VC as a mean of authentication:

1. Wallet makes an authorization request to the AS of the issuer through a QRcode or a deeplink. The `client_metadata` attribute (or wallet_issuer attribute) is added to the request aside the standard `redirect_uri` endpoint of the wallet. For this step the wallet opens a browser session and redirects the user agent to the AS authorization endpoint.
2. To process the authentication step, the issuer fetches the wallet authorization endpoint from the `client_metadata` and prepares a VP request with its own `reponse_uri` endpoint like a verifier. The VP request is sent as a redirect to the wallet authorization endpoint. For implementtaion issuer can add the `state` attribute to the VP request to link the request to the original wallet request.
2. To process the authentication step, the issuer fetches the wallet authorization endpoint from the `client_metadata` and prepares a VP request with its own `reponse_uri` endpoint like a verifier. The VP request is sent as a redirect to the wallet authorization endpoint. For implementation issuer can add the `state` attribute to the VP request to link the request to the original wallet request.
3. Wallet selects the VP requested and transfers is through a POST to the `response_uri` endpoint provided in the VP request. The state is added to the `vp_token` and `presentation_submission`.
4. Issuer acting as a verifier validates the VP data needed to prepare the VC and redirects the user agent to the `redirect_uri` endpoint of the wallet with the `code`. For implementation the `state` can be associated to the `code`.
5. Wallet requests an `access_token` in exchange of the `code`. For implementation the `code` can be associated to the `access_token`.
6. Wallet requests the credential with the access token.

In case of the use of the `wallet_issuer` attribute, issuer must discover the wallet authorization endpoint through the standard `/.well-known/openid-configuration` endpoint:

* Talao: [https://app.talao.co/wallet-issuer/.well-known/openid-configuration](https://app.talao.co/wallet-issuer/.well-known/openid-configuration)
* Altme: [https://app.altme.io/wallet-issuer/.well-known/openid-configuration](https://app.altme.io/wallet-issuer/.well-known/openid-configuration)
- Talao: [https://app.talao.co/wallet-issuer/.well-known/openid-configuration](https://app.talao.co/wallet-issuer/.well-known/openid-configuration)
- Altme: [https://app.altme.io/wallet-issuer/.well-known/openid-configuration](https://app.altme.io/wallet-issuer/.well-known/openid-configuration)

Learn more about [Dynamic Credential Request](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html#name-dynamic-credential-request).

Expand Down Expand Up @@ -128,17 +133,17 @@ Wallet support all the attributes of the display.

The `uri` can be either a link or a data uri scheme. `text_color` and `background_color` are fallbacks options if links are not provided.

`name` is used as the VC name if there is no background image.
`name` is used as the VC name if there is no background image.

If `display` is not provided wallets use a fallback blue card with white text color.

### Attributes of a claim

Wallets show only but all claims that are in the issuer metadata, rules are:

* if there is a` display` attribute in the claim, wallet displays the label in bold with the claim value on the same line. Otherwise wallet displays the claim value alone,
* if the claim is a json object (nested claims) without `display` -> it goes to the line and indent,
* if the claim is a json object with a `display` -> it displays the label in bold and goes to the line and indent.
- if there is a` display` attribute in the claim, wallet displays the label in bold with the claim value on the same line. Otherwise wallet displays the claim value alone,
- if the claim is a json object (nested claims) without `display` -> it goes to the line and indent,
- if the claim is a json object with a `display` -> it displays the label in bold and goes to the line and indent.

With this issuer metadata:

Expand Down Expand Up @@ -203,17 +208,17 @@ Wallets support all attributes of the display :
"name": "First Name",
"locale": "en-US"
},
```

`value_type` supported are:

* `string`,
* `integer`,
* `bool`,
* `email`,
* `uri`,
* `image/jpeg` , `image/png`
- `string`,
- `integer`,
- `bool`,
- `email`,
- `uri`,
- `image/jpeg` , `image/png`

`email` and `uri` are active as you can launch the browser or open the smartphone email manager with a clic.

Expand Down Expand Up @@ -274,7 +279,46 @@ Wallet does not support the [type metadata](https://www.ietf.org/archive/id/draf

Wallets support the following specifications depending on the VC format:

* ldp_vc, jwt_vc, jwt_vc_json, jwt_vc_json-l : [Bitstring Status List V1.0](https://www.w3.org/TR/vc-bitstring-status-list/)
* sd-jwt-vc : [Token Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)
- ldp_vc, jwt_vc, jwt_vc_json, jwt_vc_json-l : [Bitstring Status List V1.0](https://www.w3.org/TR/vc-bitstring-status-list/)
- sd-jwt-vc : [Token Status List](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)

When the VC is received from the issuer or displayed, the wallet verifies the signature of the VC, the signature of the status list and the status of the VC. If any of these checked fails teh wallet display a red card status. These verification steps can by passed with an option in the wallet provider backed through a security low profile.

## Waltid integration

All `issuer.{..}`, `expirationDate`, `issuanceDate`and `credentialSubject.id` claims must be removed from the credential data as they are already provided in the json_jwt_vc as `iss`, `sub`, `iat`. Here is a correct configuration needed to make the waltid example running :

```
{
"issuerKey": {
"type": "jwk",
"jwk": {
"kty": "EC",
"d": "uTIT47GfSlRa0Da4CsyoIZpjjwQLFxmL2qmBuzZpEy0",
"crv": "P-256",
"kid": "FsHUZY4_tDJDvxdp5B6moS1kwpP7PBekw4KfK7m0LCU",
"x": "keR9l4u1SaZKMZ7wHvj_3z44vP0sa3nlzrnc8UjpQV0",
"y": "pmcaedg5dtc2R6ZPZfWCBY56_M_5fUZgsz4LWD0mG8U"
}
},
"credentialConfigurationId": "UniversityDegree_jwt_vc_json",
"credentialData":{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"credentialSubject": {
"degree":{
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"authenticationMethod": "PRE_AUTHORIZED",
"issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2Iiwia2lkIjoiRnNIVVpZNF90REpEdnhkcDVCNm1vUzFrd3BQN1BCZWt3NEtmSzdtMExDVSIsIngiOiJrZVI5bDR1MVNhWktNWjd3SHZqXzN6NDR2UDBzYTNubHpybmM4VWpwUVYwIiwieSI6InBtY2FlZGc1ZHRjMlI2WlBaZldDQlk1Nl9NXzVmVVpnc3o0TFdEMG1HOFUifQ"
}
```
90 changes: 58 additions & 32 deletions docs/wallet/verifier-configuration.md
View file
Original file line number Diff line number Diff line change
@@ -1,46 +1,46 @@
# Verifier configuration

Updated the 18th of October 2024.
Updated the 21st of October 2024.

## OIDC4VP Specifications Drafts

Wallets support both OIDC4VP and SIOPV2 specifications.

* [OIDC4VP Draft 18](https://openid.net/specs/openid-4-verifiable-presentations-1_0-18.html) supported
* [OIDC4VP Draft 20](https://openid.net/specs/openid-4-verifiable-presentations-1_0-20.html) supported
* [OIDC4VP Draft 21](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) coming soon
* [SIOPV2 Draft 13](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html) supported
- [OIDC4VP Draft 18](https://openid.net/specs/openid-4-verifiable-presentations-1_0-18.html) supported
- [OIDC4VP Draft 20](https://openid.net/specs/openid-4-verifiable-presentations-1_0-20.html) supported
- [OIDC4VP Draft 21](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) coming soon
- [SIOPV2 Draft 13](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html) supported

## OIDC4VP and SIOPV2 features

Wallets support:

* client_id_scheme,
* request in value and request_uri,
* presentation_definition and presentation_definition_uri,
* direct_post and direct_post.jwt,
* id_token, vp_token, id_token vp_token response_type,
* client_metadata
* signed response JARM
- client_id_scheme,
- request in value and request_uri,
- presentation_definition and presentation_definition_uri,
- direct_post and direct_post.jwt,
- id_token, vp_token, id_token vp_token response_type,
- client_metadata
- signed response JARM

Wallets do not support:

* request uri Method Post,
* encrypted response,
* openid federation 1.0.
- request uri Method Post,
- encrypted response,
- openid federation 1.0.

## Invocation schemes for verification

Wallets support different invocation schemes:

* openid://,
* openid-vc://,
* haip://,
* siopv2://
* https://app.altme.io/app/download/authorize,
* https://app.talao.co/app/download/authorize
- openid://,
- openid-vc://,
- haip://,
- siopv2://
- https://app.altme.io/app/download/authorize,
- https://app.talao.co/app/download/authorize

Those schemes can be displayed as QR code for wallet app scanner, smartphone camera or as a deeplink/universal link (a button in a html page for the smartphone browser).
Those schemes can be displayed as QR code for wallet app scanner, smartphone camera or as a deeplink / universal link (a button in a html page for the smartphone browser).

# Support of Universal Links and App Links

Expand All @@ -50,17 +50,17 @@ For security reasons Talao wallets use Universal Links and App Links to redirect

Wallet supports the following [client_id_scheme](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-verifier-metadata-managemen) of verifiers:

* did : wallets resolve the DID Document to validate the request object signature, All standards DID methods are supported through an external instance of the DID resolver managed by Talao.
* x509_san_dns : wallets get the public key from the last X509 certificate to validate the request object signature. Wallets use the dNSName Subject Alternative Name (SAN) to request consent from user to present the VC.
* verifier_attestation: wallets validate the signature of the request object with the publick key in the cnf of the verifier attestation,
* redirect_uri: there is no validation of the request as the request object must not be signed.
- did : wallets resolve the DID Document to validate the request object signature, All standards DID methods are supported through an external instance of the DID resolver managed by Talao.
- x509_san_dns : wallets get the public key from the last X509 certificate to validate the request object signature. Wallets use the dNSName Subject Alternative Name (SAN) to request consent from user to present the VC.
- verifier_attestation: wallets validate the signature of the request object with the public key in the cnf of the verifier attestation,
- redirect_uri: there is no validation of the request as the request object must not be signed.

## Wallet metadata

Wallet metadata are available "out of band".

* Talao: [https://app.talao.co/wallet-issuer/.well-known/openid-configuration](https://app.talao.co/wallet-issuer/.well-known/openid-configuration)
* Altme: [https://app.altme.io/wallet-issuer/.well-known/openid-configuration](https://app.altme.io/wallet-issuer/.well-known/openid-configuration)
- Talao: [https://app.talao.co/wallet-issuer/.well-known/openid-configuration](https://app.talao.co/wallet-issuer/.well-known/openid-configuration)
- Altme: [https://app.altme.io/wallet-issuer/.well-known/openid-configuration](https://app.altme.io/wallet-issuer/.well-known/openid-configuration)

## Submission presentation

Expand All @@ -72,14 +72,40 @@ The presentation is done in two steps which are the choice of the credential the

The credential contains 3 types of data:

* The standards jwt attributes as iss, iat, vct,...that are systematically presented and not displayed to the user during the process,
* The “disclosable” claims that are displayed and selectable (except for `limit_disclosure = required`),
* Other claims defined in the jwt are displayed to the user and not selectable
- The standards jwt attributes as iss, iat, vct,...that are systematically presented and not displayed to the user during the process,
- The “disclosable” claims that are displayed and selectable (except for `limit_disclosure = required`),
- Other claims defined in the jwt are displayed to the user and not selectable

For data minimization purpose, in case of a presentation_definition including the `limit_disclosure = required` option, user can only accept or refuse to present the verifiable credential. The data set of the VC is limited to what is strictly required by the verifier.

## Submission Requirement Features

Learn more about tghis topic [here](https://identity.foundation/presentation-exchange/#submission-requirement-feature).
Learn more about this topic [here](https://identity.foundation/presentation-exchange/#submission-requirement-feature).

To be done

## Waltid integration

Integration of the example provided by waltid documentation must be updated by:

- QR code returned by Waltid API must be corrected as client_id must be equal to response_uri when `client_id_scheme = redirect_uri`. See [https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-verifier-metadata-managemen](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-verifier-metadata-managemen)
- `path` must be providd from upper object. Replace `$.type` by `$.vc.type`
- `type` is an array so filter must be set accordingly

```
constraints': {
'fields': [
{
'path': [
'$.vc.type'
],
'filter': {
'type': 'array',
'contains': {
'const': 'UniversityDegreeCredential'
}
}
}
]
}
```

0 comments on commit 0a661e1

Please sign in to comment.