Deploy Keycloak on Azure App Service

Keycloak is an awesome open-source identity and access management solution that can be used to secure applications and services. In this guide, we’ll walk through the process of deploying Keycloak on Azure App Service. I did this with the docker option on Linux. I’m using Postgres from Supabase as the database, but you can use any database you like. I tried it with Azure SQL as well, with no issues.

There’s a lot of content out there, but I wanted to share a few things thing that badly tripped me up.

• When you’re deploying Keycloak on Azure App Service, you need to set the KC_HOSTNAME environment variable to the hostname of your app service. This is because Keycloak uses this value to generate URLs for various endpoints, and if it’s not set correctly, you’ll run into issues with redirects and other functionality. A neat trick is to use the ${WEBSITE_HOSTNAME} environment variable to dynamically set this value based on the hostname of your app service.

• In your App Service environment variables you must set {WEBSITES_ENABLE_APP_SERVICE_STORAGE} to true. This is because Keycloak requires a persistent storage location for its data, and this environment variable enables the App Service to provide this functionality.

• When switching to a production environment, you should consider using a more robust database solution like PostgreSQL instead of the default H2 database. This will provide better performance and scalability, especially as your application grows. But when you do this it’s very important to avoid the --optimize option for the start command. This option will build the container with the default H2 database (which is not suitable for production use) which then causes the following error:

Datasource '<default>': Driver does not support the provided URL: jdbc:...

It tells you this on the documentation, but it’s easy to miss. I spent a good few hours trying to figure out why my Keycloak container wouldn’t start and this was the reason.

Below is my production docker-compose.yml file that I used to deploy Keycloak on Azure App Service. I hope this helps you avoid some of the pitfalls I encountered.

Best of luck with your deployment!

version: "3.8"

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start
    environment:
      - KC_DB=postgres
      - KC_DB_URL=jdbc:postgresql://aws-0-us-east-1.pooler.supabase.com:6543/postgres?user=postgres.[username]&password=[password]
      - KC_DB_USER=postgres.[username]
      - KC_DB_PASSWORD=[password]
      - KC_HOSTNAME=${WEBSITE_HOSTNAME}
      - KC_PROXY_HEADERS=xforwarded
      - KC_HTTP_ENABLED=true
      - KC_HTTP_RELATIVE_PATH=/auth
      - KC_CACHE=local
      - KC_LOG_LEVEL=INFO
      - KEYCLOAK_ADMIN=admin
      - KEYCLOAK_ADMIN_PASSWORD=adminpassword
      - KC_HEALTH_ENABLED=true
      - KC_METRICS_ENABLED=true
    ports:
      - 8080:8080
    volumes:
      - ${WEBAPP_STORAGE_HOME}/keycloak-data:/opt/keycloak/data