Centralizing Identity: Deploying Zitadel on a VPS as an OIDC/OAuth2 Provider for Microservices

Introduction: The Identity Challenge in Modern Microservices

As organizations transition from monolithic applications to distributed microservices architectures, managing user identities, authentication, and authorization becomes exponentially complex. In a decentralized ecosystem, allowing each microservice to handle its own user database and authentication logic introduces severe security vulnerabilities, redundant code, and a fragmented user experience. To solve this, engineering teams turn to Single Sign-On (SSO) and centralized Identity Providers (IdP).

While legacy tools like Keycloak have long dominated the market, a modern, cloud-native contender has emerged: Zitadel. Built with a focus on multi-tenancy, turnkey scalability, and developer-friendly APIs, Zitadel offers an excellent balance of performance and flexibility. In this technical guide, we will explore how to deploy Zitadel on a standalone Virtual Private Server (VPS) to serve as the centralized IAM powerhouse for your microservices ecosystem using OpenID Connect (OIDC) and OAuth 2.0 protocols.

---

Why Zitadel? A Modern IAM Alternative

Before diving into the implementation steps, it is essential to understand why Zitadel is uniquely suited for microservices infrastructure compared to traditional solutions:

• Cloud-Native & Lightweight: Written in Go, Zitadel features a remarkably small footprint and rapid startup times compared to Java-based alternatives like Keycloak.
• Built-in Multi-Tenancy: Zitadel’s architecture treats organizations as first-class citizens, allowing you to isolate different clients, partners, or departments natively without complex realm configurations.
• Event-Sourced Architecture: Every configuration change, login event, and user modification is stored as an immutable stream of events. This provides a built-in, unalterable audit log crucial for enterprise compliance.
• Developer-First Experience: With extensive support for gRPC, REST APIs, and modern SDKs, integrating authorization into your individual microservices is seamless.

---

Architecture Overview: Centralized SSO Flow

Deploying Zitadel on a VPS puts it at the core of your infrastructure. When a user or a client application attempts to access your microservices, the authentication flow follows the standard Authorization Code Flow with PKCE (Proof Key for Code Exchange) to maximize security:

1. The client application redirects the unauthenticated user to the Zitadel login page hosted on your VPS domain (e.g., iam.yourdomain.com).
2. The user authenticates via passwords, passkeys (FIDO2), or external Social IdPs.
3. Upon successful authentication, Zitadel issues an Authorization Code and redirects the user back to the client application.
4. The client exchanges this code for an Access Token and an ID Token via a secure back-channel request to Zitadel.
5. The client passes the Access Token (typically a JSON Web Token - JWT) in the HTTP authorization header when making requests to downstream microservices.
6. Microservices validate the incoming JWT locally using Zitadel's public keys (JWKS) or via token introspection.

Security Note: Downstream microservices do not need to query the Zitadel database directly. They cryptographically verify the token's signature, ensuring high-throughput and low-latency performance.

---

Prerequisites and Environment Setup

To successfully follow this guide, ensure your VPS meets the minimum hardware specifications and software requirements:

• VPS Specifications: Minimum 2 vCPUs, 4GB RAM, and 20GB of SSD storage running a clean installation of Ubuntu 22.04 LTS or 24.04 LTS.
• Domain Name: A registered domain or subdomain pointing to your VPS public IP address (e.g., iam.company.com).
• Docker Ecosystem: Docker Engine v24.0+ and Docker Compose v2.0+ installed on the server.

---

Step-by-Step Deployment Guide

Step 1: Database Provisioning

Zitadel supports PostgreSQL and CockroachDB. For production-grade resilience and horizontal scalability, CockroachDB is highly recommended due to its distributed SQL design. We will configure a single-node CockroachDB instance inside our Docker Compose environment for simplicity, which can easily scale out to multiple nodes later.

Step 2: Designing the Configuration File

Create a directory named /opt/zitadel and place your application configuration inside a file named config.yaml. This file dictates how Zitadel communicates with the database, configures encryption keys, and sets up external URLs.

# Partial config.yaml snippet
ExternalSecure: true
ExternalDomain: 'iam.yourdomain.com'
ExternalPort: 443

Log:
  Level: 'info'

Database:
  Cockroach:
    Host: 'crdb'
    Port: 26257
    User: 'zitadel_user'
    Database: 'zitadel'

Step 3: Orchestrating with Docker Compose

Next, define the infrastructure stack using a docker-compose.yml file. This stack includes CockroachDB, Zitadel, and a reverse proxy (like Nginx or Traefik) to manage SSL termination with Let's Encrypt certificates.

version: '3.8'

services:
  crdb:
    image: cockroachdb/cockroach:v23.1.0
    command: start-single-node --insecure
    volumes:
      - crdb_data:/cockroach/cockroach-data
    ports:
      - "26257:26257"

  zitadel:
    image: ghcr.io/zitadel/zitadel:v2.42.0
    command: 'start-from-init --config /config.yaml'
    volumes:
      - ./config.yaml:/config.yaml
    ports:
      - "8080:8080"
    depends_on:
      - crdb
    environment:
      - ZITADEL_MASTERKEY=YourSuperSecret32CharacterMasterKey

volumes:
  crdb_data:

Run docker compose up -d to initiate the setup. Zitadel will automatically initialize the database schema, apply migrations, and output the initial administrator credentials in the container logs.

---

Configuring Zitadel for Microservices

Once deployment is verified and accessible over HTTPS, log into the Zitadel Console to construct your identity perimeter:

1. Setting up Organizations and Projects

Create a dedicated Project within your master organization. In Zitadel, a project acts as a logical container for a collection of microservices and client applications that share the same user pool or authorization context.

2. Creating Application Clients

Within your project, add your frontend applications (e.g., React, Next.js, Angular) as User Agent or Web applications. Ensure you specify correct redirect URIs to prevent open-redirect vulnerabilities. For background workers or inter-service communication, create API Clients utilizing JWT Profile authentication.

3. Defining Roles and Authorizations

Zitadel allows you to define application-specific roles directly in the console. You can assign roles like admin, editor, or billing_manager to users. These roles are automatically embedded inside the OIDC ID and Access tokens, enabling your microservices to execute precise Role-Based Access Control (RBAC).

---

Securing the Deployment

Hosting a centralized identity provider on a public VPS demands rigorous security hardening. Implement the following best practices immediately after deployment:

• Firewall Hardening: Utilize ufw or cloud security groups to block public access to database ports (26257) and internal Zitadel ports (8080). Only ports 80 and 443 should remain open to the public internet.
• Enable TLS 1.3: Ensure your reverse proxy is configured to use modern cryptographic ciphers and explicitly disables weak protocols like TLS 1.0 and 1.1.
• Enforce Multi-Factor Authentication (MFA): Set up global organizational policies within Zitadel requiring all users—especially administrators—to enroll in TOTP or hardware keys (WebAuthn).
• Database Backups: Schedule automated cryptographic backups of the CockroachDB volume to an offsite S3-compatible storage bucket.

---

Conclusion

Centralizing your identity management using Zitadel on a VPS provides an enterprise-grade, highly scalable, and cost-effective solution for securing a microservices ecosystem. By leveraging standard OIDC/OAuth2 protocols, you effectively decouple authentication from your business logic, allowing your engineering teams to focus on building features rather than reinventing security architecture. With its native multi-tenancy, light resource consumption, and intuitive management console, Zitadel proves to be an outstanding foundation for modern, decentralized application security.