Verifying SD-JWT VC credentials via OID4VC
This guide provides a comprehensive walkthrough for verifying a SD-JWT VC credentials based on the IETF standard using the walt.id Enterprise verifier API. The verification process will utilize the OID4VP protocol, an extension of OpenID, facilitating secure and standardized communication between identities.
SD-JWT 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.
OID4VP: A protocol specifying how parties can present VCs 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.
Preparing the Verification
First, determine the type of SD-JWT VC Credential to be verified. Although this guide focuses on a "VerifiableDiploma," you can use any credential type compliant with the IETF standard.
The verification process will be as follows:
- Specify the credential type(s) to request from a user and the verification policies to be applied to the credential( s).
- Optionally provide a success and failure redirect URL, which the user will be redirected to after the verification process is completed.
After you have provided the required information:
- The API generates a DCQL (Digital Credential Query Language) request.
- API returns a URL which can passed to OIDC-compliant wallet to fulfill the request.
If you have provided a success or failure redirect URL, the user will be redirected to that URL. You can then access the verification results by using the id of the verification session, which can be found in the URL generated by the API, as well as in the query or path parameters of the redirect URL.
Example Verification Request
In this example, we specify the credential we want to verify by supplying the type.
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": "pid",
"format": "dc+sd-jwt",
"meta": {
"vct_values": [
"http://{orgID}.enterprise-sandbox.waltid.dev/v1/waltid.issuer/issuer-service-api/openid4vc/draft13/identity_credential"
]
},
"claims": [
{
"path": [
"given_name"
]
},
{
"path": [
"family_name"
]
},
{
"path": [
"address",
"street_address"
]
}
]
}
]
},
"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.