DID Authentication — OASIS Docs

Overview

OASIS supports two authentication modes side-by-side:

Standard auth — username/email + password → JWT. Used by most OApps and the OPORTAL dev portal.
DID auth — cryptographic challenge/response using a W3C DID. Used for ONET node joining and advanced decentralised identity scenarios.

Both modes issue the same JWT token on success, so the rest of the API is identical regardless of which auth path was used.

Standard JWT Flow

Client calls POST /api/avatar/authenticate with credentials.
ONODE validates, returns jwtToken (7-day expiry).
Client includes Authorization: Bearer <token> on all subsequent requests.
On expiry, client re-authenticates. There is no refresh token — re-login is required.

⚠️

Store the token securely

In browser OApps, store the JWT in localStorage (acceptable for non-sensitive OApps) or in an HttpOnly cookie (preferred for high-security applications). Never expose it in URLs or logs.

DID Auth Flow

DID auth uses a nonce-based challenge/response pattern:

Client presents its DID to the ONODE.
ONODE looks up the DID document to find the verification method (public key).
ONODE generates a one-time nonce and returns it to the client.
Client signs the nonce with its private key and returns the signature.
ONODE verifies the signature against the DID document public key.
On success, ONODE issues a JWT for the associated avatar.

Nonce Store

DID auth nonces must be stored server-side to prevent replay attacks. OASIS supports two nonce store backends, configured in OASISDNA.json:

Store	Config value	Notes
In-memory	`Memory`	Default. Works on a single ONODE. Not suitable for multi-node deployments.
Redis	`Redis`	Required for ONET multi-node clusters. Set `RedisConnectionString` alongside.

ℹ️

ONET nodes require Redis

When an ONODE joins ONET with DID auth enabled, it must use the Redis nonce store. Using in-memory will cause nonce validation failures across node boundaries and generate a startup warning in the ONODE logs.

Enabling DID Auth

json — OASISDNA.json

{
  "OASISDNA": {
    "EnableDIDAuth": true,
    "NonceStoreType": "Redis",
    "RedisConnectionString": "localhost:6379"
  }
}

← Previous

Holons & Data Model

Karma System