Decentralized ID (DID) Tokens
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 givenclaim.claim: Unsigned data the user asserts. This should equal theproofafter 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
| Key | Description |
iat | Issued at timestamp (UTC in seconds). |
ext | Expiration timestamp (UTC in seconds). |
nbf | Not valid before timestamp (UTC in seconds). |
iss | Issuer (the signer, the "user"). This field is represented as a Decentralized Identifier populated with the user's Ethereum public key. |
sub | The "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. |
aud | Identifies the project space. This field is populated with the application's Magic entity ID. |
add | An 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! |
tid | Unique token identifier. |