Credential Issuance

Credential Issuance Service provides applications with secure methods of issuing and claiming credentials. It implements the OID4VCI (OpenID for Verifiable Credential Issuance) protocol, which provides the mechanism for Issuers to issue Verifiable Credentials to Affinidi Vault users and obtain the credentials using the OAuth 2.0 authorisation flow.

The Credential Issuance Service follows a pre-defined Schema to issue Verifiable Credentials to users and cryptographically signs the credentials using wallets. The verifiers/requesters can later use the Issuer’s DID value to verify the credentials.

Benefits of Credential Issuance Service

• Secured Issuance and Claim: The issuance and claim of Verifiable Credentials uses OpenID for Verifiable Credential Issuance (OID4VCI) standard, which is an OAuth 2.0-based mechanism to authorise access to the issued credentials benefiting from its well-established security, simplicity, and flexibility.

• Issue VCs from Preferred Wallet: The Credential Issuance Service allows Issuers to select from the list of supported Wallets (DID Methods) to issue and sign the credential, enabling them to utilise the provided benefits of each wallet.

• W3C-compliant Credential Issuance: The Credential Issuance Service issues credentials to users using the W3C Verifiable Credential standard and allows you to define the list of supported schemas for your issuance flow.

How Credential Issuance Works

When issuing a Verifiable Credential, three main flows happen within the whole process:

Issuance Configuration

First, the Issuer creates the issuance configuration required to issue Verifiable Credentials to the consumers. In this configuration, they select the wallet that will sign the credentials and list the supported schemas to create the user credential offer. Supported schemas can be multiple types with different data structures depending on the requirements.

sequenceDiagram
    actor Developer
    participant Affinidi Portal
    participant Credential Issuance Service

    Developer->>Affinidi Portal: Configure a Credential Issuance Config
    Affinidi Portal->>Credential Issuance Service: Create a Credential Issuance Configuration
    Note over Affinidi Portal, Credential Issuance Service:  Credential Issuance Configuration allows only 1 configuration per Project
    Credential Issuance Service->>Credential Issuance Service: Create / Link a wallet for signing
    Credential Issuance Service->>Credential Issuance Service: Create an Issuance Configuration with details provided
    Credential Issuance Service->>Affinidi Portal: Return the created/linked wallet, including supported Schema
    Affinidi Portal->>Developer: Provide details of the Issuance Configuration to use for issuing credentials

To create an Issuance Configuration, follow these steps. Additionally, Credential Issuance allows you test your configuration before integrating with your application.

Credential Issuance Flow

In the Credential Issuance flow, Issuers implement the required business logic within their applications, which initiates the issuance of a credential offer that users can claim in their Affinidi Vault.

For example, on an Online Course website, you can issue a credential attesting that the student completes the course.

In this example, the website calls the Credential Issuance Service to create a Credential Offer containing the details about the course. The structure of the Credential Offer is based on one of the supported schemas configured in the Issuance Configuration. It returns the URI of the Credential Offer and Transaction Code that the website sends to the user to claim from the Affinidi Vault.

sequenceDiagram
    participant Website
    participant Credential Issuance Service
    actor User

    User-->>Website: Completes a task or course and request for certificate.
    Website->>Credential Issuance Service: Create a credential offer for the user
    Note over Website, Credential Issuance Service:  Credential data includes the supported Schema, User's wallet DID, and credential details to issue
    Credential Issuance Service->>Credential Issuance Service: Validates the credential data based on Issuance Configuration
    Credential Issuance Service->>Credential Issuance Service: Signs the Credential with the configured wallet
    Credential Issuance Service->>Website: Returns the Transaction Code and Offer URI to claim the credential from the Affinidi Vault
    Website-->>User: Send the Credential Offer to the user with the Transaction Code to claim the credential in a form of a link or QR code

Credential Offer Claim Modes

When creating a Credential Offer, you must specify the Claim Mode (claimMode) for how the user retrieves and claims the credential to store it in their Affinidi Vault. In the Credential Issuance, these are the supported claim modes:

• TX_CODE generates a transaction code that must be shared securely with the user. The generated transaction code must be entered by the user to retrieve and claim the credential. When creating a credential offer with TX_CODE as the claim mode, the user’s Decentralised Identifier (DID) is optional.

  If the user’s DID is provided when creating the credential offer with the TX_CODE claim mode, the Credential Issuance Service will validate the credential proof if the DID of the current user claiming the credential matches the DID on the credential offer.

• FIXED_HOLDER does not generate a Transaction Code but requires the user’s Decentralised Identifier (DID) when creating the credential offer. The Credential Issuance Service will validate the credential proof if the DID of the current user claiming the credential matches the DID on the credential offer.

  To get the DID of the user, you must implement  Affinidi Login to authenticate and extract the user’s DID value from the ID Token provided.

• NORMAL is the same as the FIXED_HOLDER claim mode option and will be deprecated in future releases.

Credential Offer Claim Flow

The Credential Offer is only valid for claims based on the Lifetime of the Credential Offer configured in the Issuance Configuration. If the user fails to claim the credential by this time, the website should create a new credential offer.

When the user clicks on the Credential Offer link, it redirects them to the Affinidi Vault’s claim credential page. The Affinidi Vault exchanges the pre-authorisation code and transaction code to get the access token required to retrieve the credential details.

While retrieving the credential details, if the Holder DID (holderDid) is provided regardless of the claim mode, whether FIXED_HOLDER or TX_CODE, the Credential Issuance Service validates the proof of the credential to verify that the user claiming the credential matches the Holder’s DID provided in the Credential Offer. It throws an error if the proof validation fails.

After the user accepts the credential, it is securely stored in the Affinidi Vault and can be shared later when requested. The user can claim and store the credential only once, and you have to create another Credential Offer if you want to duplicate it for different profiles available on their Affinidi Vault.

sequenceDiagram
    actor User
    participant Affinidi Vault
    participant Credential Issuance Service
    participant Website

    User->>Affinidi Vault: Enters the Transaction Code to view the Credential Offer
    Affinidi Vault->>Credential Issuance Service: Resolves Offer URI and get the Credential Offer with Access Token
    Note over Affinidi Vault, Credential Issuance Service: Affinidi Vault will exchange Trx Code and Pre-Auth Code <br /> for the Access Token to Get the Credential
    Credential Issuance Service->>Credential Issuance Service: Validate credential proof
    Credential Issuance Service->>Credential Issuance Service: Update Credential Offer as Claimed
    Credential Issuance Service->>Affinidi Vault: Return the Verifiable Credential
    Affinidi Vault->>User: Presented the Verifiable Credential
    User->>Affinidi Vault: Accepts the Verifiable Credential
    Affinidi Vault->>Affinidi Vault: Securely Stores the Verifiable Credential
    Website-->>Credential Issuance Service: Checks the status of the Offer
    Website-->>Website: Update the website based on the Offer status

Implement Credential Issuance