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

sequenceDiagram User->>Wallet: User selects Credential Wallet->>Credential Issuer: Request Issuer metadata Wallet->>Credential Issuer: Authorization Request (in browser) Credential Issuer->>Bank: Verify Identity Credential Issuer->>Wallet: Authorization Response (code) Wallet->>Credential Issuer:Token Request (code) Credential Issuer->>Wallet: Token Response (access token) Wallet->>Credential Issuer: Credential Request Credential Issuer->>Wallet: Credential Response (credential)

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

Javascript
    
 
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"}]
Copy

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.

Javascript
    
 
HTTP/1.1 302 FoundLocation: https://Wallet.example.org/cb?    code=SplxlOBeZQQYbYS6WxSbIA
Copy

Authorization Error

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

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

Token Endpoint

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

Javascript
    
​x
 
POST /token HTTP/1.1Host: controller.myoneid.co.ukAuthorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=Content-Type: application/x-www-form-urlencoded​grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
Copy

Token Response

Javascript
    
 
HTTP/1.1 200 OKContent-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"      }    ]}
Copy

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.

Javascript
    
 
POST /credential HTTP/1.1Host: controller.myoneid.co.ukAuthorization: BEARER czZCaGRSa3F0MzpnWDFmQmF0M2JWContent-Type: application/json​{      "credential_identifier": "OneIDAgeVerificationCredential",   "proof": {      "proof_type": "jwt",      "jwt":        "eyJ0eXAiOiJvcGVuaWQ0dmNpLXByb29mK2p3dCIsImFsZyI6IkVTMjU2IiwiandrI        jp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiblVXQW9BdjNYWml0aDhFN2k        xOU9kYXhPTFlGT3dNLVoyRXVNMDJUaXJUNCIsInkiOiJIc2tIVThCalVpMVU5WHFpN        1N3bWo4Z3dBS18weGtjRGpFV183MVNvc0VZIn19.eyJhdWQiOiJodHRwczovL2NyZW        RlbnRpYWwtaXNzdWVyLmV4YW1wbGUuY29tIiwiaWF0IjoxNzAxOTYwNDQ0LCJub25j        ZSI6IkxhclJHU2JtVVBZdFJZTzZCUTR5bjgifQ.-a3EDsxClUB4O3LeDD5DVGEnNMT        01FCQW4P6-2-BNBqc_Zxf0Qw4CWayLEpqkAomlkLb9zioZoipdP-jvh1WlA"   }}
Copy

Credential Success

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

Javascript
    
 
HTTP/1.1 200 OKContent-Type: application/jsonCache-Control: no-store​{  "credential": "LUpixVCWJk0eOt4CXQe1NXK....WZwmhmn9OQp6YxX0a2L",  "notification_id": "notification-id-1234"}
Copy

Credential Error

Possible Errors

invalid_credential_request
unsupported_credential_type
invalid_proof
invalid_encryption_parameters

Javascript
    
 
HTTP/1.1 400 Bad RequestContent-Type: application/jsonCache-Control: no-store​{   "error": "unsupported_credential_format",   "error_description": "this is a description of the error"}
Copy

Notification Endpoint

Notification Request

Javascript
    
 
POST /notification HTTP/1.1Host: server.example.comContent-Type: application/jsonAuthorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW​{  "notification_id": "3fwe98js",  "event": "credential_accepted"}
Copy

Javascript
    
 
POST /notification HTTP/1.1Host: server.example.comContent-Type: application/jsonAuthorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW​{  "notification_id": "3fwe98js",  "event": "credential_failure",  "event_description": "Could not store the Credential. Out of storage."}
Copy

Notification Success

Javascript
    
 
HTTP/1.1 204 No Content
Copy

Notification Error

Javascript
    
 
HTTP/1.1 400 Bad RequestContent-Type: application/jsonCache-Control: no-store{   "error": "invalid_notification_id"}
Copy

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

Javascript
    
 
{    "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"                }            ]        }    }}
Copy

Last updated on

Was this page helpful?