Keycloak behind a Nginx Proxy Manager (NPM) #37021

PelleHanses · 2025-02-03T20:46:55Z

PelleHanses
Feb 3, 2025

Hi,
is someone running Keycloak in docker and have a Nginx proxy manager as docker as reverse proxy in fron of Keycloak?
Can you please give me some hints on how to setup both Keycloak and Nginx proxy manager to get it to work?

In this first setup we have both Keycloak and Nginx proxy manager on the same host.

Thanks
PelleH

vmsman · 2026-03-08T17:13:04Z

vmsman
Mar 8, 2026

This is apparently impossible.

0 replies

WarmWelcome · 2026-06-07T05:23:28Z

WarmWelcome
Jun 7, 2026

@PelleHanses @vmsman After suffering for 16+ hours, I have been able to put something together. I use NPM Plus, so it might be slightly different in the nginx section for you

.env:

# Keycloak config
KC_HOSTNAME="https://login.example.com"
KC_PORTNUMBER="12345"
## Pick timezone from "TZ Identifier" column: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
TIMEZONE="Etc/UTC" 

## NPM
PRIVKEY_PEM_PATH="./nginx/cert/letsencrypt/live/example.com/privkey.pem"
FULLCHAIN_PEM_PATH="./nginx/cert/letsencrypt/live/example.com/fullchain.pem"

## NPM Plus (Nginx Proxy Manager Plus)
#PRIVKEY_PEM_PATH="./npmplusfolder/opt/npmplus/tls/certbot/live/npm-10/privkey.pem"
#FULLCHAIN_PEM_PATH="./npmplusfolder/opt/npmplus/tls/certbot/live/npm-10/fullchain.pem"

## Temp user
### After you have created your account and disabled this user, comment out "KC_BOOTSTRAP_ADMIN_USERNAME" and "KC_BOOTSTRAP_ADMIN_PASSWORD" in the compose file
KC_BOOTSTRAP_ADMIN_USERNAME="tempadmin"
KC_BOOTSTRAP_ADMIN_PASSWORD="CHANGEME"

# Postgres config
POSTGRES_DB="keycloak"
POSTGRES_USER="keycloak"
POSTGRES_PASSWORD="CHANGEME"


# Naughty corner
## I hate hate this env. I cannot get this &#!^ to work for the life of me and no one else seems to be able to either.
## The devs somehow see zero issue with it, which is ironic since there have been a million issues about it. No working examples have ever been provided AFAIK. 
## Disabled in docker compose file, avoid this at all costs (but if you can figure out how to configure it to work with this, please share. lol)
#KC_HOSTNAME_ADMIN="https://login-admin.example.com"

Genuinely incredibly angry at that hostname admin env. I spent way too long trying to get that to work and testing different setups before I gave up. Every issue with this basically says "wontfix, you just don't understand how it works" and provide no examples so we can understand how it works. Maybe being so hard to use, explain, or even give a working example of is evidence to the fact that it is broken? But I digress.

docker-compose.yml

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.6.3
    command: start
    environment:
      - "TZ=${TIMEZONE}"
      - "KC_DB=postgres"
      - "KC_DB_URL=jdbc:postgresql://kcpostgres/${POSTGRES_DB}"
      - "KC_DB_USERNAME=${POSTGRES_USER}"
      - "KC_DB_PASSWORD=${POSTGRES_PASSWORD}"
      # - "KC_HOSTNAME_DEBUG=true" # Only enable when needed
      - "KC_HOSTNAME=${KC_HOSTNAME}"
      # - "KC_HOSTNAME_ADMIN=${KC_HOSTNAME_ADMIN}" # Cannot, for the life of me, get this shit to work properly. Avoid at all costs. 
      - "KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true" # Set to false to allow client-server communication through a private network. See https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/22.0/html/server_guide/hostname-#hostname-backend
      # - "KC_HOSTNAME_STRICT=false" # "If KC_HOSTNAME is specified, KC_HOSTNAME_STRICT is effectively ignored" - Per KC logs at startup
      - "KC_HTTP_ENABLED=true"
      - "KC_PROXY_HEADERS=xforwarded"
      - "KC_HEALTH_ENABLED=true"
      - "KC_METRICS_ENABLED=true"
      - "KC_LOG_LEVEL=info"
      # - "KC_BOOTSTRAP_ADMIN_USERNAME=${KC_BOOTSTRAP_ADMIN_USERNAME}" # Only enable when needed
      # - "KC_BOOTSTRAP_ADMIN_PASSWORD=${KC_BOOTSTRAP_ADMIN_PASSWORD}" # Only enable when needed
    ports:
      - "${KC_PORTNUMBER}:8080"
      - "9000:9000"
      # - "57801:8443" # admin interface avaiable on local network
    volumes:
      - ./keycloak/keycloak.conf:/opt/keycloak/configuration/keycloak.conf
      - ./keycloak/providers:/opt/keycloak/providers
      - ./keycloak/data:/opt/keycloak/data
      - ./keycloak/themes:/opt/keycloak/themes
      - "${PRIVKEY_PEM_PATH}:/opt/keycloak/conf/server.key.pem"
      - "${FULLCHAIN_PEM_PATH}:/opt/keycloak/conf/server.crt.pem"
    depends_on:
      kcpostgres:
        condition: service_healthy
    networks:
     - keycloak_network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/health/live"]
      interval: 10s
      timeout: 10s
      retries: 20

  kcpostgres:
    container_name: kcpostgres
    image: postgres:18-alpine
    environment:
      TZ: ${TIMEZONE}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./keycloak/postgresql:/var/lib/postgresql
    networks:  
     - keycloak_network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  keycloak_network:
    driver: bridge

npm settings

Domain Names: KC_HOSTNAME in your .env
Scheme: http://
Forward Hostname / IP / Path: KC host IP
Forward Port: KC_PORTNUMBER in your .env

In custom locations, set:
Location: ^~ /admin/
same scheme, hostname, port.
For the custom locaiton custom nginx config, I included my public IP address so it would work with my vpn, but your mileage may vary.

allow 127.0.0.0/8;
allow ::1;
allow 192.168.0.0/24;
allow 192.168.0.0/16;
allow 172.16.0.0/12;
allow <PUBLIC_IP_ADDRESS>;
deny all;

In TLS settings, force HTTPS. May need to enable websockets but I don't have that setting anymore in npm plus.

For the overall custom nginx configuration, you should only need this

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;

And that was all! Let me know if it worked for ya.

0 replies

Navigation Menu

Repository navigation

Keycloak behind a Nginx Proxy Manager (NPM) #37021

Uh oh!

{{title}}

Uh oh!

Replies: 2 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Keycloak behind a Nginx Proxy Manager (NPM) #37021

Uh oh!

PelleHanses Feb 3, 2025

Replies: 2 comments

Uh oh!

vmsman Mar 8, 2026

Uh oh!

WarmWelcome Jun 7, 2026

.env:

docker-compose.yml

npm settings

PelleHanses
Feb 3, 2025

vmsman
Mar 8, 2026

WarmWelcome
Jun 7, 2026