Implementing SaaS Passkey Onboarding & Multi-Tenant Auth

Standard credential-based authentication is no longer viable for modern, security-conscious software-as-a-service (SaaS) environments. Password fatigue directly leads to onboarding drop-offs, while phishing attacks exploit weak secondary factors like SMS and email-based one-time passwords (OTPs). Implementing SaaS Passkey Onboarding mitigates these vulnerabilities at the protocol level, combining phishing-resistant security with frictionless UX.

However, architecting passkey authentication for a multi-tenant SaaS application introduces significant engineering hurdles. Relying Party IDs (RP IDs) are strictly bound to domains, requiring dynamic configuration resolution for custom enterprise domains. Furthermore, tenant isolation rules mandate that credentials registered under one organization remain strictly segregated from others. This blueprint provides a complete, production-ready reference architecture for implementing multi-tenant, passkey-native onboarding using TypeScript and Google Cloud Platform (GCP).

1. Introduction: The Future of SaaS Onboarding Security

Security teams, product managers, and enterprise buyers are converging on a single requirement: the elimination of passwords. Traditional multi-factor authentication (MFA) methods fail to address the core problem. If an adversary can trick a user into entering credentials on an illegitimate site, they can often phish the concurrent TOTP or session token as well. Passkeys, built on the FIDO2 and WebAuthn standards, offer a cryptographic defense. They utilize hardware-backed public-key cryptography that is intrinsically tied to the origin domain, rendering phishing attacks mathematically impossible.

For high-compliance environments processing unstructured data—such as platforms built around secure document processing like PDFaiGen—eliminating standard credential databases is a core security requirement. The goal of Staksoft's architecture is to merge this level of defense-in-depth with seamless, single-click SaaS onboarding.

This blueprint targets the specific challenges of multi-tenancy. When an application supports distinct corporate environments—each with custom subdomains (e.g., enterprise-a.saas.com) or fully customized vanity domains (e.g., portal.enterprise-a.com)—the static WebAuthn configuration patterns found in simple consumer apps fall short. Our approach outlines a dynamic, stateless verification model designed for scale on Google Cloud Platform.

2. Understanding Passkeys for SaaS: Beyond Passwords

Passkeys are fundamentally asymmetric cryptographic key pairs. During enrollment, the user\'s device (the authenticator) generates a unique private key locally in secure enclave hardware and registers the matching public key with the SaaS server (the relying party). During authentication, the server challenges the client, which signs the challenge using its hardware-locked private key.

The WebAuthn specification categorizes credentials based on user experience and storage mechanisms:

• Synced Passkeys: Multi-device credentials synchronized across an ecosystem provider\'s cloud (such as Apple iCloud Keychain, Google Password Manager, or Microsoft Credential Manager). They solve the device loss problem seamlessly.

• Device-Bound Passkeys: Uncopyable keys locked to physical hardware (such as YubiKeys or dedicated platform TPM modules). Highly critical for strict compliance models.

To implement WebAuthn within a multi-tenant framework, you must understand three critical variables:

1. Relying Party ID (RP ID): A valid domain name (excluding scheme, port, or path) identifying the authority responsible for the credentials. The browser strictly enforces that the RP ID must be equal to or a registrable suffix of the current document\'s domain origin.

2. Client Data JSON: A JSON object sent from the browser to the backend containing the challenge, origin, and token binding status.

3. Authenticator Attestation: The cryptographic proof supplied by the authenticator certifying its manufacturer, model, and security level. For generic SaaS onboarding, explicit attestation verification is usually bypassed (set to none) to maximize device compatibility, although financial and medical enterprise systems may enforce it to verify HSM usage.

By shifting to passkeys, your application drops user friction dramatically. The registration flow bypasses complex password validation logic, secure storage concerns on client devices, and subsequent validation routines. Instead, it completes in a single biometrically verified gesture.

3. Architecting Multi-Tenant Passkey Authentication

Multi-tenancy requires complete separation of workspace directories. A user in Tenant A should never have their credential context exposed to Tenant B, and a malicious administrator in Tenant B must not be able to register credentials targeting Tenant A\'s workspace.

Core Architectural Principles

• Dynamic Relying Party ID (RP ID) Mapping: The backend cannot use a hardcoded RP ID. Instead, it must dynamically resolve the RP ID based on the incoming tenant identifier and the request host.

• Strict Isolation Barriers: The credentials database must associate public keys with both a user_id and a tenant_id. All authentication checks must utilize composite keys to verify tenant ownership prior to executing cryptographic assertion validation.

• Zero-Trust Challenge Lifecycle: Challenges must be stateless, short-lived, single-use, and signed to protect against replay attacks.

When orchestrating these configurations alongside relational databases on GCP, it is vital to keep database migrations clean and decoupled, similar to the approaches detailed in our analysis of Enterprise Catalog Orchestration on GCP.

Database Schema Design

The schema below details the structural requirements of a Postgres/Cloud SQL database configured for multi-tenant passkey credentials. Note the use of binary data types (BYTEA) for storing keys and raw identifiers. Storing raw buffer data in typical text columns like string-encoded hexadecimal or Base64 frequently triggers encoding corruption, especially when executing low-level platform operations.

CREATE TABLE tenants (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    slug VARCHAR(63) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    custom_domain VARCHAR(255) UNIQUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE NOT NULL,
    email VARCHAR(255) NOT NULL,
    display_name VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(tenant_id, email)
);

CREATE TABLE passkey_credentials (
    id BYTEA PRIMARY KEY, -- Credential ID
    tenant_id UUID REFERENCES tenants(id) ON DELETE CASCADE NOT NULL,
    user_id UUID REFERENCES users(id) ON DELETE CASCADE NOT NULL,
    public_key BYTEA NOT NULL, -- COSE-formatted public key
    counter INT DEFAULT 0 NOT NULL, -- Prevents replay attacks via credential clones
    transports VARCHAR(50)[] DEFAULT '{}'::VARCHAR[],
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_passkey_tenant_lookup ON passkey_credentials(tenant_id, user_id);

4. Implementing Passkey Flows with TypeScript

The following TypeScript solution implements WebAuthn operations on the backend, utilizing the industry-standard @simplewebauthn/server library. It dynamically manages multi-tenant parameters in real-time.

Backend Services: Registration Lifecycle

The enrollment flow consists of two endpoints: generating options and verifying the response.

Step 1: Generating Registration Options

import { generateRegistrationOptions } from '@simplewebauthn/server';
import { Request, Response } from 'express';
import { db } from './db';
import { cacheChallenge } from './cache';

export async function handleGetRegistrationOptions(req: Request, res: Response) {
  const { email, tenantSlug } = req.body;
  const originHost = req.headers.host; // e.g., 'enterprise-a.saas.com' or 'customdomain.com'

  try {
    // 1. Fetch and validate tenant context
    const tenant = await db.query('SELECT * FROM tenants WHERE slug = $1 OR custom_domain = $2', [tenantSlug, originHost]);
    if (tenant.rows.length === 0) {
      return res.status(404).json({ error: 'Tenant context not found' });
    }
    const tenantData = tenant.rows[0];

    // 2. Resolve user. Create user inline if implementing dynamic SaaS onboarding
    let userResult = await db.query('SELECT * FROM users WHERE tenant_id = $1 AND email = $2', [tenantData.id, email]);
    let user = userResult.rows[0];
    if (!user) {
      const insertUser = await db.query(
        'INSERT INTO users (tenant_id, email, display_name) VALUES ($1, $2, $3) RETURNING *',
        [tenantData.id, email, email.split('@')[0]]
      );
      user = insertUser.rows[0];
    }

    // 3. Query existing credentials to exclude
    const existingCreds = await db.query('SELECT id FROM passkey_credentials WHERE tenant_id = $1 AND user_id = $2', [tenantData.id, user.id]);

    // 4. Resolve RP ID dynamics based on host
    const rpID = tenantData.custom_domain || originHost?.split(':')[0] || 'staksoft.com';

    const options = await generateRegistrationOptions({
      rpID,
      rpName: tenantData.name,
      userID: Buffer.from(user.id).toString('base64url'),
      userName: user.email,
      userDisplayName: user.display_name,
      attestationType: 'none',
      authenticatorSelection: {
        residentKey: 'required',
        userVerification: 'required',
        authenticatorAttachment: 'platform'
      },
      excludeCredentials: existingCreds.rows.map(row => ({
        id: row.id,
        type: 'public-key'
      })),
      supportedAlgorithmIDs: [-7, -257] // ES256 and RS256
    });

    // 5. Store challenge in Redis with an expiration of 120 seconds
    await cacheChallenge(`challenge:reg:${user.id}`, options.challenge, 120);

    return res.status(200).json({ options, userId: user.id, tenantId: tenantData.id, rpID });
  } catch (error) {
    console.error('Registration options error:', error);
    return res.status(500).json({ error: 'Internal server error' });
  }
}

Step 2: Verifying the Attestation Response

import { verifyRegistrationResponse } from '@simplewebauthn/server';
import { getCachedChallenge, deleteChallenge } from './cache';

export async function handleVerifyRegistration(req: Request, res: Response) {
  const { response, userId, tenantId, rpID } = req.body;
  const origin = `${req.secure ? 'https://' : 'http://'}${req.headers.host}`;

  try {
    const expectedChallenge = await getCachedChallenge(`challenge:reg:${userId}`);
    if (!expectedChallenge) {
      return res.status(400).json({ error: 'Challenge expired or missing' });
    }

    const verification = await verifyRegistrationResponse({
      response,
      expectedChallenge,
      expectedOrigin: origin,
      expectedRPID: rpID,
      requireUserVerification: true
    });

    await deleteChallenge(`challenge:reg:${userId}`);

    if (!verification.verified || !verification.registrationInfo) {
      return res.status(400).json({ error: 'Verification failed' });
    }

    const { credentialID, credentialPublicKey, counter } = verification.registrationInfo;

    // Save to the isolated SQL database
    await db.query(
      `INSERT INTO passkey_credentials (id, tenant_id, user_id, public_key, counter, transports) 
       VALUES ($1, $2, $3, $4, $5, $6)`,
      [
        Buffer.from(credentialID),
        tenantId,
        userId,
        Buffer.from(credentialPublicKey),
        counter,
        response.response.transports || []
      ]
    );

    return res.status(200).json({ success: true });
  } catch (error) {
    console.error('Verify registration error:', error);
    return res.status(500).json({ error: 'Verification validation failed' });
  }
}

Authentication Flow: Single-Gesture Assertion Verification

During login, user input is completely bypassed if discoverable credentials (resident keys) are enabled. The authenticator prompts the user, scans their biometrics, and produces an assertion payload representing the matched key.

This flow relies on querying the database using the credentialID provided in the verification request. This mapping ensures that the credential resolving to a specific tenant boundary can only authenticate that tenant\'s workspace session.

Client-Side Integration: Standard and Native Frameworks

On web-based frontends, utilize the standard @simplewebauthn/browser library to trigger authenticator gestures without writing manual navigator.credentials.create() byte-array parsers.

import { startRegistration, startAuthentication } from '@simplewebauthn/browser';

async function performWebAuthnOnboarding(email: string, tenantSlug: string) {
  // Obtain dynamically resolved configuration from TypeScript backend
  const optionsRes = await fetch('/api/auth/register/options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, tenantSlug })
  });
  const data = await optionsRes.json();

  // Trigger browser platform authenticator dialog
  const regResponse = await startRegistration(data.options);

  // Submit attestation back to server
  const verificationRes = await fetch('/api/auth/register/verify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      response: regResponse,
      userId: data.userId,
      tenantId: data.tenantId,
      rpID: data.rpID
    })
  });
  return await verificationRes.json();
}

For native environments, platform-specific APIs are required. Mobile frameworks do not leverage standard browser APIs directly but bind instead to native bridges:

• iOS: Use the ASAuthorizationController interface passing ASPublicKeyCredential parameters.

• Android: Integrate the Google Credential Manager API, which unifies passkeys, passwords, and federated identity solutions into a single client interface.

When compiling native modules for systems built on custom cross-platform architectures, pay close attention to structural issues such as the ones detailed in Flutter Dart FFI 16KB Page Alignment: Android 15 Guide to ensure your binary cryptographic calls match the hardware architecture without memory access faults.

5. Leveraging Google Cloud Platform (GCP) for Passkey Backend

Deploying a FIDO2 authentication system requires highly secure, performant, and elastic backend infrastructure. The GCP ecosystem provides native components that fulfill these requirements without introducing architectural complexity.

Cloud Run & Serverless Backend Routing

Deploy the verification microservice using Cloud Run. Because WebAuthn challenge verification relies strictly on CPU-bound cryptographic checks (such as verifying signature algorithms with RSA or ECDSA public keys), Cloud Run\'s ability to scale based on concurrent requests is highly effective. To maintain sub-100ms response times, configure Cloud Run instances with a minimum of 1 CPU and keep warm instances running to eliminate cold-start issues.

Secret Manager and Memorystore

• Google Cloud Secret Manager: Manage deployment-wide cryptographic seeds, database connection pools, and asymmetric JWT-signing keys. These coordinates must never be saved in serverless environment variables.

• Cloud Memorystore (Redis): Challenges must expire within 1-2 minutes. Disk storage mechanisms are too slow and degrade performance. Memorystore provides sub-millisecond read/write performance for temporary challenges. Set the storage key strictly linked to the user context with an explicit TTL value.

Cloud SQL for Isolated Tenant Storage

To enforce tenant-specific access rules and manage persistent user profiles, deploy Cloud SQL (PostgreSQL). To ensure compliance, restrict access using IAM-based database authentication. This eliminates password-based database access, ensuring your application is identity-integrated from the hardware layer up. Utilize connection pooling to safely handle the erratic scaling patterns of serverless Cloud Run instances.

GCP Security Best Practices

Your passkey-native endpoints are highly vulnerable to denial-of-service and credential-stuffing attacks if left exposed. Implement the following layered defenses:

1. Cloud Armor / Cloudflare WAF integration: Apply strict rate limits to registration options requests. Challengers must limit anonymous registration endpoints to a maximum of 5 requests per IP address per minute to prevent malicious challenge-generation floods that can exhaust Redis memory.

2. Audit Logging: Stream structured logs from Cloud Run directly to Cloud Logging. Track credential registrations and capture failure payloads, such as mismatched RP IDs, key verification failures, or unexpected credential types.

6. Multi-Tenant Specific Considerations & Best Practices

Expanding standard WebAuthn logic to support enterprise-grade software deployments introduces operational complexities around custom domain structures and credentials management.

Tenant Data Isolation: Logical vs. Physical Partitioning

For SaaS platforms, choose between two primary partitioning strategies:

• Logical Isolation (Shared DB, Shared Schema): Every row in your credentials database table includes a tenant_id column. Every database query must strictly include this column in its WHERE clause. This approach is highly cost-effective and simple to maintain.

• Physical Isolation (Separate Databases per Tenant): Allocate a dedicated Cloud SQL instance or isolated database container for each enterprise tenant. While significantly more expensive and complex to orchestrate, it provides complete data security and satisfies strict regulatory requirements. See our technical guide on Architecting Least-Privilege Apps to analyze complex trust boundary topologies.

The Custom Domain Conundrum

When an enterprise tenant deploys your platform on a custom domain (e.g., portal.enterprise-a.com), the WebAuthn standard prohibits using your main application domain (saas.com) as the RP ID. The browser restricts the RP ID to the user\'s current top-level domain origin.

To support custom domains without breaking authentication:

1. Dynamically extract the origin host from the request headers in the backend.

2. Validate that the custom domain is registered and active for the requested tenant.

3. Assign the custom domain as the RP ID in the registration and authentication options.

4. Save the specific RP ID used during registration alongside the credential. During authentication, verify that the incoming RP ID exactly matches the domain stored with the credential.

An alternative approach is to use a centralized identity provider (IdP) model. In this setup, users are redirected from custom domains to a central authentication domain (e.g., auth.saas.com) to perform passkey validation before being redirected back with a secure session token.

Admin Dashboard and Credential Revocation

Enterprise administrators require granular control over their users\' credentials. Building administrative tooling to support these actions is a critical step during SaaS passkey onboarding:

• Provide tenant admins with self-service tools to revoke compromised, lost, or unused passkeys.

• Provide detailed metadata for registered credentials, including the registration date, estimated device manufacturer, and last-used timestamp.

Account Recovery Flows

If a user loses access to their authenticator device and has not registered backup keys, they are locked out of their account. Because passkeys eliminate passwords, you must implement alternative, secure recovery methods that maintain phishing-resistant standards:

• Secure Magic Links: Deliver a single-use, time-limited magic link via email, requiring additional out-of-band verification (e.g., verifying a security code shown on the screen).

• Identity Federation: Allow users to link secure SAML or OIDC enterprise directories (such as Okta, Azure AD, or Google Workspace) as backup login mechanisms.

• Offline Recovery Keys: Generate a high-entropy, 256-bit backup code (BIP-39 mnemonic phrase) during the initial onboarding flow. The user must store this key offline to reset their authenticator access if needed.

7. Performance Comparison and Metrics

Transitioning from password-based credentials to passkey-native onboarding significantly improves operational metrics and user engagement. The tables below outline performance benchmarks based on production SaaS environments running equivalent authentication flows.

Authentication Flow Latency (GCP Cloud Run Backend)

Onboarding & Support Ticket Metrics

8. Challenges and Future Outlook

While passkey adoption is growing, enterprise platforms must address several remaining technical and operational challenges. First, older enterprise workstations, server environments, and virtual machines (VMs) often lack native platform TPM hardware, blocking platform authenticators like TouchID or Windows Hello. In these environments, architects must support roaming authenticators like security keys or allow fallback to secure corporate identity providers (IdPs).

Second, managing passkey synchronization within enterprise boundaries requires clear corporate policies. Enterprise security models often restrict the use of consumer cloud systems like Apple iCloud or personal Google Accounts to synchronize business credentials. Managing corporate-approved password managers (e.g., 1Password, Bitwarden) that support professional passkey sharing is essential for maintaining strict data security compliance.

As the FIDO Alliance updates the WebAuthn and CTAP specifications, we will see closer integration between local credential handlers and enterprise mobile management (EMM) software. This evolution will give IT administrators complete control over credential usage, bridging the gap between user convenience and strict enterprise compliance.

9. FAQ

What occurs if a user loses their physical device containing a device-bound passkey?

Without an alternative recovery path, the user is locked out. To prevent this, you should design your onboarding flow to encourage registering at least two separate keys (e.g., a platform-native passkey and a physical security key like a YubiKey). If both are lost, authentication must fallback to your secure recovery mechanism, such as identity federation, SAML SSO, or an offline mnemonic recovery key.

How can we prevent duplicate credential registrations for the same user account?

When requesting registration options via generateRegistrationOptions, populate the excludeCredentials parameter with a list of the user\'s existing credential IDs. The browser will check this list and prevent the user from registering a device that has already been enrolled.

Does dynamic RP ID configuration affect search engine optimization (SEO) or cross-origin headers?

Dynamic RP IDs have no impact on standard search engine crawlers, as they only affect cryptographic authentication endpoints. However, you must ensure your Cross-Origin Resource Sharing (CORS) policies are configured correctly. The backend authentication services must explicitly trust and allow incoming traffic from all registered tenant domains and custom subdomains to ensure smooth WebAuthn operations.

Summary

Implementing SaaS Passkey Onboarding dramatically improves your application\'s security posture and user onboarding conversion. By designing a dynamic RP ID mapping architecture, using byte-aligned binary database fields to prevent credential data corruption, and deploying your serverless validation microservices on GCP Cloud Run, you can build an enterprise-ready, phishing-resistant authentication system. This architecture ensures complete tenant isolation while delivering the seamless, secure login experience modern users expect.

Code Snapshots

TypeScript Server-Side Registration Options Generator

import { generateRegistrationOptions } from '@simplewebauthn/server';
import { TenantConfig, UserRecord } from './types';

interface GenerateOptionsParams {
  user: UserRecord;
  tenant: TenantConfig;
  existingCredentials: Array<{ id: string; transports?: AuthenticatorTransport[] }>;
}

export async function generateTenantRegistrationOptions({
  user,
  tenant,
  existingCredentials
}: GenerateOptionsParams) {
  // Dynamic RP ID mapping is essential for custom multi-tenant domains
  const rpID = tenant.customDomain || `${tenant.slug}.staksoft.com`;
  const rpName = tenant.name;

  return generateRegistrationOptions({
    rpID,
    rpName,
    userID: user.id,
    userName: user.email,
    userDisplayName: user.displayName || user.email,
    attestationType: 'none',
    authenticatorSelection: {
      residentKey: 'required', // Required for discoverable credentials / username-less login
      userVerification: 'required',
      authenticatorAttachment: 'platform' // Restrict to platform authenticators (TouchID, FaceID, Windows Hello)
    },
    excludeCredentials: existingCredentials.map(cred => ({
      id: Buffer.from(cred.id, 'base64url'),
      type: 'public-key',
      transports: cred.transports
    })),
    supportedAlgorithmIDs: [-7, -257] // ES256 and RS256 algorithms
  });
}

TypeScript Verification of WebAuthn Registration Response

import { verifyRegistrationResponse } from '@simplewebauthn/server';
import { RegistrationResponseJSON } from '@simplewebauthn/types';

interface VerifyRegistrationParams {
  response: RegistrationResponseJSON;
  expectedChallenge: string;
  expectedOrigin: string;
  expectedRPID: string;
}

export async function verifyTenantRegistration({
  response,
  expectedChallenge,
  expectedOrigin,
  expectedRPID
}: VerifyRegistrationParams) {
  const verification = await verifyRegistrationResponse({
    response,
    expectedChallenge,
    expectedOrigin,
    expectedRPID,
    requireUserVerification: true
  });

  if (!verification.verified || !verification.registrationInfo) {
    throw new Error('Registration verification failed');
  }

  const { credentialID, credentialPublicKey, counter } = verification.registrationInfo;

  return {
    credentialID: Buffer.from(credentialID).toString('base64url'),
    // Store public key as a binary Buffer to prevent serialization corruption
    credentialPublicKey: Buffer.from(credentialPublicKey),
    counter
  };
}

Relevant Content Suggestions

• Architecting Enterprise Catalog Orchestration: Airflow, Mage-OS, & MySQL 9: Provides critical strategies for GCP-native database provisioning and enterprise data schemas.

• Architecting Least-Privilege Shopify Apps: Task-Based OAuth Consent: Explains multi-tenant trust boundaries, OAuth architectures, and token management in serverless environments.

• Architecting Distributed Sagas with NestJS, Go, and gRPC: Covers transaction orchestration when syncing dynamic configuration states across microservices.

• Flutter Dart FFI 16KB Page Alignment: Android 15 Guide: Addresses low-level serialization and dynamic memory constraints crucial for native mobile authenticator compilation.