Authentication

Overview

The Open Privacy Suite authenticates users through Privado ID zero-knowledge proofs with optional ProofOfHumanity (PoH) verification via Billions. Users prove their identity without revealing private keys, and can optionally link Ethereum addresses via EIP-191 signatures.

For SSO-based authentication using Microsoft Entra ID, see the Azure AD / SSO guide.

Architecture

Auth Flow

{
  "id": 1,
  "circuitId": "credentialAtomicQueryMTPV2",
  "query": {
    "allowedIssuers": ["did:polygonid:polygon:amoy:..."],
    "credentialSubject": { "isHuman": { "$eq": 1 } },
    "context": "https://raw.githubusercontent.com/0xPolygonID/tutorial-examples/main/credential-schema/schemas-examples/proof-of-humanity/proof-of-humanity.jsonld",
    "type": "ProofOfHumanity"
  }
}

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 300
}

{
  "error": "humanity_verification_required",
  "message": "Please complete ProofOfHumanity verification at Billions",
  "verify_url": "https://app.billions.network"
}

ETH Address Linking

Users can link Ethereum addresses to their DID. There are two link types:

• User-initiated link (link_type: user) — the user proves ownership by signing an EIP-191 challenge. This is the explicit, user-controlled flow.
• System-inferred link (link_type: system) — when a user submits a signed transaction (eth_sendRawTransaction) and the proxy forwards it successfully, the sender address (cryptographically recovered from the transaction signature) is automatically linked to the user's DID. This enables response filters to recognise transactions without requiring a separate linking step.

User-initiated links take precedence over system-inferred links when both exist for the same address.

User-Initiated Linking

{
  "nonce": "a1b2c3d4e5f6...",
  "message": "Link Ethereum address to DID\n\nI authorize linking this Ethereum address to my decentralized identity.\n\nDID: did:privado:...\nNonce: a1b2c3d4e5f6..."
}

{
  "nonce": "a1b2c3d4e5f6...",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "signature": "0x..."
}

Address Collision Detection

A single ETH address can be linked by more than one DID — for example, a shared deployer wallet used by a team, or a key-compromise event. When this occurs, the system:

1. Allows the link — shared keys are a legitimate pattern (multi-sig, shared deployer, team wallet).
2. Emits a SIEM event with elevated severity (eth_address_linked_collision) so administrators can review.
3. Surfaces collisions in the admin dashboard — administrators can view all addresses linked to multiple DIDs at GET /api/v1/admin/eth-addresses/collisions.

If a collision is judged to be a key-compromise event rather than intentional sharing, the administrator can revoke the unwanted link.

Configuration

Wallet networks (Privado ID & Billions)

Every wallet's DID is anchored on a specific iden3 network — Privado ID wallets on privado:main, Billions app wallets on billions:main (chainID 45056). During proof verification the proxy resolves each DID's on-chain identity state through a per-network resolver. Both networks are registered out of the box, so users can sign in with either the Privado ID app or the Billions app against a stock deployment.

If a wallet's network has no registered resolver, its proof is rejected before any credential check. The Billions resolver is configured by BILLIONS_RPC_URL and BILLIONS_STATE_CONTRACT; the Privado resolver by PRIVADO_RPC_URL and PRIVADO_STATE_CONTRACT. This applies to basic DID-ownership login (Path A) — it is independent of ProofOfHumanity (Path B).

Credential query file

When Path B is enabled, BILLIONS_CREDENTIAL_QUERY_FILE must point to a JSON file containing a credentialSubject object with the predicate to enforce. The iden3 query language supports operators like $eq, $ne, $lt, $gt, $in, $nin, and multi-field predicates.

{
  "credentialSubject": {
    "isHuman": { "$eq": 1 }
  }
}

A multi-field example (if a credential exposes both fields):

{
  "credentialSubject": {
    "isHuman":     { "$eq": 1 },
    "jurisdiction":{ "$in": ["CH", "DE"] }
  }
}

The proxy assembles the full query at boot by injecting allowedIssuers, context, and type from the other env vars. The file must only describe the credentialSubject predicate.

Testing Options

Option A: Mock Implementation (Development)

Use the MockPrivadoVerifier for local development:

ENVIRONMENT=development
REQUIRE_PROOF_OF_HUMANITY=false

• Skips real ZK proof verification
• Returns configurable responses (isHuman true/false)
• Works without any external infrastructure
• Supports mock tokens: mock.{did} or mock.jwz.token.{did}

Option B: Run Your Own Issuer Node (E2E Testing)

Run a local Privado ID Issuer Node on Polygon Amoy testnet. Clone the repo, configure for Amoy, and create ProofOfHumanity credentials for test users.

Amoy testnet details:

Then configure the proxy (Amoy uses a different state contract than Privado mainnet):

REQUIRE_PROOF_OF_HUMANITY=true
BILLIONS_ISSUER_DID=did:polygonid:polygon:amoy:...
PRIVADO_STATE_CONTRACT=0x1a4cC30f2aA0377b0c3bc9848766D90cb4404124
BILLIONS_CREDENTIAL_QUERY_FILE=/path/to/query.json

Option C: Billions Testnet

For Billions testnet access, see Billions signup.

Testing Matrix

Admin Authentication

Admin API endpoints (/api/v1/admin/*) use a separate authentication layer from the user auth flow described above. The admin middleware accepts two credential types:

X-Admin-Token (M2M / Bootstrap)

For machine-to-machine access and initial setup. Set via the ADMIN_API_TOKEN environment variable and passed in the X-Admin-Token request header.

curl -H "X-Admin-Token: $ADMIN_API_TOKEN" \
  http://localhost:8080/api/v1/admin/orgs

JWT with Admin Claim (Browser-Based)

For admin dashboard access. Users authenticate normally (Privado ID or Azure AD), then the middleware checks whether the user has the admin RBAC claim via any of their group memberships. The check filters out expired memberships.

To grant admin access to a user:

1. Create an organization and group via the admin API (using X-Admin-Token)
2. Set the admin claim on the group's access configuration
3. Add the user as a member of that group

The frontend checks admin status via GET /api/v1/me/admin-status (returns { "is_admin": true/false }). Non-admin users see an "Access Denied" page; unauthenticated users are redirected to login.

Bootstrap the first admin with the X-Admin-Token (M2M) endpoint above, then grant the admin claim to subsequent admins through the RBAC steps just described.

Error Reference

Authentication Errors

ETH Linking Errors

Access Control Errors

On the JSON-RPC data path, RBAC denials — method not allowed, KYC not completed, contract not permitted, and even a ban — are deliberately returned as an opaque 404 method not found; the proxy does not disclose why a call was denied. The operator-facing denial reasons are recorded in the access log and surfaced in Troubleshooting → RBAC.