Since mid-Jan Q1/23 the Wallet Kit extended it's multi-issuer configurability to a complete multi-tenancy supported system.
All API endpoints for issuer configuration have the option for setting a tenantId.
The default tenantId is "default".
POST /issuer-api/{tenantId}/config/did/create
POST this JSON body to the specified URL:
Method being one of: [ key, web, ebsi, iota, cheqd, jwk ]. Only the method is required. All "didWeb" prefixed options are only needed for creating a did:web.
Response: did:key:z6MknaJ7YLdkCq1QV2tcwVSY5uVfUKGfBdigo7g4PyipTnCc
GET /issuer-api/{tenantId}/config/getConfiguration
POST /issuer-api/{tenantId}/config/setConfiguration
The configuration was amended to include the "issuerDid" attribute with the DID from "Creating a DID for a tenant".
Issuance is very simple, in fact, you only need to call a single HTTP POST endpoint:
POST /issuer-api/{tenantId}/credentials/issuance/request
Wallet When issuing a credential, you will have to pre-select what type of wallet shall be used.
There are three types of wallets:
Mobile wallets:
Cross device flow: User uses another device (desktop pc, laptop) than where their wallet is installed (smartphone).
In this case, you will use the virtual wallet "x-device", which creates an "openid-initiate-issuance://..." URL.
Web wallets:
Same device flow: User uses the same device that their wallet is installed on.
In this case, you will have to additionally ask what web wallet the user is using (if you aren't forcing them to use your or an specific web wallet).
e.g. "walt.id", which creates an "https://wallet.walt.id/..." URL.
App wallets
Theoretically same device flow, but also uses the virtual wallet "x-device" for creating an "openid-initiate-issuance://..." URL.
In the default configuration you can use the wallet "walt.id" (https://wallet.walt.id), or the virtual wallet "x-device" for the cross device flow ("openid-initiate-issuance://...").
The selected walletId is the id configured in the mappings seen in wallet_kit-configuration.m
Answers with a redirect (header "Location") to the issuance URL, e.g. http://localhost:3000/api/siop/initiateIssuance/?issuer=http%3A%2F%2Flocalhost%3A8080%2Fissuer-api%2Fdefault%2Foidc%2F&credential_type=VerifiableId&pre-authorized_code=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxYTYyMzJiMy1hZDE0LTQ3YTYtYjMxNi00NzUzZjJhM2Q2NWYiLCJwcmUtYXV0aG9yaXplZCI6dHJ1ZX0.TGYpvRwE9Qc7-BSMLAA-u3Kweyf8ks2w3ulBpSyZQiI&user_pin_required=false
Verifiable Credential templates/types setup
You can import a DID document using:
The value "default" of --as-issuer
refers to the tenantId.
By specifying vc templates --help
you can also view other VC template commands (besides import you can list, export and remove)
GET /issuer-api/{tenantId}/config/templates
By default, only the template ID will be shown, but the full template will not be loaded.
GET /issuer-api/{tenantId}/config/templates/{templateId}
Response for "VerifiableId" credential:
POST /issuer-api/{tenantId}/config/templates/{templateId}
For this demo, we will add the example w3c-ccg credential CrudeProductCredential:
/issuer-api/{tenantId}/config/templates/{templateId}
There are 3 ways to integrate the verification flows into your application:
Same-device (web-based) flow
Cross-device flow (with QR code)
Via webhooks (callback)
In all cases, first make sure you have your tenant configured with all the verification policies, etc. that fit your requirements.
Then start the presentation flow, using the methods described below.
GET /verifier-api/<tenantId>/present?walletId=walt.id&vcType=VerifiableId
Supported parameters:
Answers with a redirect (header "Location") to the verification URL (at your specified wallet). e.g.
(a local wallet at localhost was configured in this example case)
By telling the wallet what vcType is required, it will usually filter the list of credentials in the user UI to only display relevant credentials of the specified type.
In the same-device flow the browser gets navigated to this API URL, with the given parameters
The walletkit redirects to the wallet and on completion, the walletkit redirects the browser back to the application.
The web redirection URL is configured in the tenant configuration parameter verifierUiUrl
, or can be overridden using the verifierUiUrl
URL parameter.
The verifierUiUrl
is called with the sub-path /success and an access_token
parameter, which can be used to retrieve the verification result data.
Example flow
Navigate the browser to:
https://wallet.walt-test.cloud/verifier-api/default/present?walletId=walt.id&vcType=VerifiableId&vcType=Europass&verifierUiUrl=https://myservice.example.com/callback/
The browser will be redirected to the wallet. The user will be presented the presentation request and asked to confirm it.
Eventually the browser will be redirected back to the application like this:
https://myservice.example.com/callback/success/?access_token=abc123
Note the subpath /success/
being added to the verifierUiUrl
!
Use the access token to retrieve the verification result from the walletkit like described in Verification result.
GET /verifier-api/{tenantId}/presentXDevice
Supported parameters:
For starting a cross-device presentation flow, call this API with the required parameters to create a presentation request.
As a response, you get an object containing a requestId
and a url
.
Your application should now render the url
from the response object as a QR code, or deep-link.
The requestId
from the response object can be used to query the verification request status, using the API endpoint described here.
The wallet can scan the rendered QR code and parse the presentation request. Eventually it will post the presentation response to the walletkit backend, which will update the request status.
When the request is fulfilled, the response of the verification request status API, will contain a URI with the access_token
parameter, which can be used to fetch the presentation result using the Verification result API.
GET /verifier-api/{tenantId}/verify/isVerified
Supported parameters:
The application calls this API, after starting a cross-device presentation flow, using the request ID received in the response object for the state
parameter of this API.
This API will return a status 404 Not found
, while it is waiting for the cross-device request to be fulfilled.
When the request is fulfilled, it will return a status 200 OK
with the redirection URL in the response body.
From the redirection URL, the application can parse the access_token
parameter, to fetch the verification result.
GET /verifier-api/<tenantID>/auth?access_token=abc123
Parameters
The response of this request will be a verification result, like described in the section Example verification result section.
As seen in the first example, you can optionally set a callback:
https://wallet.walt-test.cloud/verifier-api/default/present?walletId=walt.id&vcType=VerifiableId&verificationCallbackUrl=http://wallet.local:5555/callback/5dd9f971-9cd2-4c41-a40f-5340ac6d1fd3
(Note &verificationCallbackUrl=
)
When setting a callback, the Wallet Kit will then call this callback as webhook when the user shares a credential (in the walt.id demo wallet: actually clicks "Share credentials").
Before answering the user, the Wallet Kit will send out an HTTP Post request using the parameters described below.
When the callback answers HTTP statuses
Statuses:
OK (200),
NoContent (201),
or Accepted (202)
the Wallet Kit will mark the callback as accepted and continue its normal operation.
When the callback answers HTTP statuses
Statuses:
MovedPermanently (301),
Found (302),
TemporaryRedirect (307),
or PermanentRedirect (308)
the Wallet Kit will abort its operation and redirect the user (using the Location
header) to the Location
specified by the callback.
This is useful for redirecting to pages based on what credentials the user shares or change depending on the data of the credentials.
When the callback answers HTTP statuses
Statuses:
Unauthorized (401),
or Forbidden (403)
the Wallet Kit will invalidate the status and set overallValid to false, even if the selected VerificationPolicy
s would result in an overallValid = true
.
When you set up your webhook to listen for such a Wallet Kit callback, you have a variety of data to work with:
state: (UUID) ID of the verification session
subject: (DID) DID of the user that created the shared presentation
auth_token: (JWT[Subject]) Signed representation of subject = DID
vps: (List[VPVerificationResult])
VPVerificationResult:
vp: (JWT) Signed representation of the Verifiable Presentation
Including DIDs, issuance dates (attribute iat
, nbf
), etc...
and obviously the actual Verifiable Credential (in attribute vc
)
vcs: (List[JWT])
Signed Verifiable Credentials sourced from the Verifiable Presentation (VC in attribute vc
, issuance date iat
nbf
, Subject DID sub
, ...)
verification_result: (VerificationResult)
valid: Boolean
overall valid state
policyResults: Map[Policy -> Boolean]
e.g. policyResults={SignaturePolicy=true, ChallengePolicy=true, PresentationDefinitionPolicy=true}
(Empty values that are not set [= null] are omitted for this example, e.g. no expirationDate was set, thus you'll receive "expirationDate": null
)
Key | Description | Example |
---|---|---|
Key | Description | Example |
---|---|---|
Key | Description | Example |
---|---|---|
Key | Description | Example |
---|---|---|
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/present?...
walletId
Wallet ID as configured in the tenant configuration
walletId=walt.id
vcType
Credential type that should be requested in the presentation request. Can be specified multiple times
vcType=VerifiableId&vcType=Europass
pdByReference
If true, the presentation definition will be passed as a URI in the presentation request (see presentation_definition_uri
), otherwise a full PD object is included in the presentation_definition
parameter.
pdByReference=false
verifierUiUrl
Web redirection URL, on which the verification result will be received. The browser will be navigated to this URL with the sub-path /success, containing an access_token parameter, which can be used to obtain the verification result, overrides the verifierUiUrl
configuration parameter in the tenant configuration
verifierUiUrl=https://myservice.example.com/verification/callback/, will be called like: https://myservice.example.com/verification/callback/success/?access_token=abc123
verificationCallbackUrl
Webhook to actively callback with the verification result (see also Verification callbacks), the URL needs to be configured as allowed webhook in the tenant configuration.
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/presentXDevice?...
vcType
Credential type that should be requested in the presentation request. Can be specified multiple times
vcType=VerifiableId&vcType=Europass
pdByReference
If true, the presentation definition will be passed as a URI in the presentation request (see presentation_definition_uri
), otherwise a full PD object is included in the presentation_definition
parameter.
pdByReference=false
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/verify/isVerified?...
state
The request ID as returned by the presentXDevice
API call
state=req123
tenantId
Path parameter, the tenant ID for this request
/verifier-api/default/auth?...
access_token
The access token, as returned in web redirection URL or cross-device verification response
access_token=abc123