DocumentationBuild. Deploy. Operate.
DocsDeployment

Configuring Gated Identity

On this page 10 sections

Connect your application’s sign-in, account API and logout to the QSCS identity gate. This guide uses app.example.com for the application and, optionally, api.example.com for a separate API. Replace these with your own origins.

Backend: any language. Implement the HTTP/JSON verifier and account endpoint below in your existing stack, such as PHP, Python, Go, Java, .NET or Node.js. No JavaScript runtime or QSCS browser SDK is required on the backend.

Browser application: steps 3–6 use the packaged JavaScript helpers in the user’s browser, including when your pages are rendered by a non-JavaScript backend. The Express middleware is an optional example.

Native or server-to-server client: use the same backend contract and implement Authentication & Signing and Authentication & Signing with your language’s HTTP and Ed25519 libraries. The packaged browser helpers require browser APIs; they are not a native or server SDK.

1. Prepare the origin and account endpoint

  1. In Infrastructure, open the domain, edit the application origin and enable Require a signed identity. Use Proxy every request for an application that must check the backend on each request. Save the settings.
  2. Keep the login page publicly accessible. QSCS serves its reserved helper and WASM paths directly. Put private account data behind protected API paths.
  3. Restrict backend access to the trusted QSCS nodes or a private loopback listener.
  4. Provide a same-origin GET /api/account endpoint. On each request, resolve the verified account subject, check the account is active, and return its account object as JSON with Cache-Control: no-store. Return 401 for a missing/expired sign-in and 403 for an account that is no longer allowed access. Do not use a cached business report as the account check.

For a standalone deployment, the equivalent origin entry is:

[Origins]
app.example.com = 127.0.0.1:8081 Auth=identity Proxy=all

2. Connect your authentication verifier

Set IdentityAuthUrl on the issuer nodes to authenticate against your application’s own accounts. This verifier setting is separate from the console’s origin and federation controls; include it in your node provisioning configuration.

[Identity Auth]
IdentityAuthUrl = https://identity.example.com/qscs/verify

The node sends an HTTP POST with Content-Type: application/json to this endpoint during login. Implement a handler that accepts the following JSON body in any backend language. Use a trusted HTTPS certificate and restrict access to your nodes. A verifier on the same machine may use loopback HTTP. It must be reachable without requiring the client identity it is establishing. Apply login rate limits and return no credential details in responses or logs.

{
  "uuid": "<32-hex client UUID>",
  "origin": "app.example.com",
  "credentials": "alice:password"
}

Split credentials at the first colon; usernames must not contain colons. Validate the password and account status against your own user store. Return HTTP 200 with a flat JSON object:

JSON — accepted credentials:

{"authenticated":true,"subject":"account:42"}

JSON — rejected credentials:

{"authenticated":false}

subject is an immutable account identifier supplied by your verifier, not a browser-selected role or username. Use 1–256 characters from A–Z a–z 0–9 . _ - : @. QSCS stores the subject with the origin-scoped public-key binding in SpookDB; your application does not need a separate device-key table to enable the gate.

Apply account permissions at the backend

After verification, QSCS removes client-supplied copies and adds these upstream headers:

X-QSCS-Identity: <client UUID>
X-QSCS-Authenticated-Subject: account:42
X-QSCS-Identity-Issuer: app.example.com

Only accept these headers through a trusted QSCS path. Bind the backend privately or restrict ingress to your nodes, check the expected issuer, resolve the subject in your account store, and enforce account status and permissions for the requested operation. A header received directly from the public internet is not proof of identity.

Optional backend example: JavaScript (Node.js / Express)

The lookup below is application code you supply. Apply the same header, account and permission checks in your framework.

// Express middleware: the backend is reachable only through trusted QSCS nodes.
app.use('/api', async (req, res, next) => {
  const issuer = req.get('X-QSCS-Identity-Issuer');
  const subject = req.get('X-QSCS-Authenticated-Subject');
  const uuid = req.get('X-QSCS-Identity');
  if (issuer !== 'app.example.com' || !subject || !uuid) {
    return res.status(401).json({error: 'Sign-in required'});
  }
  try {
    // Implement this lookup using your application's account store.
    const account = await accounts.findBySubject(subject);
    if (!account || !account.active) return res.sendStatus(403);
    req.account = account;
    next(); // Each route also checks its required permissions.
  } catch (error) { next(error); }
});

An existing OAuth or token-based sign-in can be adapted through your verifier, for example by validating a short-lived exchange credential against your identity provider. The browser still calls the QSCS login endpoint with the documented fields; QSCS does not automatically implement an OAuth exchange.

3. Use the packaged browser helpers

The qscs-bootstrap package installs the supported helpers in /opt/qscs/helpers. Core serves them at /.qscs/helpers/ and injects the small qscs client into eligible HTML pages. The matching WASM is served at /.qscs/browser/qscs-substrate.wasm. Package upgrades keep these components together.

Prepare the application page

Keep Browser navigation enabled on the origin (the default). Route /.qscs/helpers/ and /.qscs/browser/ through QSCS. Use your normal application module or deferred script; no SDK download, copied helper files or additional script tags are needed. If browser navigation is disabled, load /.qscs/helpers/client.js before your application code instead.

Allow same-origin scripts and WebAssembly in CSP, typically script-src 'self' 'wasm-unsafe-eval'. Allow the issuer and configured API recipients in connect-src, and keep browser storage available. Await qscs.ready before starting identity or API work. Handle initialization errors with a retry action.

4. Wire up sign-in and session restoration

Browser JavaScript. In your application module, create the session controller. Implement the two UI hooks below with your application’s rendering and request timers. The controller cancels packaged subscriptions and clears their baselines at session transitions. Your cleanup hook clears the application’s own private state.

await qscs.ready;

const session = await qscs.createSession({
  accountUrl: '/api/account',
  clearPrivateState() {
    stopPrivatePolling();     // Your application's timers/subscriptions.
    removePrivateData();      // Rendered account data and local app caches.
  },
  onState(state, value) {
    // 'busy': disable login/logout and pause private UI actions.
    // 'signed-in': value is your verified account object.
    // 'signed-out': show the sign-in form.
    // 'error': value is an Error; offer the appropriate retry action.
    showSessionState(state, value);
  }
});

// Run once at page startup, before starting private API work.
const account = await session.restore();
if (account) startPrivateViews(account);

// From your login form, with normal error handling:
async function signIn(form) {
  const username = form.elements.username.value.trim();
  const password = form.elements.password.value;
  form.elements.password.value = '';
  const account = await session.login(username, password);
  startPrivateViews(account);
}

stopPrivatePolling, removePrivateData, showSessionState and startPrivateViews are application hooks you provide. Start requests after the session method resolves, rather than inside onState. Catch rejected calls at your UI boundary and display their message.

The packaged controller handles the following steps:

  1. Serialize authentication actions and cancel outstanding reads at each account change. The controller rejects overlapping login/logout actions and prevents late results from entering the next session.
  2. Revoke an existing active session before switching accounts. Rotate to a new UUID/keypair before signing POST /auth/login.
  3. Send username, password, client_uuid (32 hex) and pubkey (64 hex). Check both the HTTP response and JSON ok:true.
  4. Fetch /api/account with the new identity before showing private views. Retry a short propagation delay with fresh signed reads, without resubmitting credentials.
  5. On reload, await identity readiness, inspect /auth/status, then verify the protected account endpoint. Restore the account only after that read succeeds.

The controller stores only a session-state marker, not credentials or account responses. The SDK owns the encrypted browser identity. If login succeeds but the account read fails temporarily, offer session.restore() to finish loading the existing session.

5. Read protected APIs and handle errors

Browser JavaScript — signed JSON read:

const report = await session.read('/api/reports/summary?range=7d');
renderReport(report);

Use session.read for JSON GET requests. It sends signed requests, checks the session generation, and returns parsed JSON. Set requestTimeoutMs when creating the controller if your API needs a different request deadline. Use qscs.fetch for other explicit signed requests. Native forms, XMLHttpRequest, resource tags and ordinary fetch calls keep their normal behaviour.

Add a separate API origin

  1. Enable Require a signed identity on both origins.
  2. Open Federated Domain Trust → Add trust. Select the issuer app.example.com, recipient api.example.com, and allowed paths such as /api/reports/.
  3. Save and wait for Applied on all nodes. The console distributes issuer audiences and recipient trust automatically. The browser SDK discovers allowed recipients through /auth/federation.
  4. Allow the recipient in CSP. The packaged controller discovers console-managed recipients automatically; an explicit recipients array is available for standalone configuration.
  5. The helper adds the issuer selector to cross-origin API URLs. Preserve the signature/CORS headers described in API Acceleration.

Browser JavaScript — federated read:

const report = await session.read(
  'https://api.example.com/api/reports/summary?range=7d'
);
renderReport(report);
ResponseApplication action
API recipient returns 401Recheck the protected account endpoint at the issuer. If the account is still valid, keep the session and retry only the rejected GET with fresh signatures. The controller waits 1, 2, 4, 8 and 15 seconds, then shows a resource error.
API recipient returns 403Recheck the issuer account, then show an access-denied error for that resource. Do not repeatedly retry or turn a resource denial into a global logout.
Account endpoint returns 401 or 403Clear private state and return to sign-in. Account checks must include current authorization and account status.
Timeout, network failure or server errorKeep the verified session and offer a retry for the failed read. Do not substitute an empty account or replay login credentials.
Logout or account change during a readAbort the old request, clear account-specific baselines and ignore late replies. The controller reports session_changed for stale results.

Only GET reads are automatically retried by the controller. Submit writes once through qscs.fetch after sign-in, using the application’s cancellation and authorization checks. If the result of a write is uncertain, reconcile its state before resubmitting or use an application-defined idempotency key.

Packaged reads negotiate JSON delta transfer automatically. For API Boost and live updates, follow API Acceleration.

6. Complete logout before allowing another login

Browser JavaScript — logout:

await session.logout(); // Then leave the sign-in form enabled.

The controller completes this sequence:

  1. Immediately remove private UI data, stop polling, abort reads and clear API delta baselines.
  2. Persist a logout-pending marker before sending a signed POST /auth/logout with an empty body.
  3. Require HTTP success and JSON ok:true. Keep the existing key and pending marker if confirmation fails; offer session.logout() again.
  4. After confirmation, rotate the browser identity and store signed-out. Enable sign-in for the next session.
  5. On reload with logout-pending, finish revocation before checking or restoring account state. The controller handles this in session.restore().

Keep the same session controller for the life of the page. It clears private state and reloads other tabs when the session marker changes, so those tabs restore the current stored signer. Do not clear IndexedDB or rotate the key as a substitute for signed logout.

7. Test before publishing

  1. Sign in and confirm that the protected account and API reads succeed.
  2. Sign out and sign straight back in in the same tab, without refreshing. Confirm that private views populate automatically.
  3. Reload while signed in and confirm the account is restored through a signed account read.
  4. Interrupt logout, reload, and confirm that the app retries logout rather than restoring the old session.
  5. Delay a federated recipient’s identity response: its rejected GET should retry while the issuer session stays active.
  6. Revoke access to a resource and then disable an account. Check that the first produces a resource error and the second ends the session.
  7. Switch accounts while requests are pending; no response or delta baseline from the previous account should appear. Repeat with two tabs open.
  8. Confirm unsigned protected requests and direct public access to the backend are rejected.

Protocol reference: Authentication & Signing · Authentication & Signing.

Need a hand with your deployment?Contact support ↗Back to top ↑