Requesting a Known Customer Credential

Known Customer Credentials (KCCs) are Verifiable Credentials designed to streamline the Know Your Customer (KYC) process for tbDEX protocol users. KCCs help in gaining access to PFIs that provide regulated financial services.

For a comprehensive exploration of the practical applications and compliance considerations of KCCs, refer to the KCC Compliance Guide. It provides detailed examples and insights into how KCCs align with certain regulatory requirements. This offers valuable context for those overseeing the implementation and management of KCCs.

In this guide, we'll cover:

• Identity Verification (IDV): How your Wallet App initiates and supports the IDV process conformant with Self Issued OpenID Provider V2 (SIOPv2) and OpenID for Verifiable Presentations (OID4VP), ensuring users can securely verify their identity.
• Credential Request: The steps needed for your Wallet App to request a KCC on a user's behalf after successful IDV.
• Credential Management: How the Wallet utilizes existing credentials for KCC requests and securely stores the KCC itself.

INFORMATION

For a detailed guide on Known Customer Credentials for Issuers, please refer to the Issuer's Known Customer Credential Guide

Environment Setup

Install Dependencies

Your Wallet App will require libraries for handling HTTP requests and processing JSON Web Tokens(JWTs). You can include these libraries in your project by installing the following dependencies:

npm install @web5/credentials@1.1.1
npm install @web5/dids@1.1.5
npm install @node-fetch

Framework Flexibility

The core logic provided in the code snippets of this guide is designed to be adaptable across different development environments. The code examples primarily cater to a Node.js environment however, the concepts shown can be applied within various frameworks or platforms, including web applications, server-side applications, and mobile applications. Depending on your development context, you'll need to adjust aspects like HTTP request handling, and secure storage to align with the practices and libraries of your chosen framework or platform.

IDV Process

Identity Verification is a critical component of typical KYC requirements, where certain types of Personally Identifiable Information (PII) are collected and verified from an individual. IDV is a crucial step before a KCC can be issued.

sequenceDiagram
autonumber
participant App as Customer's Wallet App
participant DID as DID Resolver
participant I as Issuer

App->>+DID: Resolve Issuer's DID
DID-->>-App: DID Document with IDV Service Endpoint
App->>+I: HTTP Request to IDV Service Endpoint
I->>I: Process Request
I-->>-App: SIOPv2 Authorization Request
App->>App: Decode & Process SIOPv2 Auth Request
App->>+I: SIOPv2 Authorization Response with id_token (& vp_token if applicable)
I-->>-App: Process Authorization Response

1. Get IDV Endpoint

Resolve the Issuer's DID to get the IDV service Endpoint that can be found in the Issuer's DID Document:

No snippet found for javascript

2. Send HTTP request to Service Endpoint

Send an HTTP request to the IDV Service Endpoint:

No snippet found for javascript

3. Create SIOPv2 Authorization Response

Decode the Issuer's SIOPv2 Authorization Request and create a SIOPv2 Authorization Response with id_token and vp_token:

No snippet found for javascript

INFORMATION

If the User's Verifiable Credentials do not satisfy the Authorization Request's Presentation Definition then only the id_token will be sent to the Issuer's response_uri. If the credentials do satisfy then a Verifiable Presentation (vp_token) will also be sent.

Processing the Credential Offer

After successful completion of the Identity Verification - whether via form or the necessary VCs - your Wallet application will then begin processing the credential_offer from the Issuer.

1. Extract Credential Offer

Extract and store the credential_issuer URL and pre_authorized_code from the credential offer:

No snippet found for javascript

2. Get Issuer's Metadata

Fetch the Issuer's Metadata from the credential_issuers URL

To construct the URL to fetch the Issuer's Metadata, the Wallet needs to append /.well-known/openid-credential-issuer to the credential_issuer URL provided in the credential_offer:

No snippet found for javascript

3. Get Authorization Server's Metadata

Fetch the Authorization Server's Metadata

Before the Wallet can request a KCC from the Issuer, the Wallet needs to also fetch the Issuer's Authorization Server Metadata by appending /.well-known/oauth-authorization-server to the credential_issuer URL in handleIssuerResponse():

No snippet found for javascript

The Server Authorization Metadata can look like this:

Server Authorization Metadata

// Issuer.js

{
"issuer": "https://issuer.example.com", // URL of the Credential Issuer
"token_endpoint": "https://issuer.example.com/token", // URL for the Access Token Request
};

4. Get Access Token

Fetch the Access Token from the Issuer's /token endpoint:

No snippet found for javascript

INFORMATION

If the IDV process is incomplete, the Issuer will return an authorization_pending error. In this case, the Wallet should wait for a short period before attempting another request to the Issuer's /token endpoint. This will allow time for the IDV process to be completed. The Wallet should continue these periodic attempts until an access_token is successfully received, indicating that the IDV process has concluded and authorization has been granted.

Here's an example Access Token Response from the Issuer:

Access Token Response

// Issuer.js
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkaWQ6ZXhhbXBsZTpPcTJ4T0J4NVVjIiwiaXNzIjoiZGlkOmV4YW1wbGU6SXNzdWVyRGlkIiwiaWF0IjoxNjE1MjM5MDIyLCJleHAiOjE2MTUzMjU0MjIsImNfbm9uY2UiOiJzYW1wbGVjbm9uY2UifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"token_type": "bearer",
"expires_in": 86400,
"c_nonce": "adQssw5c",
"c_nonce_expires_in": 86400
}

Request Known Customer Credential

After receiving the access_token from the Issuer, the Wallet can now send a KCC request to the credential_endpoint that was in the Issuer's Metadata.

Send Request to Issuer's Credential Endpoint

Sign and Send an HTTP POST request to the Issuer's credential endpoint:

No snippet found for javascript

INFORMATION

To learn more about the fields within the payload and header, please refer to OpenID's specs.

The Known Customer Credential will be a signed VC JSON Web Token for secure transmission.

Example Known Customer Credential

To convert the signed VC JWT into a VerifiableCredential object you can use the parseJwt() method. Here is what a decoded Known Customer Credential would look like:

{
"vcDataModel": {
"@context": ["https://www.w3.org/2018/credentials/v1"],
"type": ["VerifiableCredential"],
"id": "urn:uuid:12345678-1234-5678-1234-567812345678",
"issuer": "did:dht:z6Mkn4w6nSaWe4fjNJRvaHZwFnMm5VexvjzDeozEu2G7jC34",
"issuanceDate": "2024-01-01T19:23:24Z",
"expirationDate": "2026-05-19T08:02:04Z",
"credentialSchema": {
id: "https://vc.schemas.host/kcc.schema.json",
type: "JsonSchema"
},
"evidence": [
{
  kind: "document_verification",
  checks: ["passport", "utility_bill"]
},
{
  kind: "sanction_screening",
  checks: ["PEP"]
}
],
"credentialSubject": {
"id": "did:dht:z6MkjGSeekPGE9QfczHWyW8v2ZzJU68kqSHzV7L2dmQyuyDu",
"countryOfResidence": "US",
"tier": "Gold",
"jurisdiction": {
  "country": "US"
}
}
}
}

To the user, an example KCC may look like this:

With that, you've successfully gone through the Identity Verification flow, requested a Known Customer Credential on behalf of the user, and securely stored the user's Known Customer Credential. Please note that this example is a foundational implementation. For a production environment, it's crucial to enhance this basic setup with comprehensive error handling, secure storage and security measures.

Next Steps

For an example of the complete flow for requesting and issuing a KCC, check out the Known Customer Credential Exemplar on GitHub. This exemplar provides a implementation of requesting and issuing a Known Customer Credential (KCC).