Verifiable Credentials Issuance

This guide describes how to issue OneID® Verifiable Credentials. The protocol that we support is OpenID for Verifiable Credential Issuance.

Issuance Flow Chart

Supported Features



Flow

Authorization Code Flow

Credential Format Profile

VC signed as a JWT (jwt_vc_json)

Proof Types

JWT

Authorization Endpoint

The authorization endpoint is used in the same manner as our base journey, but with some additional parameters.

  • authorization_details

    • type is required and is always set to openid_credentials

    • credential_configuration_id should be the id for the required credential

Authorization Request

GET https://controller.myoneid.co.uk/v2/authorize
?client_id=1234
&redirect_uri=https://example.myoneid.co.uk/return
&response_type=code
&scope=openid age_over_18 product:age_check
&state=randomstateid1234
&authorization_details=[{"type":"openid_credential","credential_configuration_id":"OneIDAgeVerificationCredential"}]

Authorization Success

When the authorization process is successful the user will be redirected back to the redirect uri provided on the authorization request along with a code.

HTTP/1.1 302 Found
Location: https://Wallet.example.org/cb?
code=SplxlOBeZQQYbYS6WxSbIA

Authorization Error

When there is an error in the authorization process the user is redirected back with an error and error_description provided.

HTTP/1.1 302 Found
Location: https://client.example.net/cb?
error=invalid_request
&error_description=Unsupported%20response_type%20value

Token Endpoint

The code that was returned for the user can now be exchanged for a token on the token endpoint.

POST /token HTTP/1.1
Host: controller.myoneid.co.uk
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

Token Response

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"2f1f65ea-1954-4bbc-81bf-e16582b143b3",
"token_type":"Bearer",
"expires_in":300,
"id_token":"eyJhbGciOiJQUzI1NiIsImtpZCI6ImhWVktTd...",
"c_nonce": "tZignsnFbp",
"c_nonce_expires_in": 86400,
"authorization_details": [
{
"type": "openid_credential",
"credential_configuration_id": "OneIDAgeVerificationCredential"
}
]
}

Credentials Endpoint

The credential endpoint issues verifiable credentials when a valid access token representing user approval is presented.

Credential Request

  • proof should be set and proof_type should be jwt.

  • c_nonce returned from the token endpoint should be included in the audience claim in the jwt.

POST /credential HTTP/1.1
Host: controller.myoneid.co.uk
Authorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/json

{
"credential_identifier": "OneIDAgeVerificationCredential",
"proof": {
"proof_type": "jwt",
"jwt":
"eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2IiwiandrI
jp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiblVXQW9BdjNYWml0aDhFN2k
xOU9kYXhPTFlGT3dNLVoyRXVNMDJUaXJUNCIsInkiOiJIc2tIVThCalVpMVU5WHFpN
1N3bWo4Z3dBS18weGtjRGpFV183MVNvc0VZIn19.eyJhdWQiOiJodHRwczovL2NyZW
RlbnRpYWwtaXNzdWVyLmV4YW1wbGUuY29tIiwiaWF0IjoxNzAxOTYwNDQ0LCJub25j
ZSI6IkxhclJHU2JtVVBZdFJZTzZCUTR5bjgifQ.-a3EDsxClUB4O3LeDD5DVGEnNMT
01FCQW4P6-2-BNBqc_Zxf0Qw4CWayLEpqkAomlkLb9zioZoipdP-jvh1WlA"
}

Credential Success

The notification_id should be used to post updates to the notification endpoint.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
"credential": "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L",
"notification_id": "notification-id-1234"
}

Credential Error

Possible Errors

  • invalid_credential_request

  • unsupported_credential_type

  • invalid_proof

  • invalid_encryption_parameters

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
"error": "unsupported_credential_format",
"error_description": "this is a description of the error"
}

Notification Endpoint

Notification Request

POST /notification HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
"notification_id": "3fwe98js",
"event": "credential_accepted"
}
POST /notification HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
"notification_id": "3fwe98js",
"event": "credential_failure",
"event_description": "Could not store the Credential. Out of storage."
}

Notification Success

HTTP/1.1 204 No Content

Notification Error

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
{
"error": "invalid_notification_id"
}

Credential Issuer Metadata

The Credential Issuer Metadata contains information on the Credential Issuer's technical capabilities, supported Credentials, and (internationalized) display information.

This document lives under /.well-known/openid-credential-issuer

{
"credential_issuer": "https://oneid.uk",
"credential_endpoint": "https://controller.myoneid.co.uk/v2/credentials",
"display": [
{
"name": "OneID",
"locale": "en-US",
"logo": {
"uri":"https://oneidlogo.svg",
"alt_text": "OneID"
}
},
{
"name": "OneID",
"locale": "en-GB"
},
],
"credential_configurations_supported": {
"OneIDAgeOver18Credential": {
"format": "jwt_vc_json",
"scope": "OneIDAgeOver18",
"cryptographic_binding_methods_supported": [
"did:example"
],
"credential_signing_alg_values_supported": [


Next to read:
Verifiable Credentials Profile

@Copyright OneID Limited 2024

On This Page
Verifiable Credentials IssuanceIssuance Flow ChartSupported FeaturesAuthorization EndpointToken EndpointCredentials EndpointNotification EndpointCredential Issuer MetadataAuthorization RequestAuthorization SuccessAuthorization ErrorToken ResponseCredential RequestCredential SuccessCredential ErrorNotification RequestNotification SuccessNotification Error