Install Zitadel

The customer must install Zitadel, an Identity and Access Management (IdAM) service to use the Istari Digital Platform. The Istari Digital Platform will use Zitadel to log users into the Istari Digital frontend as well as manage permissions for which resources the user can access in the Istari Digital Platform.

info

When configuring Zitadel, you will need to save a number of values that will later be referenced when installing the Istari Platform. Details on these are covered below.

Zitadel Setup, Installation, and Configuration

If a customer does not have an ICAM system currently, Istari Digital has a suggested configuration of an Identity and Access Management (IdAM) service using the Zitadel Open Source project. This configuration will install Zitadel and an additional PostgreSQL database into the customer’s Kubernetes cluster. It is recommended that a separate PostgreSQL database is used for Zitadel, to minimize risk of losing all data and users in the event of a disaster. The database implementation, however, is left up to the customer.

Adding the Zitadel Repository

In a terminal run:

helm repo add zitadel https://charts.zitadel.com
helm repo update

zitadel-values.yaml

A zitadel-values.yaml will have to be created to configure the Zitadel installation. The example zitadel-values.yaml requires some values to be filled in by the Customer. These values are in the table below with some example values. The Customer should make sure they set these values in the beginning of the zitadel-values.yaml or replace the Helm variables with the correct values.

Key	Description
Master Key	32-character master encryption key for Zitadel
Admin User Password	Password for initial Zitadel admin user
Customer Domain	The base domain for Zitadel
RDS Instance Host	PostgreSQL host
RDS User Password	Password for the PostgreSQL user
RDS Admin User	PostgreSQL admin user
RDS Admin User Password	Password for the PostgreSQL admin user

warning

The PostgreSQL password ends up becoming part of a URI connection string and thus the characters used must be limited to the following due to URI escaping rules: A–Z a–z 0–9 - _ . ! ~ * ' ( ) ; / ? : @ & = + $ , #

An example zitadel-values.yaml is shown below:

zitadel-values.yaml

# ZITADEL main configuration
image:
  repository: "ghcr.io/zitadel/zitadel"
  tag: "v2.71.17"
  # # If using images from a private repo, also uncomment the
  # # following lines & replace '<image_pull_secret>' with the name of the Kubernetes secret used to pull images
  # imagePullSecrets:
  # - name: <image_pull_secret>
initJob:
  enabled: true
  podAnnotations:
    sidecar.istio.io/inject: "false"
setupJob:
  enabled: true
  machinekeyWriter:
    image:
      repository: "alpine/k8s"
      tag: "1.33.4"
  podAnnotations:
    sidecar.istio.io/inject: "false"
zitadel:
  masterkey: [Master Key] # Set the Master key to your desired key, it should be 32 characters

  configmapConfig:
    ExternalSecure: true
    ExternalPort: 443
    Port: 8080
    ExternalDomain: "zitadel.[Customer Domain]" # Replace with actual domain

    FirstInstance:
      InstanceName: "Main"
      DefaultLanguage: "en"
      Org:
        Name: "zitadel"
        Human:
          UserName: "admin"
          Email:
            Address: "admin@zitadel.[Customer Domain]" # Replace with actual email address
            Verified: true
          PreferredLanguage: "en"
          Password: [Admin User Password] # Replace with secure admin password
          PasswordChangeRequired: false
        Machine:
          Machine:
            Username: "sa"
            Name: "SA Admin"
          MachineKey:
            Type: 1

    TLS:
      Enabled: false

    Database:
      Postgres:
        Host: [RDS Instance Host] # Replace with actual PostgreSQL host
        Port: 5432 # Replace with PostgreSQL port if not using RDS
        Database: zitadel
        MaxOpenConns: 20
        MaxIdleConns: 10
        MaxConnLifetime: "30m"
        MaxConnIdleTime: "5m"
        User:
          Username: zitadel # Replace with database user if different
          SSL:
            Mode: "prefer"
        Admin:
          Username: [RDS Admin User] # Replace with PostgreSQL admin user
          SSL:
            Mode: "prefer"

  secretConfig:
    Database:
      Postgres:
        User:
          Password: [RDS User Password] # Replace with database user password
        Admin:
          Password: [RDS Admin User Password] # Replace with admin user password

Install Zitadel

In a terminal opened to the directory where the Zitadel zitadel-values.yaml exists, run this command to install Zitadel:

helm upgrade --install zitadel zitadel/zitadel --version 8.7.2 -f zitadel-values.yaml

Zitadel DNS

Create a DNS record for Zitadel and an endpoint that can be used to terminate TLS for it.