keycloak¶
Keycloak 26 — OAuth 2.0, OpenID Connect and SAML, with users, realms, clients and social logins — backed by its own Postgres so what you configure survives a restart.
spin up keycloak # http://localhost:8096
spin open keycloak # the admin console
spin cli keycloak -- get realms --fields realm
Ports¶
| Service | Host port | Container | Env var |
|---|---|---|---|
| Keycloak | 8096 |
8080 | KEYCLOAK_PORT |
| Postgres | not published | 5432 | — |
The database is Keycloak's own and is deliberately not published. When you
want a Postgres of your own, spin up postgres is the one with 5432 and a
GUI.
Credentials¶
| What | Default |
|---|---|
| Admin user | spinup |
| Admin password | spinup |
Created once, on an empty database. Changing KEYCLOAK_ADMIN_PASSWORD
afterwards does nothing — change it in the console, or spin destroy
keycloak and start over.
Wiring an app to it¶
Issuer http://localhost:8096/realms/master
Discovery http://localhost:8096/realms/master/.well-known/openid-configuration
Authorization http://localhost:8096/realms/master/protocol/openid-connect/auth
Token http://localhost:8096/realms/master/protocol/openid-connect/token
Most OIDC libraries need only the issuer and will find the rest. In the
console, create a realm of your own rather than using master — master is
where the admins live, and its tokens are short-lived by design.
A quick check that it is really answering:
curl -s -X POST http://localhost:8096/realms/master/protocol/openid-connect/token \
-d client_id=admin-cli -d username=spinup -d password=spinup -d grant_type=password
Storage¶
keycloak-db holds everything — realms, clients, users, the admin account.
spin down keycloak keeps it; spin destroy keycloak deletes it and the
next start is a first start.
Notes¶
start-dev, notstart: the production command needs a TLS certificate and a build step, and refuses to run without a hostname. Dev mode is HTTP, no hostname strictness, and it is otherwise the same server — realms exported from it import into a real one.- The
sslRequiredfix. Keycloak'smasterrealm ships withsslRequired=EXTERNAL, which rejects plain HTTP from any address it does not think is private — and behind Docker Desktop's port forwarding your own machine is one of those. Left alone,curl http://localhost:8096/realms/...answers403 {"error":"invalid_request","error_description":"HTTPS required"}and the admin console cannot log in, while the very same request from inside the container works. Thekeycloak-setupone-shot runskcadm.sh update realms/master -s sslRequired=NONEonce the server is healthy. It is idempotent, runs on every start and shows asExited (0)inspin ps. A realm you create yourself needs the same setting — it is on the realm's Login tab as "Require SSL". - The healthcheck is bash's
/dev/tcpagainst/health/readyon the management port, 9000. The image is UBI micro with a JVM in it: no curl, no wget, andCMD-SHELLwould run undersh, which has no/dev/tcp. KC_BOOTSTRAP_ADMIN_USERNAME/_PASSWORD, notKEYCLOAK_ADMIN/KEYCLOAK_ADMIN_PASSWORD. The old names were deprecated in 26.0 and are ignored, silently, leaving a server with no way in.spin cli keycloakiskcadm.sh, which needs to log in first:spin shell keycloak, then./bin/kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user spinup --password spinup.- Keycloak takes around 35 seconds to become healthy — a JVM, a database migration and a realm import on the first start.