Skip to main content

How it works

Intermediate
Concept

Overview​

Verifiable credentials (VCs) on ICP rely on Internet Identity (II), which provides distinct identities that preserve unlinkability for each dapp. A dapp utilizing verifiable credentials can’t ask for a user's credentials from the issuer of the verifiable credential directly. When a relying party wants to obtain a credential from an issuer, it must request it through an identity provider such as Internet Identity.

Internet Identity acts as a communication link between the relying party and issuer API, connecting with the issuer API and asking for the credentials for the user. After receiving the credentials, they are forwarded to the relying party.

Verifiable Credential Workflow

User's perspective​

From the user's perspective, the relying party opens a new window to allow the credential, which is closed when the flow finishes.

Verifiable Credential Workflow

Developer's perspective​

From the developer’s perspective, the interaction between dapps uses window messages and calls to canisters:

  1. The user accesses the relying party and starts the process to request credentials. This may be an action such as logging into a dapp or accessing a private service that requires authorization.

  2. The relying party starts the flow with Internet Identity (II):

    a. The relying party opens a new II window and waits for a window message.

    b. The frontend of II sends a window message to start the request process.

    c. The relying party replies with the credentials request and issuer data for the request.

  3. The II frontend calls the issuer canister to retrieve the consent message.

  4. The II frontend shows all the details to the user: the relying party, the consent message, and the issuer URL, then waits for the user action.

  5. The user decides whether to allow or revoke the action.

    a. If allowed, the II frontend requests the ID alias for the II backend.

  6. The II backend calculates an ID alias which is an opaque identifier to keep unlinkability between the issuer and the relying party.

  7. The II frontend requests the credential from the issuer.

  8. The issuer receives the request for the credential, validates the call from II, and replies with a verifiable presentation if the user fulfills the credential's requirements.

  9. The II frontend receives the credential from the issuer and forwards it to the relying party, closing the window.

  10. The relying party verifies the credentials.

Verifiable Credential Workflow

For more details, check out the specification in Internet Identity’s repository.

Test verifiable credentials​

There is a demo relying party deployed on ICP available for testing: https://l7rua-raaaa-aaaap-ahh6a-cai.icp0.io/.

You first need to login with an identity provider. To avoid using real users, it is recommended to use the staging instance of Internet Identity: https://fgte5-ciaaa-aaaad-aaatq-cai.ic0.app/.

There is a demo issuer deployed on ICP available for testing. It will issue any requested credential. Feel free to use it when testing the flow: qdiif-2iaaa-aaaap-ahjaq-cai.

Next steps​