Engineering

What is 3ID Connect?

3ID Connect is an authentication system that allows users to use blockchain wallets to interact with browser-based Ceramic apps.

0xPottery

25 Nov 2020 • 11 min read

Ceramic is a decentralized content management network where all content is stored in streams and all transactions on these streams must be signed by the decentralized identifier (DID) of the stream owner(s).

3ID Connect is a hosted authentication system for browser-based Ceramic applications that allows users to onboard to applications, control their DID, and interact with Ceramic streams using their existing blockchain accounts. Try a demo of 3ID Connect here.

You might consider using 3ID Connect in your application if:

You're building a browser application that uses Ceramic
Your users already have a blockchain wallet
Other features of your app use a blockchain and you want your users to use the same wallet to interact with DIDs
You don't want to be bothered with DID key management
You don't want your users to be bothered with DID key management

This post provides a technical overview of the 3ID Connect system, and is the first part of a three-part series on 3ID Connect. Other posts:

What is a DID?

DIDs is the W3C standard for globally-unique, persistent decentralized identifiers. These identifiers have an associated DID document which contains public keys used for signature verification and encryption. There are currently more than 60+ implementations of DIDs, called methods. The primary DID method for end-user accounts on Ceramic is called 3ID.

DID Providers

DID providers are lightweight libraries that implement the standard EIP-2844 interface for a particular DID method. DID providers allow for creating DIDs, signing data, verifying data, encrypting data, and decrypting data. A DID provider needs to have a currently authenticated DID, then be passed to a Ceramic instance in order to allow the user to perform transactions on Ceramic. 3id-did-provider provides this interface for the 3ID DID method.

Key Management

Like any other asymmetric cryptographic account, DIDs have a public identifier that is controlled by a private seed (pneumonic/private key). Therefore, building applications with Ceramic functionality requires that this DID seed is managed and protected in a secure way. When a 3ID DID is created using the raw 3id-did-provider interface, it is up to the wallet or application developer to decide how to manage this seed.

This flexibility in DID key management is desirable considering the many different runtime environments where you might want to build a Ceramic application. For example in a React Native application, you might want to use the device's local storage to store a 3ID seed. Alternatively, you might want to implement your application using a custodial key management solution so users don't need to worry about keys at all.

3ID Connect: A hosted 3ID wallet for browser apps

3ID Connect is a secure DID wallet purpose-built for Ceramic browser applications which offers all the 3id-did-provider interfaces, but wraps them in a novel solution to key management and authentication using one or more blockchain wallets that your users already have. By using 3ID Connect, neither users nor developers need to worry about managing DID keys and instead users can rely on the key management of their blockchain wallet(s) to protect their DID seed.

During the process of onboarding to an application, 3ID Connect makes it seamless for users to create a 3ID, permission one or more blockchain accounts to authenticate/control their 3ID, and grant applications permissions to utilize their DID in various ways using signatures provided by this blockchain account. Instead of needing to provide the raw 3id-did-provider to your application's Ceramic node in order to transact with the user's Ceramic streams, you can simply pass 3ID Connect as the user's DID provider.

This multi-account-to-one-DID model provides resilience against identity loss while offering additional security benefits. When more than one blockchain account is connected to a single DID, the only way a user could ever lose control of their DID is if they simultaneously lose control of all of their blockchain keys. This type of catastrophic key loss scenario is highly unlikely and improves security by delegating and distributing DID key management to all of a user's blockchain wallets. Additionally since each blockchain account is considered an equal "owner" of the DID, any account can remove any other account at any time. This allows a user to deprovision an account in the case that particular wallet account is compromised or lost, without losing their DID.

3ID Connect also provides many other benefits:

Intuitive data consent management screens let users know which permissions they're giving to the application
Simplified user onboarding flow removes DID creation and key management friction, and remembers which permissions a user has given to an application on future visits so they don't need to sign unnecessary messages each time
Users can publicly link their blockchain accounts to their DID, which allows data associated to the DID (such as linked profiles, social graphs, verified social accounts, other blockchain accounts, application data, etc.) to be resolved by simply looking up the blockchain account

How it works

Architecture

3ID Connect is a hosted 3ID account management application that runs in an iFrame window alongside any applications which have installed the 3ID Connect library in their app. The 3ID Connect library communicates with the iFrame application over an RPC interface. It implements RPC calls to support functionality in 3ID Connect and most importantly relays any DID provider calls from the application to the 3id-did-provider instance running in the iFrame.

The iFrame application uses 3id-did-provider , js-ceramic, and js-idx in combination to support all keychain and identity management operations. It also connects to a community Ceramic node managed by the 3Box Labs team, to persist all 3ID and IDX related Ceramic streams. The 3ID Connect application is hosted on AWS under the app.3idconnect.org domain.

Key Management System

3ID Connect uses Ceramic, the 3ID DID provider, the IDX identity protocol, and blockchain wallets to manage the DID's seed and authentication data in a secure, decentralized manner. The various components of this system are outlined below.

3ID DID Method: An implementation of decentralized identifiers (DIDs) stored on Ceramic. 3ID Connect uses 3IDs as end-user identities.

3id-did-provider: A DID provider interface for the 3ID DID method.

js-ceramic: A node that implements the full Ceramic protocol. 3ID Connect connects to this node over an HTTP API and uses it to store 3IDs, as well as other documents described below.

js-idx: A JavaScript/TypeScript library which implements the IDX decentralized identity protocol for keeping track of data associated with a DID in a decentralized manner.

IDX Index: A key-value store document which contains an index of a DID's personal information. This document is stored on Ceramic as a TileDocument stream and a reference to it is included in the DID document of the 3ID DID.

3ID Keychain: A document which stores copies of the DID's seed encrypted to their various authentication methods. This document is stored on Ceramic as a TileDocument stream and a reference to it is included in the DID's IDX Index. When a user authenticates with a blockchain account in 3ID Connect, this DID seed is decrypted inside the iFrame.

Crypto Accounts document: A document which stores a list of blockchain accounts that are publicly linked to a DID, along with their CAIP-10 Link proofs. This document is stored on Ceramic as a TileDocument stream and a reference to it is included in the DID's IDX Index.

CAIP-10 Link: A Ceramic stream which acts as a proof that publicly binds a blockchain account to a DID. A reference to this stream is included in the DID's Crypto Accounts document.

iFrame localStorage: A local store which stores a decrypted copy of the DID's seed (which permanently resides inside the 3ID Keychain) under the 3ID Connect domain, and permissions granted to each application under each application's domain. These secrets are stored in the iFrame for convenience and user experience. Even if all data is lost from the iFrame it can always be resynced from the 3ID Keychain, using the path 3ID > IDX Index > 3ID Keychain.

Blockchain wallets: Key management and signing solutions for accounts on blockchain networks. These providers are used for user authentication and permissions management in the 3ID Connect system. They are used to sign messages, and encrypt and decrypt the DID's seed which is then stored in the 3ID Keychain. 3ID Connect currently supports Ethereum wallets, but any blockchain that supports deterministic signatures can easily be added. See this tutorial to learn how to add support for accounts from a new blockchain in 3ID Connect.

3ID Connect User Flows

In the next post, "How to use 3ID Connect in browser applications," we guide you through installing 3ID Connect in your application. In the section below, we walk through some of the most common user flows that your users can experience while using 3ID Connect within your application. These flows will shed light on how the various components of the key management and authentication system described above work together. Try a simple demo app that includes 3ID Connect here.

Users of your application will encounter one of a few 3ID Connect flows depending on: 1) whether or not they already have a 3ID linked to their blockchain account; and 2) whether or not they have previously used their 3ID with your application.

Here are the four different flows described in this section:

The blockchain account has a 3ID, and the 3ID has previously used this domain.
The blockchain account has a 3ID, but the 3ID has not yet used this domain.
The blockchain account does not have a 3ID, and the user wants to create a new 3ID.
The blockchain account does not have a 3ID, and the user wants to connect to an existing 3ID.

Some of the examples below show 3ID Connect being used with the MetaMask browser extension wallet on Ethereum, but any other wallet on any other blockchain would have a similar flow.

Onboarding Flow 1

The blockchain account has a 3ID, and the 3ID has previously used this domain.

If the user's blockchain account already has a DID, and if they have already provided your application's domain with the permissions that are being requested during a previous session, the user will automatically be authenticated into your application. No action will need to be taken on the user's part and they won't see any 3ID Connect windows. Because 3ID Connect had stored the keys and permissions in iFrame localStorage from a previous session, they will be used for this session and all future sessions.

Onboarding Flow 2

The blockchain account has a 3ID, but the 3ID has not yet used this domain.

The 3ID Connect permissions screen will appear in the corner of your browser window.

If the user's blockchain account is already connected to a 3ID (likely from using 3ID Connect in a separate application) but they have not yet provided your application with the permissions that you're requesting, then the user will see a 3ID Connect permissions window. After clicking "Continue", the user will be authenticated.

Onboarding Flow 3

The blockchain account does not have a 3ID, and the user wants to create a new 3ID.

If the user's blockchain account does not have a 3ID, they will be prompted with a 3ID Connect new account window which provides them with the option to "Create new 3ID" or "Link existing". If the user clicks "Create new", behind the scenes 3ID Connect will perform a series of actions to initialize a new 3ID and connect their blockchain account to it.

First, 3ID Connect creates a new 3ID enabled with IDX.

Create a new 3ID DID on Ceramic
Create a new IDX Index on Ceramic
Create a new 3ID Keychain on Ceramic
Create a new Crypto Accounts document on Ceramic
Store the StreamID of the IDX Index inside the 3ID
Store the StreamID of the 3ID Keychain inside the IDX Index
Store the StreamID of the Crypto Accounts document inside the IDX Index

Next, 3ID Connect adds the blockchain account as an authentication method for the 3ID.

The user is prompted to sign a message with their blockchain account that says: Add this account as a Ceramic authentication method (see above). From the resulting signature, an encryption key is deterministically derived. Because determinism is used to derive the encryption key from the signature, the user is always able to regenerate this encryption key wherever they can sign the same message with this same blockchain account.
3ID Connect encrypts the seed of the DID with this derived encryption key (called an authMethod).
3ID Connect stores this encrypted seed in the 3ID Keychain document on Ceramic.

Lastly, 3ID Connect publicly links the blockchain account to the 3ID.

The user is prompted to sign a message with their blockchain account that includes their DID (see above). 3ID Connect then uses this signed payload to create a CAIP-10 Link which binds the blockchain account to the 3ID.
3ID Connect stores the StreamID of the CAIP-10 Link inside the DID's Crypto Accounts document.

After the user has completed the steps above, they will now have a new 3ID that can be controlled by a blockchain account. Upon completion, they will see the 3ID Connect permissions window. Once approved, the user will be authenticated.

Onboarding Flow 4

The blockchain account does not have a 3ID, and the user wants to connect to an existing 3ID.

If the user clicks "Link existing" instead of "Create new" when they see the 3ID Connect new account window, they will enter a flow where they connect their current blockchain account to an existing 3ID.

To accomplish this, 3ID Connect will redirect the user to an external domain where the user can: 1) see their other 3IDs currently managed in their 3ID Connect window; 2) search for 3IDs not currently in the 3ID Connect window; and 3) manage the account linking process. By default, 3ID Connect will redirect this flow to the domain of an 3ID identity management application (to be announced).

Behind the scenes, this flow will then execute the second and third steps outlined in Flow 3 to add the blockchain account as an authentication method for the 3ID, and publicly link the blockchain account to the 3ID.

Once the user has completed these steps, they will be redirected back to the original application domain and see the 3ID Connect permissions window. Once approved, the user will be authenticated.

Security Considerations

The current implementation of 3ID Connect makes a number of usability and security tradeoffs. The development team has a list of planned security improvements for the future, but here are a few things to be aware of with 3ID Connect as it's implemented today:

While the code is open source, the application is still hosted by 3Box Labs. In the future this could be hosted on IPFS and resolved through ENS or IPFS.
Key material is kept in iFrame local storage. While it is sandboxed and we restrict any third party JavaScript from running in the app, local storage is still vulnerable to known attacks.
Phishing attacks and/or malicious websites could impersonate 3ID Connect screens and/or have the user sign a message that allows that attacker to access their DID kept in the iFrame.

Questions?

Reach out in the Ceramic Discord.