This section elaborates the theory behind the Wallet:

• Wallet Basics - Learn what the Wallet Kit is and what it does.

• Architecture - Explore the architecture and components.

• Feature List - Explore all features in an overview list

This documentation will help you understand how the Wallet works and how you can use it. However, it presumes a certain level of knowledge about Self-Sovereign Identity (SSI) so

• if you are already familiar with SSI, you can jump to the introduction of the Wallet.

• if you are new to SSI, please continue with our introduction to Self-Sovereign Identity.

What is SSI?

Self-Sovereign Identity (SSI) is a user-centric approach to digital identity that gives people and organizations full control over their data. As a result, SSI enables anyone to easily share their data and reliably prove their identity (i.e. who they are and anything about them) without sacrificing security or privacy.

In other words, SSI enables you to “bring your own identity” and this is true for potentially any type of information - from your core identity (e.g. name, age, address) to your education and work records, your health and insurance data, bank account and financial information, etc.

Moreover, SSI can be used to model the digital identities of people, organizations and things.

At the end of the day, SSI promises a digital world in which interactions are effortless and worry-free. It is simply the next evolutionary step in identity management, a new paradigm in which our digital identities are no longer fragmented and locked into silos that are under someone else’s control, but only at our own disposal to be shared securely and privately.

How does SSI work?

SSI allows us to model digital identity just like we are used to the way identity works in the non-digital world based on paper documents and cards. There are just some minor twists.

For example, instead of our identity documents being made of paper or plastic, they are digital credentials made of bits and bytes and instead of storing them in wallets made of leather, they are stored in digital wallets on our phones. Importantly, these digital credentials can be reliably verified by anyone they are shared with online or offline.

In doing so, SSI enables decentralized ecosystems in which different parties can exchange and verify identity-related information. These ecosystems look like three-sided marketplaces, so that every party can take on three roles:

• Issuers - Parties who “issue” identity-related data to people or organizations (“Holders”) in the form of digital credentials. They are the original data sources of an SSI ecosystem. For example, a government issues digital passports to citizens or a university issues digital diplomas to graduates.

• Holders - Individuals or organizations who receive digital credentials that contain data about themselves from various sources (“Issuers”). By aggregating and storing such credentials in digital wallets, Holders can build holistic digital identities that are under their control and can easily be shared with third parties ("Verifiers").

• Verifiers - Parties who rely on data to provide products and services can reliably verify and process data that has been provided by others (“Holders”). Verifiers, also called “Relying Parties”, are usually organizations or individuals in their professional capacity.

Usually, a single party plays only one of these roles per interaction. However, it is perfectly normal for a party to take on different roles in different interactions.

For example:

• A university (Holder) is being accredited to issue certain types of educational credentials by a national authority (Issuer).

• A university (Issuer) issues a digital diploma to a graduate (Holder), who can share this information with a recruiter (Verifier) in the course of a job application.

• After the recruiting process, a recruiter (Issuer) issues the results of an applicant’s assessment (e.g. skills, referral) to the applicant (Holder), who can share this information with a new manager or another recruiter (Verifier).

• A manager (Issuer) issues the results of a performance review to his employee (Holder) who can share this information with HR (e.g. to improve talent development programs).

Understanding SSI requires the understanding of a few core concepts:

• Registries, which serve as a shared and trusted record of certain information. In other words, they serve as a “layer of trust” and a “single source of truth”.

• Cryptographic keys, which convey control over digital identities and enable core functionality such as encryption and authentication.

• Decentralized Identifiers (DIDs), which establish a public key infrastructure by linking keys to unique identifiers that allow different parties to find and interact with each other.

• Verifiable Credentials (VCs) which are digital identity documents that can easily and securely be shared with and verified (incl. validity, integrity, authenticity, provenance) by anyone in a privacy preserving way. Importantly, they are never (!) stored on a blockchain due to privacy and compliance reasons.

• Protocols enable the exchange of data (VCs) between different parties.

• Wallets, which store our keys (control) and VCs (identity data) and enable the management and sharing of our digital identities and data via easy-to-use applications.

The following graphic shows the SSI tech stack:

The following graphic shows how SSI works and highlights the core concepts (in blue):

Think of these core concepts as different building blocks that are available in different variations and can be put together in different ways:

As a result, there are different “flavours” of SSI depending on which variations of which building blocks have been used and how they have been put together.

Importantly, the differences in terms of technologies that are being used illustrate why interoperability has always been one of the most important topics within the industry and why the development and use of open standards (e.g. by the W3C, Decentralized Identity Foundation, OpenID Foundation and others) are vital for technology and vendor selection.

Deep Dive

The following section explains all concepts in more detail.

Registries

Registries serve as a single source of truth in which all participants of an SSI ecosystem can trust. Depending on the ecosystem, registries make information accessible to anyone or just a limited group. Registries are important because they enable:

• (Distributed) Public Key Infrastructures (DPKIs) which establishes an open distribution system for public keys which can be used for encryption and authentication among others.

• Trust Registries which contain reliable information about people, organisations, things and even credentials (e.g. data models, status and validity information) to ensure that different parties can trust each other and the identity-related data they exchange.

Different technologies can be used to implement Registries. For example:

• Blockchains or L1: Typically blockchains are used because it is unfeasible (or even impossible) to tamper with them. The fact that no single organisation can change the contents of a blockchain or manipulate the terms by which it is governed are very aligned with the requirements for identity ecosystems. Today, we see a growing number of developers and organizations focusing on so-called permissioned blockchains (i.e. only a selected group can “write”) like Ethereum Quorum/Enterprise. Permissionless blockchains, like Ethereum, are still used, but less than the permissioned alternatives for a variety of reasons like scalability, costs, lack of customisable governance frameworks.

• L2: Layer two networks sit on top of blockchains and aggregate data before anchoring it. The main idea behind them is to circumvent common challenges of public, permissionless blockchains like scalability and cost issues. The most popular implementations in the context of identity are “ION” (for Bitcoin) and “Element” (for Ethereum).

• Other Distributed Ledger Technologies (DLTs): Sometimes other DLTs are utilised like the Interplanetary File System (IPFS) though its use for digital identity remains limited.

• Domain Name Service (DNS): Considering certain drawbacks of DLTs and their relatively slow adoption by the mass market, DNS can also be used to serve as a registry. Though it is not fully decentralised (considering its underlying governance framework), DNS has many advantages like its maturity and global adoption.

Importantly, SSI can be implemented without registries, particularly without blockchains, because identity data (or at least personal data of individuals) is never anchored due to privacy and compliance reasons. However, by combining SSI with blockchains (or other technologies), robust and trustworthy identity ecosystems that utilise transparent DPKIs and reliable Trust Registries can emerge.

Decentralised Identifiers (DIDs)

DIDs are important because they establish a (distributed) public key infrastructure (DPKI) and allow parties to find each other, authenticate and encrypt and verifiably sign data.

A variety of “DID methods'', which are different implementations of the DID specification, exist. Considering that DID methods differ in terms of how they are created, registered and resolved, different methods come with different advantages and disadvantages.

For example, while DIDs are often anchored on Registries, such as EBSI (did:ebsi) or the Domain Name Service (did:web), new methods emerged that do not require Registries because their distribution is based on peer-to-peer interactions (e.g. did:key).

As example, the identifier did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y of the method did:ebsi would resolve to the following DID document:

Verifiable Credentials (VCs) & Verifiable Presentations (VPs)

Verifiable Credentials (VCs) and Verifiable Presentations (VPs) are digital credentials that contain actual identity data of people or organisations and are standardized by the W3C. They are digital equivalents of paper-based identity documents like passports or diplomas.

VCs are created and signed by “Issuers”, the data sources within an SSI ecosystem. Issuers are typically organisations (e.g. governments, universities, banks) who provide people (or other organisations) with VCs that prove identity-related attributes.

For example, a university acts as an Issuer, if it issues diplomas (VCs) to its graduates.

VCs typically contain at least:

• the Issuer’s DID

• the recipient’s DID (also called “Holder”)

• information about the VC’s validity (e.g. expiration date, references to revocation mechanisms)

• the recipient’s identity attributes (e.g. name, age, address, …)

• the signature of Issuer (also called “proof”) other information (e.g. semantic contexts, issuance date, evidence related to the issuance process, references to external VC data models/templates)

Here is an illustrative example of a VC:

VPs are composed and signed by “Holders”. They can contain identity information from one or multiple VCs and are created for the purpose of presenting them to a “Verifier”. In other words, VPs are the format with which the contents of VCs are shared by the person or organisation that is described by the VCs.

For example, a graduate presents a VP to an employer that contains information from her digital passport and diplomas.

VPs typically contain at least:

• VCs or parts of VCs (individual attributes)

• the recipient’s signature (to ensure so-called “Holder binding”)

Here is an illustrative example of a Verifiable Presentation:

Data Exchange (Protocols)

Different authentication and data exchange protocols are used to securely transfer identity data (e.g. VCs, VPs) between parties (e.g. from an Issuer to a Holder). They typically establish a mutually authenticated and encrypted data channel between the communicating parties.

The most common data exchange protocols used for SSI are:

• OIDC4SSI / SIOP (Self-Issued OpenID Connect Provider): An extension of a mature authentication and authorisation protocol called "OpenID Connect" (OIDC).

• DIDComm: A novel protocol specifically designed for SSI and maintained by the Decentralized Identity Foundation (DIF).

• Credential Handler API: A proposed browser-extension that may be used to connect the user's identity wallet to a web-application.

The Wallet Kit (or "wallet backend") as well as the Issuer and Verifier Portals (or "Issuer and Verifier backends") are built as abstraction layers over the SSI Kit. They provide user data separation (user contexts of the underlying data stores) and high-level APIs for the interaction with the web frontends and the credential exchange protocols such as OIDC and SIOP.

Moreover, the wallet backend can be seen as an abstraction over the "Custodian" component of the SSI Kit, whereas the Issuer and Verifier backends build on top of the "Signatory" and "Auditor" components, respectively.

The Community Stack

It has always been our goal to provide developers and organizations with great tools, so they can focus on delivering holistic identity solutions. Taking the lessons learned from previous products, we decided to redesign our current offering, resulting in what we now call The Community Stack. A collection of open-source products providing everything to launch any identity solution with ease. You can learn more about it .

Transition

Starting from December 2023, the Wallet-Kit will halt feature enhancements, leading to a complete discontinuation planned for end-Q3 2024. It's essential to plan your transition to the new stack effectively.

The table below indicates which components of the Wallet-Kit are already supported in the new stack.

If you have any question, please .

The Wallet enables you to launch an identity wallet or extend an existing app with identity capabilities:

Welcome to our Introduction to Self-Sovereign Identity (SSI) for developers and technical readers.

Before you get started, feel free to explore other (less technical) resources that will help you and your team to get a more holistic understanding of SSI and digital identity in general:

• .

Multi-tenancy

Since mid-Jan Q1/23 the Wallet Kit extended it's multi-issuer configurability to a complete multi-tenancy supported system.

All API endpoints for issuer configuration have the option for setting a tenantId.

The default tenantId is "default".

Creating a DID for a tenant

POST /issuer-api/{tenantId}/config/did/create

curl -X 'POST' \
  'http://localhost:8080/issuer-api/default/config/did/create \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "method": "key",
}'

{
    "method": "string*",
    "keyAlias": "string",
    "didWebDomain": "string",
    "didWebPath": "string"
}

Retrieve and update tenant configuration

GET /issuer-api/{tenantId}/config/getConfiguration

curl -X 'GET' \
  'http://localhost:8080/issuer-api/default/config/getConfiguration' \
  -H 'accept: application/json'

{
    "issuerUiUrl": "https://issuer.cheqd.walt-test.cloud",
    "issuerApiUrl": "https://issuer.cheqd.walt-test.cloud/issuer-api/default",
    "issuerClientName": "walt.id Issuer Portal",
    "wallets": {
        "walt.id": {
            "id": "walt.id",
            "url": "https://wallet.cheqd.walt-test.cloud",
            "description": "walt.id web wallet",
            "presentPath": "api/siop/initiatePresentation/",
            "receivePath" : "api/siop/initiateIssuance/"
        }
    }
}

Update issuer configuration to include our generated DID

POST /issuer-api/{tenantId}/config/setConfiguration

curl -X 'POST' \
  'https://wallet.walt-test.cloud/issuer-api/default/config/setConfiguration' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d 'vv JSON BELOW vv'

{
    "issuerUiUrl": "https://issuer.cheqd.walt-test.cloud",
    "issuerApiUrl": "https://issuer.cheqd.walt-test.cloud/issuer-api/default",
    "issuerClientName": "walt.id Issuer Portal",
    "issuerDid": "did:key:z6MknaJ7YLdkCq1QV2tcwVSY5uVfUKGfBdigo7g4PyipTnCc",
    "wallets": {
        "walt.id": {
            "id": "walt.id",
            "url": "https://wallet.cheqd.walt-test.cloud",
            "description": "walt.id web wallet",
            "presentPath": "api/siop/initiatePresentation/",
            "receivePath" : "api/siop/initiateIssuance/"
        }
    }
}

CLI

You can import a DID document using:

config --as-issuer default vc templates import --name TestCredential credential-template.json

The value "default" of --as-issuer refers to the tenantId.

By specifying vc templates --help you can also view other VC template commands (besides import you can list, export and remove)

REST API

List templates you have

GET /issuer-api/{tenantId}/config/templates

curl -X 'GET' \
  'http://localhost:8080/issuer-api/default/config/templates' \
  -H 'accept: application/json'

[
  {
    "mutable": false,
    "name": "Europass",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableAuthorization",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableVaccinationCertificate",
    "template": null
  },
  {
    "mutable": false,
    "name": "KycCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "DataSelfDescription",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableId",
    "template": null
  },
  {
    "mutable": false,
    "name": "UniversityDegree",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableMandate",
    "template": null
  },
  {
    "mutable": false,
    "name": "ProofOfResidence",
    "template": null
  },
  {
    "mutable": false,
    "name": "AmletCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "OpenBadgeCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableDiploma",
    "template": null
  },
  {
    "mutable": false,
    "name": "DataConsortium",
    "template": null
  },
  {
    "mutable": false,
    "name": "DataServiceOffering",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiableAttestation",
    "template": null
  },
  {
    "mutable": false,
    "name": "KybCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "PermanentResidentCard",
    "template": null
  },
  {
    "mutable": false,
    "name": "EuropeanBankIdentity",
    "template": null
  },
  {
    "mutable": false,
    "name": "Iso27001Certificate",
    "template": null
  },
  {
    "mutable": false,
    "name": "LegalPerson",
    "template": null
  },
  {
    "mutable": false,
    "name": "ParticipantCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "GaiaxCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "VerifiablePresentation",
    "template": null
  },
  {
    "mutable": false,
    "name": "PeerReview",
    "template": null
  },
  {
    "mutable": false,
    "name": "ServiceOfferingCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "KybMonoCredential",
    "template": null
  },
  {
    "mutable": false,
    "name": "Email",
    "template": null
  }
]

Show a VC template

GET /issuer-api/{tenantId}/config/templates/{templateId}

curl -X 'GET' \
  'http://localhost:8080/issuer-api/default/config/templates/VerifiableId' \
  -H 'accept: application/json'

{
  "type": [
    "VerifiableCredential",
    "VerifiableAttestation",
    "VerifiableId"
  ],
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "id": "urn:uuid:3add94f4-28ec-42a1-8704-4e4aa51006b4",
  "issuer": "did:ebsi:2A9BZ9SUe6BatacSpvs1V5CdjHvLpQ7bEsi2Jb6LdHKnQxaN",
  "issuanceDate": "2021-08-31T00:00:00Z",
  "issued": "2021-08-31T00:00:00Z",
  "validFrom": "2021-08-31T00:00:00Z",
  "credentialSchema": {
    "id": "https://api.preprod.ebsi.eu/trusted-schemas-registry/v1/schemas/0xb77f8516a965631b4f197ad54c65a9e2f9936ebfb76bae4906d33744dbcc60ba",
    "type": "FullJsonSchemaValidator2021"
  },
  "credentialSubject": {
    "id": "did:ebsi:2AEMAqXWKYMu1JHPAgGcga4dxu7ThgfgN95VyJBJGZbSJUtp",
    "currentAddress": [
      "1 Boulevard de la Libert�, 59800 Lille"
    ],
    "dateOfBirth": "1993-04-08",
    "familyName": "DOE",
    "firstName": "Jane",
    "gender": "FEMALE",
    "nameAndFamilyNameAtBirth": "Jane DOE",
    "personalIdentifier": "0904008084H",
    "placeOfBirth": "LILLE, FRANCE"
  },
  "evidence": [
    {
      "documentPresence": [
        "Physical"
      ],
      "evidenceDocument": [
        "Passport"
      ],
      "subjectPresence": "Physical",
      "type": [
        "DocumentVerification"
      ],
      "verifier": "did:ebsi:2A9BZ9SUe6BatacSpvs1V5CdjHvLpQ7bEsi2Jb6LdHKnQxaN"
    }
  ]
}

Add a new VC template

POST /issuer-api/{tenantId}/config/templates/{templateId}

curl -X 'POST' \
  'http://0.0.0.0:8080/issuer-api/default/config/templates/CrudeProductCredential' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d 'SEE EXAMPLE BODY'

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1"
    ],
    "id": "http://neo-flow.com/credentials/3a185b8f-078a-4646-8343-76a45c2856a5",
    "type": [
        "VerifiableCredential",
        "CrudeProductCredential"
    ],
    "name": "Heavy Sour Dilbit",
    "description": "Crude oil stream, produced from diluted bitumen.",
    "issuer": "did:v1:test:nym:z6MkmbrHuhkzwWYeJjkBhTYktabXR22ECzk1WrHJPW69EsJY",
    "issuanceDate": "2020-04-09T21:12:12Z",
    "credentialSubject": {
        "producer": "did:v1:test:nym:z6MkfG5HTrBXzsAP8AbayNpG3ZaoyM4PCqNPrdWQRSpHDV6J",
        "category": "Western Canadian Select",
        "hsCode": "270900",
        "identifier": "3a185b8f-078a-4646-8343-76a45c2856a5",
        "name": "Heavy Sour Dilbit",
        "description": "Crude oil stream, produced from diluted bitumen.",
        "volume": "10000",
        "address": {
            "address": "Edmonton, CAN",
            "latitude": "53.5461",
            "longitude": "113.4938"
        },
        "productionDate": "2020-03-30T07:23:14.206Z",
        "predecessorOf": "c98f2452-ab18-4cbe-bf89-635fb8ae7f33",
        "successorOf": "",
        "physicalSpecs": {
            "uom": "barrel",
            "minimumQuantity": "1000",
            "apiGravity": 21,
            "viscosityAt10C": "302",
            "viscosityAt20C": "157",
            "viscosityAt30C": "89.6",
            "viscosityAt40C": "55.3",
            "viscosityAt45C": "44.4",
            "pourPoint": "-30",
            "vapourPressure": "51.7",
            "density": "928",
            "naphtha": "",
            "distillateAt350To650F": "",
            "gasOilAt650To980F": "",
            "residAt980F": "41",
            "deemedButane": "1.9",
            "tan": "1.05",
            "ron": "",
            "mon": "",
            "boilingPoint": "",
            "freezingPoint": "",
            "criticalTemperature": "",
            "criticalPressure": "",
            "autoIgnitionTemperatureInAirAt1atm": "",
            "solubilityInTrichloroethylene": "",
            "penetrationAt25C100g5sec": "",
            "softeningPoint": "",
            "ductilityAt25C": "",
            "olefin": "",
            "color": "",
            "odor": "",
            "grossCalorificValueAt15C": "",
            "netCalorificValueAt15C": "",
            "airRequiredForCombustion": "",
            "copperCorrosionAt38CFor1Hour": ""
        },
        "chemicalSpecs": {
            "microCarbonResidue": "9.68",
            "aromaticsTotalBTEX": "0.23",
            "sedimentAndWater": "188",
            "liquidPhaseH2S": "",
            "mercury": "",
            "oxygenates": "",
            "filterableSolids": "",
            "phosphorousVolatile": "",
            "mediumChainTriglycerides": "",
            "benzene": "",
            "particulates": "",
            "organicChlorides": "",
            "nickel": "54",
            "vanadium": "132.5",
            "water": "",
            "molecularWeight": "",
            "sulphur": "3.66",
            "naphthenes": "",
            "chloride": "",
            "arsenic": "",
            "lead": "",
            "ethene": "",
            "propane": "",
            "isoButane": "",
            "nButane": "",
            "hydrocarbonsHeavier": "",
            "unsaturatedHydrocarbons": ""
        }
    },
    "proof": {
        "type": "Ed25519Signature2018",
        "created": "2020-04-09T21:12:28Z",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..VOFp3CC42FvRBqpTNVABY0DX4TqmLrkjG20K0Zl0JtfOU28EcUkndTQm1n9NPDyh3r4XXw0l7i-hxlViCjkTCw",
        "proofPurpose": "assertionMethod",
        "verificationMethod": "did:v1:test:nym:z6MkmbrHuhkzwWYeJjkBhTYktabXR22ECzk1WrHJPW69EsJY#z6Mkmh3mQN5VNM6yXksw19kiBHLNud8vXSfHE84xtanMchbA"
    }
}

Remove the VC template

/issuer-api/{tenantId}/config/templates/{templateId}

curl -X 'DELETE' \
'https://wallet.walt-test.cloud/issuer-api/default/config/templates/CrudeProductCredential' \
-H 'accept: text/plain'

Issuer Portal

• Issuer web portal

  • Web based user interface for issuing credentials to the web wallet

• Wallet configuration

  • Possibility to configure list of supported wallets (defaults to walt.id web wallet)

• Credential issuance

  • Support for issuing verifiable credentials to the web wallet, based on OIDC for credential issuance specification

Verifier Portal

• Verifier web portal

  • Web based user interface for requesting credential presentations through the web wallet

• Wallet configuration

  • Possibility to configure list of supported wallets (defaults to walt.id web wallet)

• Presentation exchange

  • Support for presentation exchange based on OIDC for verifiable presentations (SIOP) specification

The wallet backend provides a simple command line interface, to run and/or configure the backend, including the issuer and verifier backends.

Installation & Running the Project

Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine

git clone https://github.com/walt-id/waltid-walletkit.git

cd waltid-walletkit

docker build --rm -t waltid/walletkit .

alias waltid-walletkit="docker run -p 8080:8080 -e WALTID_DATA_ROOT=/data -v $PWD:/data waltid/walletkit"

waltid-walletkit run

docker run -p 8080:8080 -e WALTID_DATA_ROOT=/data -v $PWD:/data waltid/walletkit run

git clone https://github.com/walt-id/waltid-walletkit.git

cd waltid-walletkit

./gradlew build install

alias waltid-walletkit="build/install/waltid-walletkit/bin/waltid-walletkit"

waltid-walletkit run

build/install/waltid-walletkit/bin/waltid-walletkit run

More options how to build the project can be found here.

Configuration

For configuring keys and DIDs (especially for the Issuer or Verifier backends), the wallet backend integrates some commands from the SSI Kit for key and DID management.

The config command lets you define the context in which you want to execute the command, by specifying the arguments --as-issuer, --as-verifier or --as-user [userID] or their shortcuts -i, -v, -u [userID], before the respective subcommand.

E.g.

waltid-walletkit config --as-issuer did list

This command lists the DIDs available in the context of the issuer backend.

For more details about the integrated commands, you may want to refer to the documentation of the SSI Kit, which you find here:

Here are the most important things to know about the Wallet Kit:

• It is open source (Apache 2). You can use the code for free and without limitations.

• It is an out-of-the-box solution that you can simply re-use or even white-label such as for building pilot projects quickly.

• It is customisable in a sense that you can individualise the app based on your requirements: You can rebrand the app, build your own UI and add new features. ****

• It is composable in a sense that you can plug your existing (d)apps into the wallet backend in order to supercharge your (d)apps with SSI capabilities.

• It abstracts complexity such as low-level functionality related to key handling, data storage, signing and interactions with third party systems.

• It is built on open standards to ensure interoperability and prevent lock-in effects.

• It is flexible in a sense that you can deploy and run wallets on-premise, in your (multi) cloud environment or directly integrate our libraries.

• It enables you to use different identity ecosystems like Europe’s emerging identity ecosystem (EBSI, ESSIF) in anticipation of a multi-ecosystem future. (Consult the to find out which ecosystems the Wallet Kit supports.)

Like the wallet-backend, the issuer and verifier portals are built on top of the SSI Kit, to leverage its functionality for issuing, signing and verifying credentials, provided by the Signatory and Auditor components resepectively.

Since the issuer and verifier backends are currently integrated with the wallet-backend project, refer to the Architecture section for details.

To save you the roundtrip, in case you ended up on this page, here's the architecture diagram once more:

The Issuer and Verifier Portals are demo web portals showcasing the scenarios of getting verifiable credentials issued into the wallet by a certified issuer or presenting a credential to a relying party. They can be used as reference implementations for issuers and verifiers to implement their own service platforms.

For credential and presentation exchange, we make use of the OIDC/SIOP protocols described in OIDC.

There are 3 ways to integrate the verification flows into your application:

1. Same-device (web-based) flow

2. Cross-device flow (with QR code)

3. Via webhooks (callback)

In all cases, first make sure you have your tenant configured with all the verification policies, etc. that fit your requirements.

Then start the presentation flow, using the methods described below.

Same device flow

GET /verifier-api/<tenantId>/present?walletId=walt.id&vcType=VerifiableId

Supported parameters:

In the same-device flow the browser gets navigated to this API URL, with the given parameters

The walletkit redirects to the wallet and on completion, the walletkit redirects the browser back to the application.

Example flow

Navigate the browser to:

https://wallet.walt-test.cloud/verifier-api/default/present?walletId=walt.id&vcType=VerifiableId&vcType=Europass&verifierUiUrl=https://myservice.example.com/callback/

The browser will be redirected to the wallet. The user will be presented the presentation request and asked to confirm it.

Eventually the browser will be redirected back to the application like this:

https://myservice.example.com/callback/success/?access_token=abc123

Note the subpath /success/ being added to the verifierUiUrl!

Cross device flow

GET /verifier-api/{tenantId}/presentXDevice

Supported parameters:

For starting a cross-device presentation flow, call this API with the required parameters to create a presentation request.

As a response, you get an object containing a requestId and a url.

Your application should now render the url from the response object as a QR code, or deep-link.

Cross-device verification request status

GET /verifier-api/{tenantId}/verify/isVerified

Supported parameters:

This API will return a status 404 Not found, while it is waiting for the cross-device request to be fulfilled.

When the request is fulfilled, it will return a status 200 OK with the redirection URL in the response body.

Verification result

GET /verifier-api/<tenantID>/auth?access_token=abc123

Parameters

Verification callbacks

As seen in the first example, you can optionally set a callback:

https://wallet.walt-test.cloud/verifier-api/default/present?walletId=walt.id&vcType=VerifiableId&verificationCallbackUrl=http://wallet.local:5555/callback/5dd9f971-9cd2-4c41-a40f-5340ac6d1fd3 (Note &verificationCallbackUrl=)

When setting a callback, the Wallet Kit will then call this callback as webhook when the user shares a credential (in the walt.id demo wallet: actually clicks "Share credentials").

Before answering the user, the Wallet Kit will send out an HTTP Post request using the parameters described below.

• When the callback answers HTTP statuses

  • Statuses:

    • OK (200),

    • NoContent (201),

    • or Accepted (202)

  • the Wallet Kit will mark the callback as accepted and continue its normal operation.

• When the callback answers HTTP statuses

  • Statuses:

    • MovedPermanently (301),

    • Found (302),

    • TemporaryRedirect (307),

    • or PermanentRedirect (308)

  • the Wallet Kit will abort its operation and redirect the user (using the Location header) to the Location specified by the callback.

  • This is useful for redirecting to pages based on what credentials the user shares or change depending on the data of the credentials.

• When the callback answers HTTP statuses

  • Statuses:

    • Unauthorized (401),

    • or Forbidden (403)

  • the Wallet Kit will invalidate the status and set overallValid to false, even if the selected VerificationPolicys would result in an overallValid = true.

Callback data to work with

When you set up your webhook to listen for such a Wallet Kit callback, you have a variety of data to work with:

• state: (UUID) ID of the verification session

• subject: (DID) DID of the user that created the shared presentation

• auth_token: (JWT[Subject]) Signed representation of subject = DID

• vps: (List[VPVerificationResult])

  • VPVerificationResult:

    • vp: (JWT) Signed representation of the Verifiable Presentation

      • Including DIDs, issuance dates (attribute iat, nbf), etc...

      • and obviously the actual Verifiable Credential (in attribute vc)

    • vcs: (List[JWT])

      • Signed Verifiable Credentials sourced from the Verifiable Presentation (VC in attribute vc, issuance date iat nbf, Subject DID sub, ...)

    • verification_result: (VerificationResult)

      • valid: Boolean

        • overall valid state

      • policyResults: Map[Policy -> Boolean]

        • e.g. policyResults={SignaturePolicy=true, ChallengePolicy=true, PresentationDefinitionPolicy=true}

Example JSON body you'll receive with a webhook callback for the VerifiableID demo

(Empty values that are not set [= null] are omitted for this example, e.g. no expirationDate was set, thus you'll receive "expirationDate": null)

Demo showing an identity/SSI use case from a person’s (Holder’s) perspective.

Test the Wallet

1. Visit the .

2. Create an account or log into an existing account.

3. Request VCs directly from the wallet by (1) clicking the “Request Credentials” button (2) choosing the “Issuer Portal” (3) selecting a credential type.

4. Claim the VC from the Issuer Portal.

5. Accept the VC.

6. Present the VC to a .

You can also experience an end-to-end use case demo by using the“” (incl. issue and verify VCs).

Each project can be easily built using docker:

Now, launch the containers using the described in the previous section, which also sets up the necessary API mappings for the web frontends to find the API endpoints.

We operate the following as public services for demo and trial purposes only:

• Web wallet

• Verifier portal

• Issuer portals

Stable deployment

The stable deployment is updated manually whenever a stable release build is ready:

• Web wallet:

• Issuer portal:

• Verifier portal:

Rolling deployment

A deployment of the bleeding edge developments is updated in a rolling fashion on every successful build of the master branch of the wallet backend project.

This deployment should not be considered stable and should not be used for demo purposes, unless you want to try out a bleeding edge feature, that is not yet available in the stable deployment.

The rolling deployment is available for demo and trial at:

• Web wallet:

• Issuer portal:

• Verifier portal:

User authentication

To authenticate with the stable or rolling deployments use any email address and password. Your data will be kept separate based on the email address, however, no password protection is enabled on these services.

Issuance is very simple, in fact, you only need to call a single HTTP POST endpoint:

Issue Credential

POST /issuer-api/{tenantId}/credentials/issuance/request

Using our prebuild frontend applications for the different parties (holder, verifier, issuer), you can easily offer a full-fledged solution to your customers and clients by connecting them to the .

Solutions

• - The frontend solution for holders

• - The frontend solution for verifiers

• - The frontend solution for issuers

Clone source

In order to build the Wallet Kit ("wallet backend") or one of the affiliated projects, you have to clone the project source on your local machine, e.g.:

Wallet Backend (wallet-backend)

For building the project JDK 16+ is required.

For importing, building and running the project in your Kotlin/Java IDE, refer to your IDE documentation.

For a plain Gradle build, independent of your IDE, simply execute:

Web Wallet (waltid-web-wallet)

For building the project NodeJs v14+ and Yarn 1.22+ is required.

In the nuxt configuration in nuxt.config.js, you may want to adjust the API proxy mappings, which by default point to either our rolling public deployment or localhost:

Uncomment or adjust to your needs:

Build and run the project using:

The service is started on port 3000 by default.

For production build and other build options, follow the instructions in the README.md of the project.

Issuer Portal (waltid-issuer-portal)

For building the project NodeJs v14+ and Yarn 1.22+ is required.

In the nuxt configuration in nuxt.config.js, you may want to adjust the API proxy mappings, which by default point to either our rolling public deployment or localhost:

Uncomment or adjust to your needs:

Build and run the project using:

The service is started on port 8000 by default.

For production build and other build options, follow the instructions in the README.md of the project.

Verifier Portal (waltid-verifier-portal)

For building the project NodeJs v14+ and Yarn 1.22+ is required.

In the nuxt configuration in nuxt.config.js, you may want to adjust the API proxy mappings, which by default point to either our rolling public deployment or localhost:

Uncomment or adjust to your needs:

Build and run the project using:

The service is started on port 4000 by default.

For production build and other build options, follow the instructions in the README.md of the project.

To setup the issuer portal backend a few things may need to be considered and some configuration may be required, depending on your situation.

Data root

Since the issuer portal backend is implemented in the same service as the wallet backend, refer to the wallet backend setup section for .

Issuer portal backend configuration

The configuration of the issuer portal backend can be adapted, by modifying the file

config/issuer-config.json

External URLs

Configure the URLs via which the issuer portal UI and backend API will be reachable from an external source, e.g. a web browser, or the wallet backend requesting credential issuance:

Issuer DID

Configure the DID used to sign issued credentials. Refer to for options to initialize a DID for the backend.

By default, the issuer backend will choose the first available DID in its data store. To enforce, which DID to use, set it in the issuer-config.json like so:

Known wallets

The issuer portal supports an issuance flow, that is triggered directly from the issuer portal into the SSI wallet. To support this kind of issuance flow, you need to configure the known wallets and how to connect to them:

This example shows the known wallet configuration for the walt.id web wallet, in issuer-config.json:

Configuration example

Here's a complete example for the issuer-config.json:

Issuer portal backend data storage

Data, such as dids and keys, are currently stored in the issuer subfolder, like so:

<data_root>/data/issuer

In the future various options to configure the issuer data storage may be provided.

Binding address and port

Initializing issuer portal backend

To set up an issuer portal backend, it is crucial to define the DID by which issued credentials should be signed.

The wallet backend intergrates a subset of commands from the walt.id SSI Kit, to accomplish simple key and DID management.

To manage keys and dids for the issuer, use the config command, with the command flag --as-issuer, or its shortcut -i:

The following examples show typical use cases and scenarios of setting up an issuer backend for various ecosystems.

EBSI/ESSIF anchored issuer DID

Create a new _Secp256k1_** key**

Sample output

Create a new _did:ebsi_

Sample output

Register the DID on the EBSI blockchain

Set the _issuerDid_** config property**

issuer-config.json

DNS/Web anchored issuer DID

Create a new _did:web_

Run the following command, replacing the _domain** (-d) and **path_** (-p) arguments**, matching your web server on which you can publish the did document:

Observe the command output:

Publish the DID document on the web server

Copy the DID document from the above command output, and publish it on your web server, on the path printed by that same command.

The DID document in this example should be resolvable from this URL:

https://walt.id/.well-known/my-issuer/did.json

The domain and path will be different in your case.

Set the _issuerDid_** config property**

issuer-config.json

Importing an external DID and key

If you want to use an existing DID, that you own, for issuance, you can import it, given that you have access to the associated private key and DID document. If the DID is resolvable through the standard mechanism of the given DID method, only the private key is required.

The private key should be available in JWK or PEM format.

Import private key from JWK file

In this example, we import a private key from the file priv.jwk:

Output

Now we can import the DID, either by importing the DID document from a local JSON file, OR by resolving it from a public registry or likewise, depending on the DID method.

Option 1: Resolve and import DID

In this example, we import a did:key, for which the DID document can be derived without external DID registry, and associate it with the previously imported key ID:

Option 2: Import DID document

In case, the DID document cannot be resolved or derived, we can also import the DID document from a local JSON file:

The relevant output for both import options, will look similar to this:

Output

Set the _issuerDid_** config property**

issuer-config.json

The Wallet Kit supports credential issuance and presentation exchange via the OpenID Connect (OIDC) standards:

On the following pages you can find sequence diagrams of the integrated end-to-end flows.

To setup the verifier portal backend a few things may need to be considered and some configuration may be required, depending on your situation.

Data root

Since the verifier portal backend is implemented in the same service as the wallet backend, refer to the wallet backend setup section for .

Verifier portal backend configuration

The configuration of the verifier portal backend can be adapted, by modifying the file

config/verifier-config.json

External URLs

Configure the URLs via which the verifier portal UI and backend API will be reachable from an external source, e.g. a web browser, or the wallet backend responding to a credential presentation request:

Known wallets

The verifier portal supports the OIDC/SIOPv2 credential presentation flow, that is triggered directly from the verifier portal requesting credentials from an SSI wallet. To support this kind of verification flow, you need to configure the known wallets and how to connect to them:

This example shows the known wallet configuration for the walt.id web wallet, in verifier-config.json:

Verification policies

By default, the verifier backend will apply some basic verification policies to the verifiable presentations and credentials, presented by the wallet. The default verification policies are:

• SignaturePolicy

  • checks the signature of the credential

• ChallengePolicy

  • verifies that the presentation was signed against the challenge requested by the verifier backend

• VpTokenClaimPolicy

  • verifies that the SIOP response (presentation from the wallet) matches the vp_token claim

In order to enforce other policies to be executed on the presented credentials, you can use the additionalPolicies property in the verifier configuration.

This also allows for configuring custom dynamic policies, and supports specification of policy arguments.

The verifier backend supports the verification policy management commands provided by the SSI Kit, using the following CLI subcommand:

This example shows the configuration of additional policies in verifier-config.json:

Configuration example

Here's a complete example for the verifier-config.json:

Verifier portal backend data storage

Data, such as dids and keys, are currently stored in the verifier subfolder, like so:

<data_root>/data/verifier

In the future various options to configure the verifier data storage may be provided.

Binding address and port

Getting Started

Depending on your preference, start exploring with the deep dive or a tutorial.

Deep dive

- See how IOTA was integrated into the SSI-Kit. The Wallet-Kit uses the SSI-Kit internally; therefore, we get all the functionality with the Wallet-Kit + more for easier integration with any app.

- Learn more about the OIDC4VP profile used for Login with IOTA

Tutorials

- Learn how to configure the wallet kit + other needed frontend projects to build a Login With IOTA use-case

Demo

The verification flow is started from the Verifier web portal. The Verifier requires a certain type of credential to be presented, and lets the user connect to a previously configured, known Wallet. The Wallet, receiving the SIOP authorization request, can check if all required credentials are available, and optionally trigger a credential issuance flow for possibly missing credentials. If all required credentials are available the user selects the credentials to present (if multiple credentials of the same type are available) and the Wallet generates the SIOP response, containing an id token and the verifiable presentation, and redirects back the verifier portal for verification:

To setup the wallet backend a few things may need to be considered and some configuration may be required, depending on your situation.

Data root

Configuration and data are kept in sub folders of the data root (by default the current working directory):

• config/

• data/

To override the data root, one can set the environment variable:

WALTID_DATA_ROOT

Wallet backend configuration

The configuration of the wallet backend can be adapted, by modifying the file

config/wallet-config.json

External URLs

Configure the URLs via which the wallet UI and API will be reachable from an external source, e.g. a web browser, or a verifier service requesting a presentation exchange:

OIDC Issuers

To enable OIDC credential issuance from within the wallet, you need to configure where the wallet finds the issuer APIs and possibly how to authenticate with the OIDC service.

For each known issuer configure a unique id, a description and the OIDC base URL. From this base URL, the wallet will try to resolve the OIDC discovery document at <base-url>/.well-known/openid-configuration.

Secrets

If you need to authenticate with the OIDC issuer service, you can configure the client_id and client_secret in two ways:

1. In wallet-config.json

1. In a separate file

To keep the secrets separated from the main config, you can keep them in a separate file, relative to the data root:

secrets/issuers.json

You can make use of this separate secrets file, e.g. in a Kubernetes or Docker Swarm deployment, to keep the passwords in a safe secret object. Also, it enables you to separate the secrets from the default configuration, which you may want to check in to version control.

Configuration example

Here's a complete example for the wallet-config.json:

Wallet backend data storage

User data (dids, keys, credentials) are currently stored in subfolders for the user id, like so:

<data_root>/data/<user@email.com>

It is planned to allow users to define their own storage preferences, in the future.

Binding address and port

By default, the wallet backend exposes its API endpoints bound to localhost, port 8080.

To override the default bindings, set the following environment variables:

WALTID_WALLET_BACKEND_BIND_ADDRESS

WALTID_WALLET_BACKEND_PORT

Command arguments

To set binding address and port, you can also use the command arguments of the run command like so:

To set the bind address to "192.168.0.1" and the port to 8081:

To bind to all interfaces (on the default port):

In this tutorial, you will learn how to configure the wallet kit + other needed frontend projects to build a Login With IOTA use-case. The tutorial is divided into two sections. First, we will set up and configure the backend handling the business logic, followed by the frontend projects which are provided for an easy and fast lauch.

Setting up the backend

Cloning the Wallet-Kit

Make sure you have Docker installed on your machine

Create the IOTA policy

To make sure only Verifiable Credentials with a "did:iota" can pass the verification (login), we will create a policy and use it in our verifier configuration.

IOTA policy

Registering the policy

The Wallet-Kit has multi tenant support, which means multiple customers, or tenants, can use a single instance of the wallet-kit, with each tenant having their own data and configurations isolated from others. And we will now create + use our IOTA tenant to register the policy

Create the IOTA Tenant + configuration

The Wallet-Kit has multi tenant support, which means multiple customers, or tenants, can use a single instance of the wallet-kit, with each tenant having their own data and configurations isolated from others. And we will now create our IOTA tenant to handle all IOTA related operations.

First, we get the configuration of the default tenant and use it as a baseline for the configuration of our IOTA tenant.

Using the response, we just got from the default tenant configuration, we will update additionalPolicies as well as the verifierApiUrl as follows:

Let's now set the above configuration object as the configuration for our IOTA tenant.

Setting up the frontend

To have the fully working Login With IOTA Demo up and running, we need three more projects:

1. The Waltid-Wallet - To create an IOTA DID and get a Verifiable Credential based on an IOTA DID issued

2. The Waltid-Issuer-Portal - The application responsible for issuing a Verifiable Credential to the DID IOTA holder (Wallet)

3. The Waltid-Verifier-Portal - The application in which the holder will log in to using a Verifiable Credential based on a DID IOTA

Wallet

Make sure you have node.js installed on your machine

Issuer Portal

Verifier Portal

Let's log in with IOTA

Now that we have the backend and all frontend applications up and running, we can start the Login with IOTA flow.

All our products are open source under the permissive **** license. This means:

• You can use, modify and distribute our products for free and without strings attached.

• You can use our products to build pilots or even production systems.

• You can deploy, run and manage our products on-premise or in your own cloud environments.

if you are using our products. We are curious to learn about your experience and happy to spread the word about your project via our newsletter or case studies.

All our products are open source under the permissive **** license. This means:

• You can use, modify and distribute our products for free and without strings attached.

• You can use our products to build pilots or even production systems.

• You can deploy, run and manage our products on-premise or in your own cloud environments.

To complement our free products, we offer services for clients who want to manage our products by themselves:

• Consulting

• Custom development and integration

• Support / SLAs

if you want to learn more.

The web wallet supports a custom issuance flow, that can be triggered from the issuer portal and makes use of the OIDC for verifiable presentations (SIOP) flow, to commute between issuer portal and wallet. The user starts at the issuer portal and selects the credentials they want to get issued. The issuer portal redirects to a, previously configured, known wallet, using the SIOP flow outlined above. The wallet creates the SIOP response, posts it to the issuer portal, and in return receives the issued credentials, given that the credential presentation was verified successfully:

Wallet backend standalone

If you are working on one of the web frontends (e.g. web-wallet, issuer-portal, verifier-portal), you may want to run the wallet backend container standalone, to connect your local web frontend build with it.

Edit the configuration files in waltid-walletkit/config, according to your needs and run the container like so:

Note: Running the web frontend containers standalone, makes little sense, as they depend on an API gateway to connect to the backend APIs. This API gateway is set up by the docker-compose configuration, mentioned above.

Docker Compose

The easiest and fastest way to get the wallet backend, frontend, and issuer and verifier portals started, is by using our docker-compose configuration, located in the project, in the subfolder:

./docker/.

Simply start the services using:

This configuration will publish the following endpoints by default:

• Web wallet on [HOSTNAME]:8080

  • API: /api/

• Verifier portal on [HOSTNAME]:8081

  • API: /verifier-api/

• Issuer portal on [HOSTNAME]:8082

  • API: /issuer-api/

Note: __ [HOSTNAME] is your local computer name. If you use localhost instead, some features, particularly with regards to credential exchange, will not work correctly.

In case the HOSTNAME is not picked up automatically, you might need to set it in an env-file and refer to it by: docker-compose --env-file env-file-with-hostname up.

Visit the ./docker folder for adjusting the system config in the following files:

• docker-compose.yaml - Docker config for launching containers, volumes & networking

• ingress.conf - Routing config

• config/wallet-config.json - wallet backend configuration

• config/verifier-config.json - verifier backend configuration

• config/issuer-config.json - issuer backend configuration

The issuance flow is triggered from the Wallet. The user chooses from a list of issuer portals known to the wallet backend, and triggers the issuance of any credential type the issuers support. Optionally, the Issuer can require a Verifiable Presentation of certain types of credentials, to be sent with the initial authorization request. If the authorization is successful, the issuer portal provides an authorization code and access token, for the wallet to retrieve the issued credentials: