Deploy a self-hosted identity provider with the auth-oidc template

Stand up Keycloak, an open-source OIDC identity provider, on a single Quake AI instance using the validated OpenTofu template auth-oidc. You apply the template, sign in to the bootstrap admin console, create a realm and a client, point a domain at the host and serve it over HTTPS, switch Keycloak to production mode, and register a redirect URI for a test application.

Keycloak keeps your sign-in flows on infrastructure you own. You run it yourself; this is a self-hosted tool you operate, not a managed service.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the auth-oidc template directory from the template reference page.
• A domain you can point at the instance once you move off the start-dev bootstrap.

Step 1: Apply the template#

Copy the template's example variables file and set key_name:

cp terraform.tfvars.example terraform.tfvars

key_name = "YOUR_KEY_NAME"

Initialize, preview, and apply:

tofu init
tofu plan
tofu apply

OpenTofu provisions a private network, a router, a security group, a block volume mounted at /var/lib/docker, an instance, and a floating IP. On first boot, cloud-init installs Docker Engine, generates the bootstrap admin password and the database password into /opt/auth-oidc/.env, and starts Keycloak in start-dev mode against the bundled PostgreSQL.

Read the outputs and record floating_ip:

tofu output

Step 2: Read the bootstrap admin password and sign in#

SSH to the instance and read the generated password:

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

Open http://YOUR_FLOATING_IP:8080 (reachable from app_allowed_cidr, the private network by default; tunnel over SSH if you set it to the default). Sign in to the Administration Console with username admin and the password you read above.

Step 3: Create a realm and a client#

1. In the top-left realm selector, select Create realm. Name it for your application (for example myapp).
2. Inside the new realm, go to Clients > Create client.
3. Set Client type to OpenID Connect, give it a Client ID (for example myapp-web), and continue.
4. Enable Client authentication if your application can hold a secret (confidential client), or leave it off for a public client (a single-page app).
5. Set Valid redirect URIs to your application's callback path, for example https://app.example.com/auth/callback. You can update this later once you have a real domain.
6. Save. If you enabled client authentication, open the Credentials tab and record the client secret.

Step 4: Point a domain at the host and serve HTTPS with Caddy#

Keycloak's production mode refuses to issue tokens over plain HTTP, so it needs a domain with TLS before real applications sign users in through it.

1. Create a DNS A record for your domain (for example auth.example.com) pointing at YOUR_FLOATING_IP. Follow How to point a domain at a Quake AI resource. Wait until it resolves:

dig +short auth.example.com

1. SSH to the instance and create /opt/auth-oidc/Caddyfile:

auth.example.com {
  reverse_proxy 127.0.0.1:8080
}

1. Add Caddy to /opt/auth-oidc/docker-compose.yml:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    network_mode: host
    volumes:
      - /opt/auth-oidc/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
volumes:
  caddy_data:

For background on certificates, see How to issue and auto-renew a TLS certificate with Let's Encrypt.

Step 5: Switch to production mode#

Edit /opt/auth-oidc/.env and uncomment the production block:

KC_HOSTNAME=https://auth.example.com
KC_PROXY_HEADERS=xforwarded
KC_HTTP_ENABLED=true

Edit /opt/auth-oidc/docker-compose.yml and change the keycloak service's command from start-dev to start. Then restart:

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

Step 6: Verify the realm and update the redirect URI#

1. Confirm the realm's OIDC discovery document resolves over your domain:

curl -s https://auth.example.com/realms/myapp/.well-known/openid-configuration | head

1. In the admin console, update the client's Valid redirect URIs to your application's real production callback, now that you have a domain.
2. Point your application's OIDC client library at the discovery URL above, with the client ID (and secret, for a confidential client) from Step 3.

What you built#

• Applied the auth-oidc template to provision a network, security group, data volume, instance, and floating IP, with Keycloak and PostgreSQL started by cloud-init
• Created a realm and a client in Keycloak's admin console
• Served Keycloak over HTTPS by pointing a domain at the floating IP and routing it through a Caddy reverse proxy
• Switched Keycloak from start-dev to production start mode, which Keycloak requires before it issues real tokens over HTTPS
• Verified the realm's OIDC discovery document and updated the client's redirect URI for production use

Scope of this deployment#

This template runs a single-VM Keycloak host, not a managed identity cloud. The instance is CPU-only and runs in one region, and it bundles PostgreSQL as a container on the same host. You operate the instance, Docker, Keycloak, the database, and the data volume yourself: back them up, patch them, and snapshot the volume before you resize or rebuild. For larger deployments, move PostgreSQL onto its own instance and run Keycloak in clustered mode, which this template does not set up.

Next steps#

• Self-hosted OIDC identity provider template: the template reference, parameters, and resource map
• Self-managed PostgreSQL template: the database to point at when you outgrow the bundled one
• Deploy Outline with the outline-docs template: a worked example of an application that consumes an OIDC provider like this one
• Self-hosted vibecode stack: where auth fits in the broader self-hosted stack
• Security hardening checklist: tighten SSH access and exposure before you serve real traffic

Clean up#

When you no longer need the deployment, destroy everything the template created:

tofu destroy

Then remove the DNS A record you created in Step 4 and any client registrations your test application held. Because Keycloak, its database, and the realm data all live on the instance and its attached volume, tofu destroy removes them along with the infrastructure. Export your realm configuration first if you want to keep it: Realm settings > Action > Partial export.