Getting Started with Decentralized ID (DID) Tokens

Getting Started with Decentralized ID (DID) Tokens

#Overview

Decentralized ID (DID) tokens are used as cryptographically-generated proofs that are used to manage user access to your application's resource server.

By adapting W3C's Decentralized Identifiers (DID) protocol, the DID token created by the Magic client-side SDK (see getIdToken) leverages the Ethereum blockchain and elliptic curve cryptography to generate verifiable proofs of identity and authorization. These proofs are encoded in a lightweight, digital signature that can be shared between client and server to manage permissions, protect routes and resources, or authenticate users.

The DID token is encoded as a Base64 JSON string tuple representing [proof, claim]:

  • proof: A digital signature that proves the validity of the given claim.
  • claim: Unsigned data the user asserts. This should equal the proof after Elliptic Curve recovery.
Javascript
01const claim = JSON.stringify({ ... }); // Data representing the user's access
02const proof = sign(claim); // Sign data with Ethereum's `personal_sign` method
03const DIDToken = btoa(JSON.stringify([proof, claim]));

#Use Cases

  • Users have control over their own identity without relying on a central authority
  • DIDs can be used for secure authentication and authorization processes

#Usage

#Generating a DID Token (Pseudo-code)

Typescript
01// Construct the user's claim
02const claim = JSON.stringify({
03    iat: Math.floor(Date.now() / 1000),
04    ext: Math.floor(Date.now() / 1000) + lifespan,
05    iss: `did:ethr:${user_public_address}`,
06    sub: subject,
07    aud: audience,
08    nbf: Math.floor(Date.now() / 1000),
09    tid: uuid(),
10});
11
12// Sign the claim with the user's private key
13// (this way the claim is verifiable and impossible to forge).
14const proof = sign(claim);
15
16// Encode the DIDToken so it can be transported over HTTP.
17const DIDToken = btoa(JSON.stringify([proof, claim]));

#Token Specification

KeyDescription
iatIssued at timestamp (UTC in seconds).
extExpiration timestamp (UTC in seconds).
nbfNot valid before timestamp (UTC in seconds).
issIssuer (the signer, the "user"). This field is represented as a Decentralized Identifier populated with the user's Ethereum public key.
subThe "subject" of the request. This field is populated with the user's Magic entity ID. Note: this is separate from the user's Ethereum public key.
audIdentifies the project space. This field is populated with the application's Magic entity ID.
addAn encrypted signature of arbitrary, serialized data. The usage of this field is up to the developer and use-case dependent. It's handy for validating information passed between client and server. The raw data must already be known to the developer in order to recover the token!
tidUnique token identifier.

#Resources