Skip to content
Documentation
  • There are no suggestions because the search field is empty.

Guest Authentication & Shadow Accounts with Zitadel

Learn how to build a frictionless guest authentication flow using Zitadel shadow accounts. Discover how to issue valid IDP tokens to anonymous users, track their sessions securely, and seamlessly merge their data upon registration, without forcing a login screen

The Problem: Authorizing Anonymous Users

Many applications require users to interact with secure, authenticated backend APIs before they officially register. Common use cases include:

  • Interactive SaaS Demos: Letting users build a dashboard before signing up.

  • E-commerce: Adding items to a cart or calculating shipping rates.

  • Progressive Onboarding: Collecting user preferences step-by-step before prompting for an email.

Backend microservices usually require cryptographically signed JSON Web Tokens (JWTs) from an Identity Provider (IDP) to authorize these actions. How do you issue a valid IDP token to an anonymous guest without forcing them through a login screen?

The Solution: Zitadel "Shadow Accounts"

The most secure and scalable approach is the Shadow Account (or Ghost Account) pattern. Using Zitadel's powerful impersonation and token exchange features, your backend can silently provision a temporary user, act on their behalf, and later upgrade them to a permanent user.

How the Architecture Works

  1. Anonymous Intent: When an unregistered user performs an action requiring authorization, the frontend calls your backend API.

  2. Silent Provisioning: The backend utilizes a Zitadel Service Account (Machine User) to call the v2 CreateUser API, generating a shadow profile.

    • Best Practice: Tag this user with a metadata key (e.g., GUEST_CREATED_AT) so abandoned accounts can be identified and batch-deleted later via a scheduled cron job.

  3. Token Impersonation: The backend uses the OAuth 2.0 Token Exchange (RFC 8693) flow to swap its Service Account token for an Impersonation Token belonging to the new guest.

  4. Session Creation: The backend returns this valid JWT to the frontend (often in an httpOnly cookie), granting the anonymous user secure access to your microservices.

  5. The Upgrade Path: When the user decides to officially register, the backend updates the shadow account in Zitadel with their real credentials, removes the GUEST metadata tag, and routes them through a standard login flow.

Required Zitadel Configuration

To enable silent provisioning and token exchange, your Zitadel instance requires specific configurations:

  • Enable Impersonation: Navigate to Instance Settings -> Security Settings and explicitly enable Impersonation.

  • Service Account Roles: The Machine User executing the backend API calls must be assigned the IAM End User Impersonator and IAM User Manager roles.

  • OIDC Application Settings: * Ensure your Web Application's Auth Method is set to PKCE (None).

    • Explicitly enable the Token Exchange flow in the Grant Types settings.

See It In Action: Demo App

We built a complete, open-source Next.js application to demonstrate this exact architecture end-to-end. The demo showcases a frictionless e-commerce flow where an anonymous user can add items to a cart, seamlessly upgrade their shadow account, and merge their data upon login.

  • Tech Stack: Next.js (App Router), NextAuth.js, Tailwind CSS, and Zitadel APIs.

  • Key Features: Real-time JWT decoding debug window, PKCE authentication, and cart data merging.

 View the Repository on GitHub