Authentication Flow

This page explains how BlokSec’s passwordless authentication works at a conceptual level. Understanding the flow helps you design better integrations and troubleshoot issues. It intentionally stays high-level on cryptographic internals.

What makes BlokSec different

Traditional authentication relies on shared secrets — passwords that both the user and the server know. BlokSec replaces this with public-key cryptography. Instead of verifying “does the user know the password?”, BlokSec verifies “can the user produce a valid digital signature?” There is no password to phish, reuse, or leak.

How the signing key is protected depends on the authentication method. BlokSec offers two passwordless methods, described below.

Authentication methods

BlokKey (mobile authenticator)

BlokKey is the BlokSec mobile authenticator app, and the most common method for day-to-day sign-ins. Once a device is enrolled, the user approves a sign-in with a single tap.

The user’s private key is generated and stored on their own device, protected by the device’s hardware security (secure enclave on iOS, TPM-backed keystore on Android). BlokSec’s server keeps only the corresponding public key, which it uses to verify signatures. Because the private key never leaves the device, there are no central secret credentials for an attacker to steal from BlokSec.

Push approval flow:

1. User initiates sign-in — The user enters their identifier on the login page.
2. Server sends a push notification — Delivered to the registered device via APNs (iOS) or FCM (Android).
3. User approves or denies — The user reviews the request (application name, location, device) and taps Approve or Deny. On approval, the authenticator signs the request on the device.
4. Server verifies and completes — The server verifies the signature against the stored public key and completes authentication, or fails if denied.

The login page polls the server while waiting. If the user doesn’t respond within 120 seconds, the request expires.

Tip

Push approval doesn’t require QR scanning, making it the fastest option for day-to-day sign-ins.

BlokBadge (split-key QR)

BlokBadge signs a user in from a personal QR badge instead of a typed username. The signing credential is split into three parts, so that no single component can authenticate on its own:

• a part carried in the user’s BlokBadge QR code,
• a part held by the BlokSec server, and
• the user’s PIN/passcode.

Sign-in flow:

1. User scans their BlokBadge — Instead of entering an identifier, the user scans their personal QR code with the browser’s webcam (or a 2D barcode scanner). The badge uniquely identifies the user.
2. Server resolves the account — From the user’s identity in the badge and the application’s identity (already known to the server during the auth flow), BlokSec determines which account is signing in. With BlokBadge, a user has a single account per application.
3. User enters their PIN/passcode — After the scan, the user is prompted for their secret.
4. Server assembles the credential and signs — The badge’s portion of the cryptographic material and the user’s PIN are sent to the server and combined with the server’s own portion to momentarily reconstruct the signing credential and produce the signature, which is verified against the stored public key.
5. Ephemeral by design — The reconstructed credential exists in server memory only for that signing operation and is zeroed immediately afterward. It is never written to disk or persisted.

Note

Because the credential is split three ways, compromising any single component is not enough: the user’s badge, the user’s PIN/passcode, and the server’s portion are all required together, and the assembled credential never outlives the signature.

DID-based identity

BlokSec uses Decentralized Identifiers (DIDs) as the primary identity anchor for users and applications. Each user has a master DID derived from their cryptographic key pair, and each application has its own DID derived from its database identifier.

DIDs appear in OIDC tokens as the sub (subject) claim and in SAML assertions as part of the internal identifiers. Your application doesn’t need to understand or process DIDs directly — they’re used internally by BlokSec for identity management.

Security properties

Property	How it’s achieved
No shared secrets	Sign-in uses digital signatures, not passwords — there’s nothing on the server to steal and replay
Phishing-resistant	Users approve on their own device; there’s no password to type into a fake page
No central key store (BlokKey)	The private key is generated and stored on the user’s device (secure enclave / TPM); BlokSec keeps only the public key, so there’s nothing central to steal
Multi-factor split (BlokBadge)	The signing credential is split three ways (the user’s QR badge, the server, and the user’s PIN/passcode); the assembled credential is ephemeral and zeroed immediately after signing
Unique per authentication	Each sign-in produces a unique signature; compromising one doesn’t help with another