data "openstack_images_image_v2" "os" {
  name        = var.image_name
  most_recent = true
}

data "openstack_networking_network_v2" "external" {
  name = var.external_network
}

resource "openstack_networking_network_v2" "private" {
  name           = "${var.app_name}-net"
  admin_state_up = true
}

resource "openstack_networking_subnet_v2" "private" {
  name            = "${var.app_name}-subnet"
  network_id      = openstack_networking_network_v2.private.id
  cidr            = var.private_cidr
  ip_version      = 4
  dns_nameservers = ["1.1.1.1", "8.8.8.8"]
}

resource "openstack_networking_router_v2" "main" {
  name                = "${var.app_name}-router"
  external_network_id = data.openstack_networking_network_v2.external.id
}

resource "openstack_networking_router_interface_v2" "private" {
  router_id = openstack_networking_router_v2.main.id
  subnet_id = openstack_networking_subnet_v2.private.id
}

resource "openstack_networking_secgroup_v2" "auth_oidc" {
  name        = "${var.app_name}-sg"
  description = "SSH and HTTP/HTTPS for a reverse proxy; admin console port 8080 restricted"
}

resource "openstack_networking_secgroup_rule_v2" "ssh" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 22
  port_range_max    = 22
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.auth_oidc.id
}

# 80 and 443 carry Keycloak in production mode, served over HTTPS through a
# reverse proxy (Caddy or Nginx). Keycloak's production "start" command refuses
# to issue real tokens over plain HTTP, so the domain path is the expected way
# real users reach it; see the reference page.
resource "openstack_networking_secgroup_rule_v2" "http" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 80
  port_range_max    = 80
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.auth_oidc.id
}

resource "openstack_networking_secgroup_rule_v2" "https" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 443
  port_range_max    = 443
  remote_ip_prefix  = "0.0.0.0/0"
  security_group_id = openstack_networking_secgroup_v2.auth_oidc.id
}

# Raw Keycloak HTTP on 8080 is restricted to app_allowed_cidr (the private
# network by default). Use it for the initial start-dev realm/client setup
# over an SSH tunnel or a scoped workstation IP; put a reverse proxy on 443 in
# front, and switch Keycloak to production mode, before real users sign in.
resource "openstack_networking_secgroup_rule_v2" "app" {
  direction         = "ingress"
  ethertype         = "IPv4"
  protocol          = "tcp"
  port_range_min    = 8080
  port_range_max    = 8080
  remote_ip_prefix  = var.app_allowed_cidr
  security_group_id = openstack_networking_secgroup_v2.auth_oidc.id
}

resource "openstack_networking_port_v2" "auth_oidc" {
  name               = "${var.app_name}-port"
  network_id         = openstack_networking_network_v2.private.id
  security_group_ids = [openstack_networking_secgroup_v2.auth_oidc.id]

  fixed_ip {
    subnet_id = openstack_networking_subnet_v2.private.id
  }

  depends_on = [openstack_networking_router_interface_v2.private]
}

resource "openstack_blockstorage_volume_v3" "data" {
  name = "${var.app_name}-data"
  size = var.volume_size
}

resource "openstack_compute_instance_v2" "auth_oidc" {
  name        = var.app_name
  flavor_name = var.flavor_name
  key_pair    = var.key_name

  user_data = templatefile("${path.module}/cloud-init/auth-oidc.yaml.tftpl", {
    app_name = var.app_name
  })

  block_device {
    uuid                  = data.openstack_images_image_v2.os.id
    source_type           = "image"
    destination_type      = "volume"
    volume_size           = 30
    boot_index            = 0
    delete_on_termination = true
  }

  network {
    port = openstack_networking_port_v2.auth_oidc.id
  }
}

resource "openstack_compute_volume_attach_v2" "data" {
  instance_id = openstack_compute_instance_v2.auth_oidc.id
  volume_id   = openstack_blockstorage_volume_v3.data.id
}

resource "openstack_networking_floatingip_v2" "auth_oidc" {
  pool = var.external_network
}

resource "openstack_networking_floatingip_associate_v2" "auth_oidc" {
  floating_ip = openstack_networking_floatingip_v2.auth_oidc.address
  port_id     = openstack_networking_port_v2.auth_oidc.id
}

variable "key_name" {
  description = "SSH keypair name (must already exist in your project)"
  type        = string
}

variable "flavor_name" {
  description = "Instance size. Keycloak plus its bundled PostgreSQL runs comfortably on 4 vCPU and 4 GiB RAM (s1a.medium); the JVM-based server wants headroom beyond what a smaller flavor gives it. Size up for many realms or high token-issuance volume."
  type        = string
  default     = "s1a.medium"
}

variable "image_name" {
  description = "Operating system image. Ubuntu 24.04 is the recommended base."
  type        = string
  default     = "Ubuntu-24.04"
}

variable "app_name" {
  description = "Display name prefix for compute and network resources"
  type        = string
  default     = "auth-oidc"
}

variable "volume_size" {
  description = "Block volume size in GiB, mounted at /var/lib/docker so the identity-provider data (the PostgreSQL database holding realms, clients, and users) lives on a volume you can grow rather than on the boot disk."
  type        = number
  default     = 20
}

variable "external_network" {
  description = "Shared external network for router gateway and floating IPs; defaults to PublicStatic (persisted FIP / production pattern). Override with PublicEphemeral for ephemeral demos."
  type        = string
  default     = "PublicStatic"
}

variable "private_cidr" {
  description = "CIDR for the private tenant network the instance lives in"
  type        = string
  default     = "10.48.0.0/24"
}

variable "app_allowed_cidr" {
  description = "CIDR allowed to reach Keycloak on port 8080. Defaults to the private network only, so the admin console and the start-dev bootstrap are not exposed to the public internet on the raw port. Keycloak's production mode (start) refuses to serve real login traffic without HTTPS, so the normal access path is a domain with TLS on 443 behind a reverse proxy; reach port 8080 directly only for initial realm and client setup, over an SSH tunnel or from this CIDR. To reach it from your workstation during setup, set this to YOUR_IP/32."
  type        = string
  default     = "10.48.0.0/24"
}

#cloud-config
package_update: true
packages:
  - ca-certificates
  - curl
write_files:
  - path: /opt/auth-oidc/docker-compose.yml
    permissions: "0644"
    content: |
      # Keycloak identity provider for ${app_name}. The admin console and the
      # OIDC endpoints listen on port 8080. cloud-init starts Keycloak in
      # start-dev mode against the bundled PostgreSQL so you can create a
      # realm and a client right away from app_allowed_cidr; Keycloak's
      # production "start" command refuses to issue real tokens over plain
      # HTTP, so switch to it (with KC_HOSTNAME, KC_PROXY_HEADERS, and
      # KC_HTTP_ENABLED) once a domain and a reverse proxy are in front. No
      # credential ships with this template: the bootstrap admin password and
      # the database password are generated on first boot.
      services:
        keycloak:
          image: quay.io/keycloak/keycloak:26.6.4
          restart: unless-stopped
          command: start-dev
          ports:
            - "8080:8080"
          env_file:
            - /opt/auth-oidc/.env
          depends_on:
            - postgres
        postgres:
          image: postgres:16-alpine
          restart: unless-stopped
          env_file:
            - /opt/auth-oidc/.env
          volumes:
            - auth_oidc_pg:/var/lib/postgresql/data
      volumes:
        auth_oidc_pg:
runcmd:
  - |
    set -e
    # The data volume attaches as /dev/sdb on this platform (not /dev/vdb).
    # Mount it at /var/lib/docker before Docker is installed so the
    # PostgreSQL data (realms, clients, and users) lives on the resizable
    # volume rather than the boot disk.
    DEV=/dev/sdb
    for i in $(seq 1 30); do [ -b "$DEV" ] && break; sleep 5; done
    if ! blkid "$DEV" >/dev/null 2>&1; then mkfs.ext4 -F -L authoidcdata "$DEV"; fi
    mkdir -p /var/lib/docker
    mount "$DEV" /var/lib/docker
    grep -q "$DEV" /etc/fstab || echo "$DEV /var/lib/docker ext4 defaults,nofail 0 2" >> /etc/fstab
    # Install Docker Engine plus the compose plugin from Docker's convenience
    # script.
    curl -fsSL https://get.docker.com | sh
    # Generate the bootstrap admin password and the bundled database password
    # on first boot. These never leave this instance.
    ADMIN_PASS=$(openssl rand -hex 16)
    PGPASS=$(openssl rand -hex 24)
    umask 077
    {
      echo "POSTGRES_USER=keycloak"
      echo "POSTGRES_PASSWORD=$PGPASS"
      echo "POSTGRES_DB=keycloak"
      echo "KC_DB=postgres"
      echo "KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak"
      echo "KC_DB_USERNAME=keycloak"
      echo "KC_DB_PASSWORD=$PGPASS"
      echo "KC_BOOTSTRAP_ADMIN_USERNAME=admin"
      echo "KC_BOOTSTRAP_ADMIN_PASSWORD=$ADMIN_PASS"
      echo "# Set these and switch the compose command to 'start' before"
      echo "# pointing real applications at this identity provider:"
      echo "# KC_HOSTNAME=https://auth.example.com"
      echo "# KC_PROXY_HEADERS=xforwarded"
      echo "# KC_HTTP_ENABLED=true"
    } > /opt/auth-oidc/.env
    chmod 600 /opt/auth-oidc/.env
    cat <<'CREDS' > /opt/auth-oidc/INITIAL_ADMIN_PASSWORD.txt
    The bootstrap admin password is in /opt/auth-oidc/.env as
    KC_BOOTSTRAP_ADMIN_PASSWORD. Read it, then delete this file:
      sudo cat /opt/auth-oidc/.env | grep KC_BOOTSTRAP_ADMIN_PASSWORD
      sudo shred -u /opt/auth-oidc/INITIAL_ADMIN_PASSWORD.txt
    CREDS
    chmod 600 /opt/auth-oidc/INITIAL_ADMIN_PASSWORD.txt
    cd /opt/auth-oidc
    docker compose up -d

# Self-hosted OIDC identity provider (Keycloak)

Single compute instance running [Keycloak](https://www.keycloak.org), an open-source identity and access management server (a self-hosted alternative to Clerk or Auth0) on infrastructure you control. After apply, you create a realm and a client, register your application's redirect URIs, point a domain and a reverse proxy at the host, switch Keycloak to production mode, and wire your application to the realm's OIDC endpoints.


**Network class:** production — `external_network` defaults to `PublicStatic` for persisted floating IPs and multi-tier stacks; override with `PublicEphemeral` for ephemeral demos.

The instance provisions a private network, a floating IP, and a block volume mounted at `/var/lib/docker` so the realm and client data lives on a resizable volume. cloud-init installs Docker Engine and brings up Keycloak in `start-dev` bootstrap mode against a bundled PostgreSQL database.

## Where this fits

Keycloak is the identity layer behind any application that needs sign-in: OIDC and SAML, social login brokering, multi-factor authentication, and per-application clients, all on infrastructure you own rather than a metered SaaS. It is the self-hosted equivalent of Clerk or Auth0 in the [self-hosted vibecode stack](/resources/solutions/self-hosted-vibecode-stack).

## Why Keycloak over Authentik

Both are credible self-hosted OIDC providers. This template leads with Keycloak because it is the most widely deployed open-source identity server, has the longest track record in enterprise and Kubernetes environments, and its realm/client model maps directly onto the OIDC concepts most application frameworks already expect. [Authentik](https://goauthentik.io) is a reasonable alternative if you want a more opinionated, modern admin UI and do not need Keycloak's broader protocol surface (SAML, Kerberos brokering, fine-grained authorization services).

## Keycloak's HTTPS-before-real-login requirement

Keycloak's production `start` command refuses to issue real tokens over plain HTTP: it expects either a TLS certificate configured on the server itself, or `KC_HTTP_ENABLED=true` plus `KC_PROXY_HEADERS=xforwarded` when a reverse proxy terminates TLS in front of it. This template starts Keycloak in `start-dev` bootstrap mode instead, which tolerates plain HTTP so you can create your first realm and client without a domain in hand. The admin console and the `start-dev` server are gated to `app_allowed_cidr` (the private network by default); they are not the path real users sign in through. Switch to `start` with a domain and a reverse proxy before pointing a real application at this identity provider.

## Prerequisites

- OpenTofu >= 1.6.0 or Terraform >= 1.6.0
- Quake AI account with OpenStack credentials
- An existing SSH keypair in your project (the value of `key_name` must match that keypair)
- A domain you can point at the instance once you move off `start-dev`

## Resource baseline

Keycloak plus its bundled PostgreSQL runs on 4 vCPU and 4 GiB RAM. The default `s1a.medium` flavor leaves headroom for the JVM-based server. Size up for many realms or high token-issuance volume.

## Usage

1. Clone or copy this template directory
2. Copy `terraform.tfvars.example` to `terraform.tfvars` and fill in your values
3. Source your OpenStack credentials: `source openrc.sh`
4. Initialize: `tofu init`
5. Preview: `tofu plan`
6. Apply: `tofu apply`

After apply, cloud-init installs Docker, generates the bootstrap admin password and the database password into `/opt/auth-oidc/.env`, and starts Keycloak in `start-dev` mode. Read the bootstrap admin password over SSH:

```bash
sudo grep KC_BOOTSTRAP_ADMIN_PASSWORD /opt/auth-oidc/.env
```

No credential ships with this template: the bootstrap admin password and the database password are generated on first boot.

## Access and security

Keycloak listens on port 8080 over plain HTTP in bootstrap mode. The security group restricts 8080 to `app_allowed_cidr`, which defaults to the private network only. Ports 80 and 443 stay open for the reverse proxy you add before going to production; they carry no traffic until then.

## Moving to production

1. Point a domain's DNS A record at `floating_ip` and put a reverse proxy (Caddy or Nginx) in front for HTTPS on 443.
2. Edit `/opt/auth-oidc/.env`: uncomment and set `KC_HOSTNAME` to your public HTTPS address, `KC_PROXY_HEADERS=xforwarded`, and `KC_HTTP_ENABLED=true`.
3. Change the `keycloak` service's `command` in `/opt/auth-oidc/docker-compose.yml` from `start-dev` to `start`, then restart:

```bash
cd /opt/auth-oidc
sudo docker compose up -d
```

## Datastores

This template bundles PostgreSQL as a container on the same instance, which suits a single identity provider. To run it as a separate service, point `KC_DB_URL` in `/opt/auth-oidc/.env` at a [self-managed PostgreSQL](/resources/iac-templates/self-managed-postgres) instance and remove the bundled `postgres` service from the compose file.

## Variables

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key_name` | string | yes | n/a | SSH keypair name (must already exist in your project) |
| `flavor_name` | string | no | `s1a.medium` | Instance size (Keycloak plus PostgreSQL runs on 4 vCPU / 4 GiB) |
| `image_name` | string | no | `Ubuntu-24.04` | Operating system image |
| `app_name` | string | no | `auth-oidc` | Display name prefix for resources |
| `volume_size` | number | no | `20` | Block volume size in GiB, mounted at `/var/lib/docker` |
| `external_network` | string | no | `PublicStatic` | Persisted FIP / production default; override with `PublicEphemeral` for demos |
| `private_cidr` | string | no | `10.48.0.0/24` | CIDR for the private subnet |
| `app_allowed_cidr` | string | no | `10.48.0.0/24` | CIDR allowed to reach Keycloak on port 8080 |

## Outputs

| Name | Description |
| --- | --- |
| `floating_ip` | Public floating IP assigned to the instance |
| `private_ip` | Private IP address of the instance |
| `admin_console_url` | Keycloak admin console URL on port 8080 (bootstrap mode only) |
| `instance_id` | Compute instance ID |

## Scope

This is a single-VM Keycloak host that you operate, not a managed identity cloud. It is CPU-only and runs in one region. You operate the instance, Docker, Keycloak, PostgreSQL, and the data volume yourself: back them up, patch them, and watch resource use as you add realms and clients. For larger deployments, move PostgreSQL onto its own instance and run Keycloak in clustered mode, which this template does not set up.

## Documentation

See also: [self-managed PostgreSQL](/resources/iac-templates/self-managed-postgres), [Outline](/resources/iac-templates/outline-docs) (an existing OIDC consumer example)