Verifying Verifiable Credentials (W3C) via OID4VC
This guide provides a comprehensive walkthrough for verifying a Verifiable Credential based on the W3C standard using the walt.id Enterprise verifier API. The verification process will utilize the OID4VCI protocol, an extension of OpenID, facilitating secure and standardized communication between identities.
Verifiable Credential (VC): A digital equivalent of physical credentials such as a driver's license or university degree. VCs are cryptographically secure, privacy-respecting, and instantly verifiable.
OID4VCI: A protocol specifying how parties can issue VCs and present these credentials in a way that's consistent and secure across platforms ensuring interoperability.
Enterprise Service Dependencies
To verify credentials, you need to have the following enterprise services setup:
- Verifier Service - Have a running verifier service. Setup instructions can be found here.
Example Verification Request 1 - Basic
For this example, we will only do a simple verification, where we request one credential type, a Verifiable Diploma, and let the system apply the default signature policy to verify the validity of the signature of the presented credential. Optionally we can provide a success and failure redirect URL, which the user will be redirected to after the verification.
curl -X 'POST' \
'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/verifier2-service-api/verification-session/create' \
-H 'accept: */*' \
-H 'Authorization: Bearer {yourToken}' \
-H 'Content-Type: application/json' \
-d '{
"dcql_query": {
"credentials": [
{
"id": "example_openbadge_jwt_vc",
"format": "jwt_vc_json",
"meta": {
"type_values": [
[
"VerifiableCredential",
"OpenBadgeCredential"
]
]
},
"claims": [
{
"path": [
"name"
]
}
]
}
]
},
"policies": {
"vcPolicies": [
{
"policy": "signature"
}
]
},
"redirects": {
"successRedirectUrl": "https://example.com/success",
"errorRedirectUrl": "https://example.com/error"
},
"urlHost": "https://example.com",
"urlPrefix": "openid4vp://authorize",
"preset": "cross_device_flow",
"signedRequest": true,
"encryptedResponse": true,
}'
Path Parameters
orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is namedtest, your default Base URL will betest.enterprise-sandbox.walt.devwhen using the sandbox environment.target: resourceIdentifier - The target indicates the organization + tenant + verifier service with which to execute the credential verification ({organizationID}.{tenantID}.{verifierServiceID}), e.g.waltid.tenant1.verifier1
Body Parameters
- policies: An array of policies to apply to the specified credential. A list of all policies can be found here.
- dcql_query - An object detailing the credentials to be requested from the user.
- redirects - An object containing the success and error redirect URLs. In previous versions of the verifier service, the redirect URLs were passed through headers
successRedirectUrianderrorRedirectUri. - urlHost - The host of the URL to be used for the verification session. In previous versions of the verifier service, the urlHost was passed through header
authorizeBaseUrl. - urlPrefix - The prefix of the URL to be used for the verification session.
- preset - The preset to be used for the verification session. Options are
cross_device_flowandsame_device_flow. - signedRequest - Whether the request should be signed.
- encryptedResponse - Whether the response should be encrypted.
{
"sessionId": "ff4f0c86-56ce-4e4a-a137-dd5569049ff3",
"bootstrapAuthorizationRequestUrl": "openid4vp://authorize?client_id=did%3Ajwk%3AeyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiU05JZ1ItTHZzSEUtNkhUUGxYYUpQVDVubHRZMFpqZlA0VkpTWEwzQ2ZkMCIsIngiOiJIVWM1ZHY1eFREV3VMVmZQcFdvVXBWTjZ1QTNJNzBsVzVnNEhoMG5VaDQ0In0&request_uri=http%3A%2F%2Forg.enterprise.localhost%3A3000%2Fv1%2Forg.tenant.verifier%2Fverifier2-service-api%2Fff4f0c86-56ce-4e4a-a137-dd5569049ff3%2Frequest",
"fullAuthorizationRequestUrl": "openid4vp://authorize?response_type=vp_token&client_id=did%3Ajwk%3AeyJrdHkiOiJPS1AiLCJjcnYiOiJFZDI1NTE5Iiwia2lkIjoiU05JZ1ItTHZzSEUtNkhUUGxYYUpQVDVubHRZMFpqZlA0VkpTWEwzQ2ZkMCIsIngiOiJIVWM1ZHY1eFREV3VMVmZQcFdvVXBWTjZ1QTNJNzBsVzVnNEhoMG5VaDQ0In0&state=8faa6212-465f-4e3f-9a44-649d3d65845c&response_mode=direct_post&nonce=9a054852-46ab-4bbe-8fc1-b96882afcc4f&response_uri=http%3A%2F%2Forg.enterprise.localhost%3A3000%2Fv1%2Forg.tenant.verifier%2Fverifier2-service-api%2Fff4f0c86-56ce-4e4a-a137-dd5569049ff3%2Fresponse&dcql_query=%7B%22credentials%22%3A%5B%7B%22id%22%3A%22pid%22%2C%22format%22%3A%22dc%2Bsd-jwt%22%2C%22meta%22%3A%7B%22vct_values%22%3A%5B%22http%3A%2F%2Forg.enterprise.localhost%3A3000%2Fv1%2Fwaltid.issuer%2Fissuer-service-api%2Fopenid4vc%2Fdraft13%2Fidentity_credential%22%5D%7D%2C%22claims%22%3A%5B%7B%22path%22%3A%5B%22given_name%22%5D%7D%2C%7B%22path%22%3A%5B%22family_name%22%5D%7D%2C%7B%22path%22%3A%5B%22address%22%2C%22street_address%22%5D%7D%5D%7D%5D%7D&client_metadata=%7B%22client_name%22%3A%22walt.id+Enterprise+Verifier%22%2C%22logo_uri%22%3A%22https%3A%2F%2Fcdn.walt.id%2Fverifier%2Flogo.png%22%7D",
"creationTarget": "org.tenant.verifier.ff4f0c86-56ce-4e4a-a137-dd5569049ff3"
}
You will receive a response containing the following fields:
- sessionId: The ID of the verification session.
- bootstrapAuthorizationRequestUrl: The shortened URL to the authorization request.
- fullAuthorizationRequestUrl: The full URL to the authorization request.
- creationTarget: The target of the verification session.
At this point you can pass either the bootstrapAuthorizationRequestUrl or the fullAuthorizationRequestUrl to the user to complete the verification process.
Validating the Verification Session
You can query the verification session by using the following endpoint:
curl -X 'GET' \
'http://{orgID}.enterprise-sandbox.waltid.dev/v1/{creationTarget}/verifier2-service-api/verification-session/info' \
-H 'accept: application/json'
-H 'Authorization: Bearer {yourToken}'
Path Parameters
orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is namedtest, your default Base URL will betest.enterprise-sandbox.walt.devwhen using the sandbox environment.creationTarget: resourceIdentifier - The target creation target returned when creating the verification session. It is a concatenation of the target resource and the session ID.
This will return the verficiation session object containing the following useful fields:
status: The status of the verification session.attempted: Whether the verification session has been attempted.reattemptable: Whether the verification session can be retried.policyResults: The results of the policies applied to the verification session.presentedRawData: The raw data verifiable presentation token.presentedCredentials: The parsed credentials presented by the user.
Policy results will be split into vcPolicy and vpPolicy results. More information about the policy results can be found here.
Alternatively, if you do not want to poll the verification session you can use a callback or Server Sent Events (SSE) to be notified when the verification session is completed.