Running Keycloak in an air-gapped environment

No signal comes in. No data goes out. Your Keycloak instance stands alone in an air-gapped network, cut off from the internet by design.

Running Keycloak in an air-gapped environment is not just a security choice; it’s an operational reality for organizations with strict compliance requirements. Without external connectivity, you need a clear process for installation, configuration, updates, and extension management — all without relying on public repos or cloud services.

Why run Keycloak air-gapped?
Air-gapped Keycloak deployments protect against external threats, enforce data sovereignty, and meet regulatory controls that demand complete isolation. Common use cases include defense systems, critical infrastructure, healthcare networks, and internal corporate identity platforms.

Challenges in Air-Gapped Keycloak Deployments

• Installation without external downloads — every artifact, including Keycloak server binaries, themes, and extensions, must be fetched, scanned, and transferred manually.
• Updating Keycloak in isolation — patching involves preparing offline update bundles and verifying integrity before applying.
• Managing identity data — sensitive user and authentication data stays within the isolated environment, requiring careful backup and restore processes that avoid any internet access.
• Dependency control — Maven artifacts, database drivers, and SPI providers must be bundled beforehand to ensure Keycloak runs without outbound requests.

Secure Setup Steps for Keycloak Air-Gapped

1. Prepare artifacts in a staging environment with internet access, including the Keycloak distribution ZIP, required extensions, and all theme resources.
2. Verify cryptographic signatures for each file before moving them into the air-gapped zone.
3. Transfer via approved physical media (e.g., encrypted drives).
4. Configure Keycloak offline by editing standalone.xml or keycloak.conf files directly, setting up realms, clients, and users without relying on external scripts.
5. Preload dependencies into the local Maven repository on the air-gapped system to avoid runtime fetches.
6. Implement internal monitoring without cloud endpoints, using local logging and alerting tools.

Best Practices

• Maintain a strict update calendar to import tested builds.
• Keep a reproducible build pipeline to package Keycloak for air-gapped delivery.
• Limit plugins to audited, trusted code.
• Use internal certificate authorities for HTTPS within the isolated network.

Deploying Keycloak air-gapped is a disciplined process that trades convenience for control. When done right, it provides a hardened identity service immune to external exploits, tuned for your exact compliance needs.

Want to see a secure, isolated identity stack spin up without the usual friction? Try it with hoop.dev — and watch it run in minutes.