Build a Small Identity Lab with Authentik or Keycloak

Expected Outcome

A working isolated identity Lab with one chosen provider, non-default generated bootstrap secrets, a test user/application boundary, and a documented teardown path.

Assumptions

• A Linux host or workstation with Docker Engine and Docker Compose v2.

• At least 2 CPU cores and 2 GB RAM for an Authentik test deployment; allow more resources if running other Lab services.

• A browser that can reach the chosen provider's local or Lab-only endpoint.

• This is a Lab: do not expose development-mode Keycloak or an unprotected Authentik setup directly to the internet.

Bill of Materials

• Official Authentik Docker Compose bundle if choosing Track A.

• Official Keycloak container image if choosing Track B.

• A password manager or other secure temporary place for generated Lab bootstrap credentials.

• One disposable test user and one disposable application/client definition.

Build Steps

1. Choose one provider for the exercise

   Use Authentik when you want to practice its application/provider/outpost model, or Keycloak when you want to practice realms, clients, and users. Do not run two incomplete identity platforms merely to satisfy the Lab title; choose one and prove a full flow.

2. Track A — download Authentik's official Compose definition

   Authentik's current Docker Compose installation is intended for test and small-scale deployments. Download the current Compose file from Authentik documentation rather than inventing a single-container Authentik service, because the supported bundle includes the dependencies and wiring Authentik actually requires.

   Changes system state: review before running

   mkdir -p ~/identity-lab/authentik && cd ~/identity-lab/authentik
   curl -fLo compose.yml https://docs.goauthentik.io/compose.yml
   grep -E '^(services:|  [a-zA-Z0-9_-]+:)' compose.yml | head -40
   openssl rand -base64 36 | tr -d '\n' | sed 's/^/PG_PASS=/' > .env
   printf '\nAUTHENTIK_SECRET_KEY=' >> .env && openssl rand -base64 60 | tr -d '\n' >> .env && printf '\n' >> .env
   chmod 600 .env
   docker compose -f compose.yml config --quiet

3. Track A — start and validate Authentik

   Pull and start the exact services defined by the downloaded Authentik bundle. Complete the initial setup at the documented port, set the akadmin password, then create one test user and one application/provider using the current First Steps workflow.

   Changes system state: review before running

   cd ~/identity-lab/authentik
   docker compose pull
   docker compose up -d
   docker compose ps
   curl -I http://127.0.0.1:9000/ || true

4. Track B — run a current Keycloak development container

   For the Keycloak track, use the current official container and start-dev only for an isolated Lab. Generate the bootstrap password rather than publishing the documentation's literal admin/admin example. Replace <KEYCLOAK_VERSION> with the current reviewed release tag before running the container.

   Changes system state: review before running

   mkdir -p ~/identity-lab/keycloak && cd ~/identity-lab/keycloak

   Manual or UI step

   • export KC_BOOTSTRAP_ADMIN_USERNAME=labadmin

   • export KC_BOOTSTRAP_ADMIN_PASSWORD=$(openssl rand -base64 24)

   Changes system state: review before running

   printf 'Temporary Keycloak bootstrap user: %s\n' "$KC_BOOTSTRAP_ADMIN_USERNAME"
   docker run --name keycloak-lab --rm -d -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME -e KC_BOOTSTRAP_ADMIN_PASSWORD quay.io/keycloak/keycloak:<KEYCLOAK_VERSION> start-dev
   docker logs keycloak-lab --tail 50

5. Track B — create a realm, user, and client

   Open the Keycloak Admin Console through http://127.0.0.1:8080, create a non-master Lab realm, create a disposable test user with a password, and register an OpenID Connect client. The Keycloak getting-started guide uses its test application to prove the authorization-code flow; follow that current flow rather than treating an admin-console login as SSO validation.

6. Validate the chosen identity flow

   For Authentik, sign in through the application/provider you created and verify the intended user is admitted. For Keycloak, sign in to the registered test client using the Lab realm user. Record the issuer/realm, client/application name, user, and successful redirect so the evidence proves an application authentication flow—not merely that the admin UI loaded.

7. Test recovery boundaries

   Confirm you know which generated secret or bootstrap credential is disposable and which provider state would need to be backed up for persistence. This Lab deliberately stops short of claiming database backup or production high availability; those require provider-specific recovery procedures.

Validation

• Only one provider track needs to be active for the Lab to pass.

• The chosen provider starts from its current official container/Compose path without legacy `docker-compose` commands.

• No literal default admin password from an example is reused as a durable credential.

• A disposable non-admin user authenticates through a test application/client flow.

• The operator can identify which endpoint is Lab-only and why it must not be exposed as a production identity service.

Troubleshooting

• For Authentik, inspect the official Compose service state and logs before changing container topology or mounting host timezone files.

  Read-only command: verify target and scope

  docker compose -f ~/identity-lab/authentik/compose.yml ps
  docker compose -f ~/identity-lab/authentik/compose.yml logs --tail=100

• For Keycloak, confirm the container is running with `start-dev`, the reviewed image tag was substituted, and the bootstrap environment variables were present at first start.

  Read-only command: verify target and scope

  docker ps --filter name=keycloak-lab
  docker logs keycloak-lab --tail 100

• If the admin UI works but the test application does not, inspect redirect URIs, issuer/realm selection, client type, and the user's realm membership before changing the identity platform itself.

Cleanup or Rollback

• Authentik track: preserve anything you intentionally want to keep, then stop the Lab without deleting volumes unless you have explicitly decided the provider state is disposable.

  Changes system state: review before running

  cd ~/identity-lab/authentik && docker compose down

• Keycloak track: because the example container is intentionally ephemeral, stopping it removes the container and its Lab state.

  Read-only command: verify target and scope

  docker stop keycloak-lab

• Delete or rotate temporary bootstrap credentials after the Lab and remove any copied `.env` file from insecure locations.

Next Improvements

• Move from development/test mode to the provider's production deployment guide before exposing an identity service beyond the Lab.

• Add TLS, a supported production database, backup/restore, monitoring, and upgrade procedures before treating the identity platform as infrastructure.

• Integrate a real non-critical application only after the disposable client flow is understood.

References

• Authentik — Docker Compose installation
• Authentik — First steps
• Keycloak — Getting started with Docker
• Keycloak — Running Keycloak in a container