Proxy Configuration

ZITADEL Cloud

Fronting ZITADEL Cloud

You can use your reverseproxy, content delivery network (CDN) or web application firewall (WAF) to front ZITADEL Cloud. However we currently do not recommend this for production settings.

To configure your service that fronts ZITADEL please have a look at the vendors in this page.

Things to look out for when fronting ZITADEL Cloud

• Cache-control - ZITADEL Cloud uses a CDN to globally distribute data. Please try to avoid overriding this header as it may lead to sideeffects
• Rate Limits - ZITADEL Cloud uses a combination of static and dynamic rate limits. If you recieve occasional 429 headers you are rate limited.

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

NGINX

TLS mode external

worker_processes  1;
events {
    worker_connections  1024;
}

http {
    server {
        listen 443;

        ssl_certificate     ssl/certificate.pem;
        ssl_certificate_key ssl/key.pem;

        location / {
            grpc_pass grpc://localhost:8080;
            grpc_set_header Host $host;
        }
    }
}

info

If another port than the default HTTPS port 443 is used replace

grpc_set_header Host $host;

with

grpc_set_header Host $host:$server_port;

TLS mode enabled

worker_processes  1;
events {
    worker_connections  1024;
}

http {
    server {
        listen 443;

        ssl_certificate     ssl/certificate.pem;
        ssl_certificate_key ssl/key.pem;

        location / {
            grpc_pass grpcs://localhost:8080;
            grpc_set_header Host $host;
        }
    }
}

info

If another port than the default HTTPS port 443 is used replace

grpc_set_header Host $host;

with

grpc_set_header Host $host:$server_port;

TLS mode disabled

worker_processes  1;
events {
    worker_connections  1024;
}

http {
    server {
        listen 80;

        location / {
            grpc_pass grpc://localhost:8080;
            grpc_set_header Host $host;
        }
    }
}

info

If another port than the default HTTP port 80 is used replace

grpc_set_header Host $host;

with

grpc_set_header Host $host:$server_port;

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

Traefik

TLS mode external

entrypoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
tls:
  stores:
    default: 
      defaultCertificate:
providers:
  file:
    filename: /etc/traefik/traefik.yaml
http:
  middlewares:
    zitadel:
      headers:
        isDevelopment: false
        allowedHosts:
        - 'localhost'
        customRequestHeaders:
          :authority: 'localhost'
    redirect-to-https:
      redirectScheme:
        scheme: https
        port: 443
        permanent: true
  routers:
    router0:
      entryPoints:
      - web
      middlewares:
      - redirect-to-https
      rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
      service: zitadel
    router1:
      entryPoints:
      - websecure
      service: zitadel
      middlewares:
      - zitadel
      rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
      tls:
        domains:
          - main: "localhost"
            sans:
              - "*.localhost"
              - "localhost"
  services:
    zitadel:
      loadBalancer:
        servers:
        - url: h2c://localhost:8080
        passHostHeader: true

TLS mode enabled

entrypoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
tls:
  stores:
    default: 
      defaultCertificate:
providers:
  file:
    filename: /etc/traefik/traefik.yaml
http:
  middlewares:
    zitadel:
      headers:
        isDevelopment: false
        allowedHosts:
        - 'localhost'
        customRequestHeaders:
          :authority: 'localhost'
    redirect-to-https:
      redirectScheme:
        scheme: https
        port: 443
        permanent: true
  routers:
    router0:
      entryPoints:
      - web
      middlewares:
      - redirect-to-https
      rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
      service: zitadel
    # The actual ZITADEL router
    router1:
      entryPoints:
      - websecure
      service: zitadel
      middlewares:
      - zitadel
      rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
      tls:
        domains:
          - main: "localhost"
            sans:
              - "*.localhost"
              - "localhost"
  services:
    zitadel:
      loadBalancer:
        servers:
        - url: https://localhost:8080
        passHostHeader: true

TLS mode disabled

entrypoints:
  web:
    address: ":80"
providers:
  file:
    filename: /etc/traefik/traefik.yaml
http:
  middlewares:
    zitadel:
      headers:
        isDevelopment: false
        allowedHosts:
        - 'localhost'
        customRequestHeaders:
          :authority: 'localhost'
  routers:
    router0:
      entryPoints:
      - web
      middlewares:
      - redirect-to-https
      rule: 'HostRegexp(`localhost`, `{subdomain:[a-z]+}.localhost`)'
      service: zitadel
  services:
    zitadel:
      loadBalancer:
        servers:
        - url: h2c://localhost:8080
        passHostHeader: true

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

Caddy

TLS mode external

https://localhost {
        reverse_proxy h2c://localhost:8080
        tls internal #only non production
}

TLS mode enabled

https://localhost {
        reverse_proxy https://localhost:8080
        tls internal #only non production
}

TLS mode disabled

http://localhost {
        reverse_proxy h2c://localhost:8080
}

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

Apache httpd

TLS mode external

LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule access_compat_module modules/mod_access_compat.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule reqtimeout_module modules/mod_reqtimeout.so
LoadModule filter_module modules/mod_filter.so
LoadModule mime_module modules/mod_mime.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule headers_module modules/mod_headers.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule version_module modules/mod_version.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule proxy_http2_module modules/mod_proxy_http2.so
LoadModule unixd_module modules/mod_unixd.so
LoadModule status_module modules/mod_status.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule dir_module modules/mod_dir.so
LoadModule alias_module modules/mod_alias.so
LoadModule rewrite_module modules/mod_rewrite.so

ServerRoot "/usr/local/apache2"
LogLevel warn
ErrorLog /proc/self/fd/2
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

ServerName my.domain
Listen 80
Listen 443

SSLRandomSeed startup builtin
SSLRandomSeed connect builtin

<VirtualHost *:80>
    ServerName my.domain
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
</VirtualHost>

<VirtualHost *:443>
    ServerName my.domain
    ProxyPreserveHost On
    SSLCertificateFile /certs/server.crt
    SSLCertificateKeyFile /certs/server.key
    ProxyPass / h2c://localhost:8080/
    ProxyPassReverse / h2c://localhost:8080/
</VirtualHost>

TLS mode enabled

LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule access_compat_module modules/mod_access_compat.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule reqtimeout_module modules/mod_reqtimeout.so
LoadModule filter_module modules/mod_filter.so
LoadModule mime_module modules/mod_mime.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule headers_module modules/mod_headers.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule version_module modules/mod_version.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule proxy_http2_module modules/mod_proxy_http2.so
LoadModule unixd_module modules/mod_unixd.so
LoadModule status_module modules/mod_status.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule dir_module modules/mod_dir.so
LoadModule alias_module modules/mod_alias.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule http2_module modules/mod_http2.so

ServerRoot "/usr/local/apache2"
LogLevel debug
ErrorLog /proc/self/fd/2
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

ServerName my.domain
Listen 80
Listen 443

SSLRandomSeed startup builtin
SSLRandomSeed connect builtin

<VirtualHost *:80>
    RewriteEngine On
    RewriteCond %{HTTPS} off
    RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
</VirtualHost>

<VirtualHost *:443>
    ProxyPreserveHost On
    SSLEngine on
    SSLProxyEngine on
    SSLCertificateFile /certs/server.crt
    SSLCertificateKeyFile /certs/server.key
    ProxyPass / h2://localhost:8080/
</VirtualHost>

TLS mode disabled

LoadModule mpm_event_module modules/mod_mpm_event.so
LoadModule authn_file_module modules/mod_authn_file.so
LoadModule authn_core_module modules/mod_authn_core.so
LoadModule authz_host_module modules/mod_authz_host.so
LoadModule authz_groupfile_module modules/mod_authz_groupfile.so
LoadModule authz_user_module modules/mod_authz_user.so
LoadModule authz_core_module modules/mod_authz_core.so
LoadModule access_compat_module modules/mod_access_compat.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule reqtimeout_module modules/mod_reqtimeout.so
LoadModule filter_module modules/mod_filter.so
LoadModule mime_module modules/mod_mime.so
LoadModule log_config_module modules/mod_log_config.so
LoadModule env_module modules/mod_env.so
LoadModule headers_module modules/mod_headers.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule version_module modules/mod_version.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule proxy_http2_module modules/mod_proxy_http2.so
LoadModule unixd_module modules/mod_unixd.so
LoadModule status_module modules/mod_status.so
LoadModule autoindex_module modules/mod_autoindex.so
LoadModule dir_module modules/mod_dir.so
LoadModule alias_module modules/mod_alias.so
LoadModule rewrite_module modules/mod_rewrite.so

ServerRoot "/usr/local/apache2"
LogLevel warn
ErrorLog /proc/self/fd/2
CustomLog /proc/self/fd/1 "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""

ServerName my.domain
Listen 80

<VirtualHost *:80>
    ServerName my.domain
    ProxyPreserveHost On
    ProxyPass / h2c://localhost:8080/
    ProxyPassReverse / h2c://localhost:8080/
</VirtualHost>

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

Cloudflare Tunnel

caution

The Cloudflare tunnel client currently has an issue which allows it not to force HTTP/2 usage towards the origin.

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2

Cloudflare

Settings

• Make sure HTTP/2 is enabled
• Verify that gRPC is enabled
• Verify that traffic is proxied through cloudflare
• Configure ZITADEL to use the TLS Mode enabled

info

Cloudflare does only support gRPC with TLS!

Troubleshooting

If something is not working please check the cloudflare WAF rules for potential violations. These two rules are known to be triggered:

• 100001 Anomaly:Header:User-Agent - Missing Cloudflare Specials
• 100004 Anomaly:Header:User-Agent, Anomaly:Header:Referer - Missing or empty

More information

• You can read here about the TLS Modes
• And here about how ZITADEL makes use of HTTP/2