Back to articles
DevOps & Systems

Guide to Configuring Zitadel on VPS for Authentication and RBAC Management for 5 SaaS Applications

This is a detailed guide on configuring Zitadel on a VPS to manage user authentication and Role-Based Access Control (RBAC) for a chain of 5 SaaS applications. Zitadel is an...

DPTCloud Engineering4 min read
Guide to Configuring Zitadel on VPS for Authentication and RBAC Management for 5 SaaS Applications

Image credit: wikimedia

This is a detailed guide on configuring Zitadel on a VPS to manage user authentication and Role-Based Access Control (RBAC) for a chain of 5 SaaS applications. Zitadel is an open-source authentication and access management platform that supports fast integration with modern applications. The guide covers installation, service configuration, user, group, role, and policy setup, and integration with SaaS applications via OAuth 2.0 and OpenID Connect. Steps are performed on a Linux-based VPS environment using Docker to deploy Zitadel and supporting tools like Nginx as a reverse proxy. This guide is suitable for DevOps engineers, system engineers, and developers who need to build a centralized authentication system for multiple applications.

Requirements and Prerequisites

To deploy Zitadel on a VPS, you need:

  • A Linux-based VPS (Ubuntu 22.04 or equivalent).
  • Docker and Docker Compose installed.
  • A domain name and SSL certificate (Let's Encrypt can be used).
  • SSH access to the VPS.
  • Basically understanding of Docker, OAuth 2.0, and OpenID Connect.

We use the NVMe Cloud VPS environment from the provider NVMe Cloud VPS for Docker, Nginx & Databases, which meets the performance and storage requirements for SaaS applications. The SaaS applications need to be integrated with Zitadel to use centralized authentication and role-based access control.

Installing Zitadel on VPS

To install Zitadel, create a docker-compose.yml file in your working directory:

version: '3.8'
services:
  zitadel:
    image: zitadel/zitadel:latest
    container_name: zitadel
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./zitadel-data:/zitadel/data
    environment:
      - ZITADEL_CONFIG_PATH=/zitadel/config/config.yaml
    restart: unless-stopped
    depends_on:
      - postgres
    networks:
      - zitadel-network
  postgres:
    image: postgres:15
    container_name: zitadel-postgres
    environment:
      POSTGRES_DB: zitadel
      POSTGRES_USER: zitadel
      POSTGRES_PASSWORD: zitadelpassword
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    networks:
      - zitadel-network
networks:
  zitadel-network:
    driver: bridge

Run the command to start the service:

docker-compose up -d

After starting, Zitadel will run on ports 80 and 443. You can access the administration interface via a browser at https://your-domain.com. Zitadel will automatically create a PostgreSQL database and initial configuration.

Creating Users, Groups, and Roles

Access the Zitadel administration interface to create users, groups, and roles. The first step is to create an administrator user to manage the system. Then, create groups such as "Admin", "User", and "Viewer" and define corresponding roles.

To create authorization roles, go to the Roles section in the administration interface. For example, create an "Admin" role with full resource access, a "User" role with read and write permissions, and a "Viewer" role with read-only access.

For the SaaS applications, create OAuth 2.0 clients for integration. Each application will have a Client ID and Client Secret to authenticate with Zitadel. The applications need to be configured to use OpenID Connect and send authentication requests to Zitadel.

Integrating with SaaS Applications

To integrate a SaaS application with Zitadel, configure the following parameters:

  • Authorization endpoint: https://your-domain.com/oauth/v2/authorize
  • Token endpoint: https://your-domain.com/oauth/v2/token
  • UserInfo endpoint: https://your-domain.com/oauth/v2/userinfo
  • Client ID and Client Secret: from Zitadel client management
  • Scopes: openid profile email

For example, with a Node.js application, you can use the openid-client library:

const { Issuer } = require('openid-client');
const issuer = await Issuer.discover('https://your-domain.com/.well-known/openid-configuration');
const client = new issuer.Client({
  client_id: 'your-client-id',
  client_secret: 'your-client-secret',
  redirect_uris: ['https://your-app.com/callback'],
  response_types: ['code'],
});
// Use the client to start the authentication process

The chain of 5 SaaS applications can be configured similarly, each with its own client to manage access and authorization based on roles.

Verification and Troubleshooting

To verify that Zitadel is working correctly:

  • Access https://your-domain.com/.well-known/openid-configuration to check OpenID Connect configuration.
  • Run the command docker-compose logs zitadel to check service logs.
  • Try logging into the administration interface with the created account.

If you encounter errors, check:

  • The SSL certificate has been issued correctly and configured on Nginx.
  • The reverse proxy path from Nginx to Zitadel is correct.
  • Ports 80 and 443 are not blocked by the firewall.

Refer to the official Zitadel documentation at https://zitadel.com/docs for more details on configuration and integration.

Related infrastructure & engineering guides: eBPF and Kernel Tracing: A Technical Guide for DevOps

DPTCloud Tier III Infrastructure

Recommended NVMe Cloud VPS Plans to Deploy This Setup

Enterprise RAID 10 NVMe SSDs, CMC & FPT District 9 uplinks with Anycast Anti-DDoS and 99.99% SLA.

View 22 VPS Plans
ECO · vn-02

VPS-2E

94.600 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 2 GB
  • SSD: 30 GB NVMe
ECO · vn-02Recommended

VPS-3E

170.500 ₫ / mo

10% VAT included

  • CPU: 2 vCPU
  • RAM: 4 GB
  • SSD: 50 GB NVMe
BASIC · vn-01Recommended

VPS-05

457.600 ₫ / mo

10% VAT included

  • CPU: 4 vCPU
  • RAM: 8 GB
  • SSD: 50 GB NVMe

Related Articles

View all
ZaloZalo SupportDiscord0384 753 478