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 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
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 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": [
"ES256"
],
"credential_definition":{
"type": [
"VerifiableCredential",
"OneIDAgeOver18Credential"
],
"credentialSubject": {
"age_over_18": {
"display": [
{
"name": "Age Over 18",
"locale": "en-US"
}
]
}
}
},
"proof_types_supported": {
"jwt": {
"proof_signing_alg_values_supported": [
"ES256"
]
}
},
"display": [
{
"name": "Age Over 18 Credential",
"locale": "en-US",
"logo": {
"url": "https://oneidageover18logo",
"alt_text": "OneID Age Over 18 logo"
},
"background_color": "#12107c",
"text_color": "#FFFFFF"
}
]
}
}
}
