# Test enterprise SSO on your laptop before you meet the client's IT

> One Keycloak container and a realm JSON file are enough to walk into the meeting with a login flow that already works.

Original: https://fdetimes.net/en/tools/keycloak-local-sso-testing-fde/

When an application goes into an enterprise, the client's IT team will sooner or later ask: which identity system will their users sign in through, and how?

If that is the moment you first open the OIDC documentation, the meeting turns into a lesson. Keycloak lets you arrive with a login flow already running on your own laptop.

This is not a niche tool. Keycloak is an open-source IAM project under the Apache 2.0 licence, and in April 2023 the CNCF's technical oversight committee voted to accept it as an incubating project.

The reason FDEs need it lies elsewhere. WorkOS observes that testing SSO the traditional way requires an IdP account and test users, which takes real effort. For an FDE, that account usually belongs to the client's IT team and may not have been granted when the project starts, while you still have to show that the application can integrate.

## What can Keycloak do for you in the field?

The Keycloak homepage sets the goal of adding authentication to applications with minimal effort. More important for an FDE, it is built on standard protocols: OpenID Connect, OAuth 2.0 and SAML, the same protocols the client's IdP uses.

That is why many teams use it as a practice ground. PuppyGraph's documentation runs a local Keycloak as a stand-in IdP, with an OIDC client and a test user set up in advance, so readers can walk through the whole SSO flow without a production IdP.

Artemis, the platform from the Technical University of Munich (TUM), does the same: a Keycloak container loads a ready-made realm in place of the university's production OIDC provider.

Picture yourself about to deploy an internal tool for a bank that uses Entra. Before the meeting, you already know which redirect URI the application needs, which claims it reads for email and user groups, and what fails when a token expires. The questions you bring to IT become far more specific.

## One command for an IdP on your machine

The official Docker getting-started page runs Keycloak in development mode and creates an admin account whose username and password are both `admin`. The command looks like this:

```bash
docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  <keycloak-image-from-official-guide> start-dev
```

The `` part is for you to fill in. Open keycloak.org/getting-started/getting-started-docker, find the `docker run` command in the step that starts Keycloak, and copy the full image name with its version tag, which sits just before `start-dev`. Check the admin environment variable names against the page too, since they can change between releases.

Then open the admin console, create a realm for a "mock customer", an OIDC client for your application and a few users, point your application at that realm and try signing in.

At this point you only have a hand-built IdP. Next time you start it, or when a colleague wants to run it, every click in the admin console has to be repeated from scratch.

## Turn the IdP into a file anyone can rebuild

Keycloak solves this with realm import. The official documentation says a realm can be loaded at server start-up with the `--import-realm` option, and for containers the import directory is `/opt/keycloak/data/import`.

Artemis is an example worth copying. It pins the Keycloak version in its compose file and loads the realm from a JSON file in the repository on every start.

A minimal version of the same idea could look like the one below. The key points are that the repository's `realms/` directory is mounted into the container's import directory and the start command adds `--import-realm`. The path comes from the current documentation; check it against the documentation for the image version you use.

```yaml
services:
  keycloak:
    image: ${KEYCLOAK_IMAGE}   # image name + pinned version, taken from Keycloak's Docker page
    command: start-dev --import-realm
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./realms:/opt/keycloak/data/import   # check this path against the docs for your version
```

To make this file run, create a `.env` file next to the compose file with exactly one line: `KEYCLOAK_IMAGE=` followed by the image and tag you copied from the Docker page. Commit that `.env` file as well: the pinned tag is what lets colleagues build exactly the same IdP as you, rather than a newer release that behaves differently.

The `realms/mock-customer.json` file needs only one client and one test user for a trial run. The illustrative excerpt below keeps the essentials; a real export from the admin console is much longer:

```json
{
  "realm": "mock-customer",
  "enabled": true,
  "clients": [
    {
      "clientId": "your-app",
      "publicClient": true,
      "redirectUris": ["http://localhost:3000/callback"]
    }
  ],
  "users": [
    {
      "username": "employee1",
      "email": "employee1@mock-customer.test",
      "enabled": true,
      "credentials": [{ "type": "password", "value": "test", "temporary": false }]
    }
  ]
}
```

The approach to follow: configure the realm by hand once, export it to JSON, add accounts that play the client's actual user groups (staff, managers, admins), then commit the file to the repository alongside the compose file. From then on, anyone on the team who runs `docker compose up` gets the same IdP, and the demo does not depend on anyone's memory.

**Key point:** Do not let the meeting with the client's IT team be the first time your application meets a real IdP.

## Three easy mistakes on the first build

Most of the time lost building a local IdP goes not on Keycloak itself but on a few small details. The table below lists what to check first when sign-in does not work.

| Symptom | Common cause | Fix |
|---|---|---|
| Sign-in succeeds but is rejected on return to the application | The redirect URI declared in the client does not match the address the application actually calls | Compare character by character: scheme, port, path, trailing `/` |
| Edits to the realm JSON file do not show after a restart | The realm already exists on the server, so the import step is skipped | Rebuild from a clean instance or delete the old realm before importing |
| Keycloak starts but no realm is loaded | `--import-realm` was left out, or the volume does not point at the right import directory | Check the start command and mount path against the docs for the version in use |

The first mistake is common OIDC experience, and it will come back in the client's environment. The second comes straight from Keycloak's rules: if the realm already exists, the import is skipped. Write both into the README so colleagues do not lose an afternoon.

## A laptop cannot replace the client's IdP

The first limit is in the start command itself. Development mode with `admin/admin` suits a local machine only; never let that configuration slip into any client environment.

The second limit is fundamental. SSOJet puts it bluntly: Keycloak runs locally with a single `docker run` command, but it behaves like Keycloak, not like Okta or Entra. Claim names, group configuration and policies can differ from one IdP to another.

SSOJet also describes the rhythm many teams choose: use a mock IdP during development and in CI, then test once against the client's real IdP before launch. That is how to plan: the laptop confirms that the application handles the standard flow correctly, and the session with IT is reserved for the client's specific details.

So do not start by learning every Keycloak feature. Get the basic OIDC flow solid first: realm, client, redirect URI, token and claim. Once you understand them on Keycloak, you will read the documentation of any enterprise IdP faster.

## Final exercise: does the "managers" group really reach the token?

Most enterprise applications ask not only "who signed in" but also "which group does this person belong to". This is the exercise to do before calling your environment finished.

In the `mock-customer` realm, create a `managers` group and assign it to a new test account, such as `manager1`. Configure the client so group information is included in the token, then sign in as `employee1` and `manager1` in turn. Decode each user's ID token and compare: only `manager1`'s token should carry the `managers` group claim.

Once you see that claim, have the application read it to unlock or block an admin page, then export the realm again so the new group lives in the JSON file. You now have the most specific question for the client's IT team: which claim does their IdP send group information in, and under what name?

## A small repository is worth more than a line in your skills list

A repository containing a sample application, a compose file and a realm JSON with ready-made test users is evidence an FDE recruiter can run themselves. On your CV, write it as an outcome: built a reproducible SSO environment to test OIDC integration before connecting to the client's IdP.

Next time your calendar shows a "kickoff with IT", spend an evening on Keycloak beforehand. You will walk into the room with the right questions instead of a list of unknowns.

**Try this week:**

- Run Keycloak in Docker following the official getting-started page, sign in to the admin console, then create a realm and an OIDC client for your application.
- Export the new realm to a .json file, add a few test accounts, then rebuild from a clean instance with --import-realm to make sure everything is reproducible.
- Write a short README so colleagues can run this IdP again without asking you a single question.

## Sources

- [Docker - Keycloak](https://www.keycloak.org/getting-started/getting-started-docker)

- [Keycloak](https://www.keycloak.org/)

- [Keycloak joins CNCF as an incubating project](https://cncf.io/blog/2023/04/11/keycloak-joins-cncf-as-an-incubating-project)

- [GitHub - keycloak/keycloak: Open Source Identity and Access Management For Modern Applications and Services](https://github.com/keycloak/keycloak)

- [Importing and exporting realms - Keycloak](https://www.keycloak.org/server/importExport)

- [Setting Up SSO with Keycloak - PuppyGraph Docs](https://docs.puppygraph.com/getting-started/setting-up-sso-with-keycloak/)

- [Keycloak OIDC Setup for Local Development | Welcome to the Artemis Documentation](https://docs.artemis.tum.de/developer/keycloak-oidc-setup)

- [Test SAML SSO Locally Without an Okta or Entra Tenant](https://ssojet.com/blog/test-saml-sso-locally-without-idp-tenant)

- [Introducing Test SSO, an easier way to integrate SSO into your app](https://www.workos.com/blog/introducing-test-sso)
