How to Deploy Keycloak on Microsoft Azure with Web App, MSSQL and Docker.

Step by step guide to get Keycloak up and running using Microsoft Azure Web App, Azure SQL Database and Docker

Published: Dec. 27, 2024

Updated: Jan. 2, 2025

Tutorials

Overview

This Keycloak for Azure Guide demonstrates how to set up a Keycloak instance on Microsoft Azure using MSSQL and Azure Web Apps. We cover creating an Azure App Service Plan, deploying Keycloak using Docker containers, setting environment variables, and accessing the Keycloak Admin Console for the first time. The cost to run this Keycloak instance will be $30 to $50 per month, depending on the level of Azure App Service Plan and Azure SQL Database you choose. Enjoy!

Step 1. Create MSSQL Database in Azure for Keycloak

You could also use MySQL or PostgreSQL, but in our testing Azure MSSQL had the least setup issues of the three.

  • You could also use MySQL or PostgreSQL, but in our testing MSSQL had the lease setup issues of the three.
  • Standard S0: 10 DTUs should be enough for testing.
  • Search for 'SQL Databases' in the Azure Portal and click Create.
  • Click Create a new SQL Database.
  • For the database name, we are using 'keycloakdemo'. You can call it whatever you want.
  • For the compute + storage, we are using 'Standard S0: 10 DTUs'. In our testing, Basic 5 DTUs was too slow to initialize the Keycloak server. Once it's up and running, it's fine with B5, but the initial setup struggled.
  • For the server, you'll be prompted to create one. We are using 'keycloakdemoserver'.
  • When creating the server, for Authentication Type, we are using 'SQL Authentication'. You can use 'Microsoft Entra-only authentication' if you prefer, but then you'll have to create identities in Azure AD to access the database from the web app.
  • For the DB server admin user, we are using 'admin'. You can use whatever you want.For the DB server admin password, use a strong password. The placeholder in the environment variables below is 'YOUR-DB-PASSWORD'.
  • For the Firewall Rule, we are using 'Allow Azure Services and Resources to access this server'. You can add your IP address as well if you want to access the database directly to check things out. The database is blank initially and keycloak will create the schema when it starts up for the first time.
  • The rest of the settings you can leave as default and click 'Review + Create'. This may take a few minutes to create everything.

Step 2. Create Azure App Service Plan and Web App using Docker.

  • Search for 'App Services' in the Azure Portal and click Create Web App.
  • Select the Subscription, Resource Group, and App Name. We are using 'keycloakdemo' for the App Name.
  • For the Publish, select 'Container'.
  • For the Operating System, select 'Linux'.
  • For the Region, select the one closest to you and the same one you used for the SQL Database.
  • You'll need to create a new App Service Plan. Click 'Create new' and give it a name. We are using 'keycloakdemo-plan'.
  • For the SKU and Size, we are using 'Basic B1'.
  • On the next tab for Container, select 'Open Container Registries' and select 'Docker Hub'.
  • For Access Type, select 'Public'.Registry URL: 'https://index.docker.io/v1'.Image and Tag: 'quay.io/keycloak/keycloak:26.0.1'. We'll update to configure fully in the next steps.
  • Leave the rest of the settings as default and click 'Review + Create'. Grab a quick glass of water while Azure creates everything for you.

Step 3. Web App Settings: Deployment Center with Azure Docker Hub.

Once Azure has created the SQL Database, App Service Plan, and Web App, go to the Web App and click on 'Deployment Center' in the left-hand menu. Copy the below settings and click save.

  • Container Type: Docker Compose
  • Registry Source: Docker Hub
  • Repository Access: Public

Docker Config

Config:
version: '3'
services:
  keycloak:
    image: 'quay.io/keycloak/keycloak:26.0.1'
    ports:
      - '8080:8080'
    volumes:
      - '${WEBAPP_STORAGE_HOME}/data:/opt/keycloak/data/'
    restart: always
    command: start-dev

Docker Config

Config:
version: '3'
services:
  keycloak:
    image: 'quay.io/keycloak/keycloak:26.0.1'
    ports:
      - '8080:8080'
    volumes:
      - '${WEBAPP_STORAGE_HOME}/data:/opt/keycloak/data/'
    restart: always
    command: start-dev
  • Note: once everything is set up, you can change the command to 'start' instead of 'start-dev'. Dev is used to start the server in development mode, which is faster to start up, but not recommended for production. Dev mode defaults include:
    • HTTP is enabled
    • Strict hostname resolution is disabled
    • Cache is set to local (No distributed cache mechanism used for high availability)
    • Theme-caching and template-caching is disabled
  • Keycloak Production mode 'start' is secure by default principle.
  • See Keycloak config for more details: https://www.keycloak.org/server/configuration

Step 4. Web App Settings: Environment Variables for Keycloak Configuration on Azure.

  • Still in the Web App, go to Settings > Environment Variables and add the following environment variables. You can click advanced and copy and paste the entire array below.
  • Be sure to update the placeholders with your own values. Specifically, you need to update the following:
    • KC_DB_URL to include your SQL server name, database name, database admin username, and database password.
    • KC_HOSTNAME, KC_HOSTNAME_ADMIN_URL, KC_HOSTNAME_URL to include your Web App name with the azurewebsites.net extension.
    • KEYCLOAK_ADMIN_PASSWORD to include a strong password for the Keycloak Admin user.
  • Clicking Apply should restart the Web App. If not, go to the Web App overview and restart the Web App.

Web App Environment Variables

[
  {
    "name": "DOCKER_REGISTRY_SERVER_URL",
    "value": "https://index.docker.io/v1",
    "slotSetting": false
  },
  {
    "name": "KC_DB",
    "value": "mssql",
    "slotSetting": false
  },
  {
    "name": "KC_DB_URL",
    "value": "jdbc:sqlserver://keycloakdemoserver.database.windows.net:1433;database=keycloakdemo;user=admin@keycloakdemoserver;password=YOUR-DB-PASSWORD;encrypt=false;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;",
    "slotSetting": false
  },
  {
    "name": "KC_HEALTH_ENABLED",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_ADMIN_URL",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_PORT",
    "value": "443",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_STRICT",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_STRICT_HTTPS",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_URL",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HTTP_ENABLED",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "KC_HTTP_PORT",
    "value": "8080",
    "slotSetting": false
  },
  {
    "name": "KC_LOG_LEVEL",
    "value": "INFO",
    "slotSetting": false
  },
  {
    "name": "KC_METRICS_ENABLED",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_PROXY",
    "value": "edge",
    "slotSetting": false
  },
  {
    "name": "KC_TRANSACTION_XA_ENABLED",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "KEYCLOAK_ADMIN",
    "value": "admin",
    "slotSetting": false
  },
  {
    "name": "KEYCLOAK_ADMIN_PASSWORD",
    "value": "YOUR-ADMIN-PASSWORD",
    "slotSetting": false
  },
  {
    "name": "WEBSITE_HTTPLOGGING_RETENTION_DAYS",
    "value": "1",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_CONTAINER_START_TIME_LIMIT",
    "value": "1800",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_ENABLE_APP_SERVICE_STORAGE",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_PORT",
    "value": "8080",
    "slotSetting": false
  }
]

Web App Environment Variables

[
  {
    "name": "DOCKER_REGISTRY_SERVER_URL",
    "value": "https://index.docker.io/v1",
    "slotSetting": false
  },
  {
    "name": "KC_DB",
    "value": "mssql",
    "slotSetting": false
  },
  {
    "name": "KC_DB_URL",
    "value": "jdbc:sqlserver://keycloakdemoserver.database.windows.net:1433;database=keycloakdemo;user=admin@keycloakdemoserver;password=YOUR-DB-PASSWORD;encrypt=false;trustServerCertificate=true;hostNameInCertificate=*.database.windows.net;loginTimeout=30;",
    "slotSetting": false
  },
  {
    "name": "KC_HEALTH_ENABLED",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_ADMIN_URL",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_PORT",
    "value": "443",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_STRICT",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_STRICT_HTTPS",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_HOSTNAME_URL",
    "value": "https://keycloakdemo.azurewebsites.net",
    "slotSetting": false
  },
  {
    "name": "KC_HTTP_ENABLED",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "KC_HTTP_PORT",
    "value": "8080",
    "slotSetting": false
  },
  {
    "name": "KC_LOG_LEVEL",
    "value": "INFO",
    "slotSetting": false
  },
  {
    "name": "KC_METRICS_ENABLED",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "KC_PROXY",
    "value": "edge",
    "slotSetting": false
  },
  {
    "name": "KC_TRANSACTION_XA_ENABLED",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "KEYCLOAK_ADMIN",
    "value": "admin",
    "slotSetting": false
  },
  {
    "name": "KEYCLOAK_ADMIN_PASSWORD",
    "value": "YOUR-ADMIN-PASSWORD",
    "slotSetting": false
  },
  {
    "name": "WEBSITE_HTTPLOGGING_RETENTION_DAYS",
    "value": "1",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_CONTAINER_START_TIME_LIMIT",
    "value": "1800",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_ENABLE_APP_SERVICE_STORAGE",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_PORT",
    "value": "8080",
    "slotSetting": false
  }
]

Step 5. Login to the Keycloak Admin Console via Azure Web App.

  • If done correctly, the Keycloak web app should begin setting itself up. This can take 5 to 10 minutes for the database to be provisions and keycloak to be fully ready. Grab another glass of water and hydrate.
  • Go to your Web App URL. Our example is 'https://keycloakdemo.azurewebsites.net'.
  • You should be redirected to the Keycloak Admin Console login page. Use the Keycloak credentials provided in the environment variables to login.
  • username: admin
  • password: [YOUR-ADMIN-PASSWORD]

Bonus: Pros and Cons of Keycloak deployed on Microsoft Azure.

Now that you have a Keycloak deployment to play around with, you need to decide if that's the right solution for your production app. Below is a list of considerations to decide if you want to maintain your own enterprise SSO solution or utilize a cloud based solution like AuthBox. Keep in mind that you still have to integrate SAML and OIDC into your application, verify signatures, decrypt assertions and all that fun stuff :)

Pros:

  • Open Source
    • Fully open source and free to use, with an active community and extensive documentation.
  • Supports Multiple Protocols
    • Provides support for SAML, OpenID Connect (OIDC), and OAuth 2.0, making it versatile for different integration scenarios.
  • Customizable and Extensible
    • Offers themes for UI customization and supports custom extensions via SPI (Service Provider Interfaces).
  • Centralized Authentication
    • Enables single sign-on (SSO) and centralized user management for multiple applications.
  • User Federation
    • Allows integration with external user directories like LDAP or Active Directory for seamless authentication.
  • Strong Security Features
    • Includes MFA (multi-factor authentication), user session management, and password policies.
  • Admin Console
    • Intuitive admin interface for managing users, roles, realms, and configurations.
  • Scalability and Clustering
    • Can scale horizontally to handle large user bases and high traffic.
  • Broad Ecosystem Support
    • Provides adapters for major platforms like Spring Boot, Node.js, and WildFly, along with support for Docker and Kubernetes.
  • Cross-Platform
    • Runs on any operating system that supports Java, and works well with cloud platforms like AWS, Azure, and GCP.

Cons:

  • Resource-Intensive
    • Requires significant system resources (e.g., CPU and memory) compared to simpler identity solutions.
  • Complex Setup
    • Initial configuration and deployment can be complex, especially for new users or non-standard use cases.
  • Limited Built-In Reporting
    • Lacks advanced reporting and analytics features, which may require third-party tools.
  • Challenging for Custom Features
    • Developing custom SPI extensions or integrating non-standard features can be time-consuming.
  • Performance Overhead
    • Performance may degrade with very large user bases unless properly tuned.
  • Maintenance and Upgrades
    • Requires careful attention to updates and security patches due to its complexity and reliance on Java.
  • UI/UX Limitations
    • Admin UI may feel clunky or outdated compared to modern identity platforms.
  • No Built-In Support for All Use Cases
    • Certain advanced use cases like delegated administration or fine-grained access control may require workarounds or extensions.
  • Learning Curve
    • Steep learning curve, especially for advanced configurations.
  • Enterprise Support Costs
    • Enterprise-grade support is available only through Red Hat’s subscription-based model, which may increase costs.

Onboard your first
Enterprise customer today

Unlimited users. Lots of Enterprise connections. Free to get started - no credit card required.