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. privado:main is registered out of the box; billions:main requires you to set BILLIONS_RPC_URL. There is deliberately no default, because an RPC endpoint that stops resolving is worse than none at all — the resolver registers but cannot be reached, and every Billions sign-in then fails deep inside proof verification with nothing pointing at the missing setting.

While BILLIONS_RPC_URL is unset, billions:main is simply not registered. A Billions wallet's proof is refused immediately with network_not_supported naming the network, the failure is logged for the operator, and GET /api/v1/auth/providers omits the network so the login page advertises Privado ID alone rather than a sign-in that cannot complete.

BILLIONS_STATE_CONTRACT keeps its default, which stays correct on that chain, so enabling Billions is a one-variable change. The Privado resolver is configured by PRIVADO_RPC_URL and PRIVADO_STATE_CONTRACT. All of 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.

A rejected wallet proof

The wallet and the browser are two different clients. The wallet posts its proof to the callback endpoint and reads the outcome from that response; the browser only polls GET /api/v1/auth/session/{id}/status. When a proof is rejected, that poll now returns failed: true with a short reason, so the login page shows the failure straight away instead of waiting out its polling window and then reporting a timeout that never happened.

The reason comes from a fixed set and never carries internal detail:

A banned account and an internal fault both collapse to authentication_failed deliberately: the session ID is rendered in the on-screen QR code, so anyone who photographs it could otherwise poll for someone else's login outcome. Operators read the precise reason from the proxy log and from GET /api/v1/admin/sessions, which reports it unreduced.

network_not_supported is reported rather than collapsed because it discloses nothing that is not already public: the set of supported networks is published by GET /api/v1/auth/providers, which takes no authentication, and the code itself names no network. Withholding it only cost the person at the browser the one piece of information that would have told them the deployment — not their wallet — needs attention.

A rejection is not final, for the same reason. Because that session ID is visible, anyone who photographs the QR can post one bogus proof — so a failure must not be able to cancel a login that still succeeds. The login page shows the failure but keeps polling, and a wallet that retries successfully still completes the session. Any client polling this endpoint should do the same rather than treating failed: true as terminal.