Install IDEN for your organization¶

This page takes you from an empty directory to a working deployment with a signed-in administrator, and then checks every part of it before anyone else is let in.

Budget about thirty minutes: ten to get it running, twenty to walk through the verification at the end. Everything runs in Docker, so the only thing you install on the host is Docker itself.

What you are installing¶

Six containers. docker compose builds and wires all of them.

A seventh service, migrate, runs the database migrations to completion and then exits. It is a separate service rather than a startup step inside the provider so that running two provider replicas does not run the migrations twice, concurrently, against the same database.

One deployment serves one organization. There is no tenant concept anywhere, and your own staff are the administrators rather than a vendor's — see Single-organization by design.

Before you start¶

Docker with Compose. That is the only requirement. docker compose version should answer.

Decide your hostname now. If this is going anywhere but your laptop, settle on the URL people will use before step 3, not after. The issuer is baked into every token and compared character for character, so changing it later invalidates every token and session in circulation.

Throughout this page, https://iden.example.org stands for that hostname. On a laptop the defaults already work and you can leave every value alone.

1. Get the code¶

git clone https://github.com/yephonekyaw/iden.git
cd iden

Every command below runs from this directory unless it says otherwise.

2. Generate a signing key¶

IDEN signs every token it issues with an RSA private key that you own. It refuses to start without one, and it will not generate one silently — a key that appears by magic is a key whose provenance nobody can account for.

Build the provider image first, then run the key generator inside it. This way you do not need Python on the host:

docker compose -f deploy/docker-compose.yml build provider

mkdir -p provider/keys
docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD/provider/keys:/keys" -e IDEN_SIGNING_KEY_DIR=/keys \
  --entrypoint python iden-dev-provider:latest -m scripts.gen_keys

Wrote signing key: /keys/iden-20260907.pem (kid: iden-20260907)

Check it worked: ls provider/keys/ shows one .pem file.

The filename stem becomes the key's kid, and keys sort by name — which is what makes rotation a matter of adding a file rather than running a migration.

3. Configure¶

Everything the deployment needs is in deploy/docker-compose.yml.

cp deploy/.env.example deploy/.env

IDEN_ENV=prod                              # Secure cookie, HSTS, no /docs
IDEN_ISSUER=https://iden.example.org
IDEN_AUTH_UI_BASE_URL=https://iden.example.org
IDEN_ALLOWED_ADMIN_ORIGINS=[]

Why these are compared exactly¶

Getting one of them wrong produces a sign-in loop rather than an error message, which is why they are worth reading carefully.

Naming your organization¶

Both frontends show whose sign-in page this is. Set it on auth-ui and dashboard:

environment:
  IDEN_ORG_NAME: "Example University"
  IDEN_ORG_LOGO_URL: "https://example.org/logo.svg"   # optional

The organization takes the larger type and IDEN drops to a caption beneath it. Leave IDEN_ORG_NAME empty and IDEN stands alone. Both are read at container start rather than baked in at build time, so one image serves any deployment.

Give IDEN_ORG_NAME to the provider service as well — deploy/docker-compose.yml already does. It is the name an authenticator app files a TOTP credential under, so someone who enrolls sees Example University: you@example.org beside their code rather than the issuer URL.

Putting it behind one hostname¶

All three belong on one origin, so the session cookie is unambiguously first-party:

Two of those are fixed rather than chosen. Discovery must be at the host root, which is why IDEN_API_PREFIX must stay empty. And the dashboard cannot be at the root: the provider's API owns /admin/* and the dashboard's own admin screens have the same names, so on one origin /admin/users has to be either the API or the page.

deploy/nginx/iden.conf.example is a tested configuration for exactly this. Deployment explains what any proxy has to do — particularly IDEN_FORWARDED_ALLOW_IPS, without which every caller looks like the proxy.

To put that origin on the internet with no inbound port at all, follow Behind a Cloudflare Tunnel.

4. Start everything¶

docker compose -f deploy/docker-compose.yml up -d --build

cp deploy/nginx/iden.conf.example deploy/nginx/iden.conf

docker compose -f deploy/docker-compose.yml \
               -f deploy/docker-compose.tunnel.yml up -d --build

The first build takes a few minutes. Startup then runs in a fixed order: PostgreSQL, Redis and SeaweedFS come up and report healthy, migrate creates the schema and exits, and only then does the provider start.

Check it worked:

docker compose -f deploy/docker-compose.yml ps

Six services running, and migrate shown as exited (0). If migrate exited non-zero, nothing else will work — read docker compose -f deploy/docker-compose.yml logs migrate before going on.

Then ask the provider itself:

curl -s http://localhost:8000/health

{"status": "ok", "database": "ok", "redis": "ok"}

degraded here names the dependency that is not answering.

5. Create the first administrator¶

The schema exists but is empty. The seed fills it: IDEN's own permission catalogue, the two starting roles, one administrator, and two clients.

docker compose -f deploy/docker-compose.yml exec provider python -m scripts.seed

Seeded 28 system scopes across 3 APIs.

  Bootstrap administrator — shown once, change it after first login
    email:    admin@localhost
    password: _qajl3wRjjx6QsuXMO9YY5tw

  Kiosk client secret — shown once, it is hashed in the database
    client_id:     kiosk
    client_secret: 7ZJbgK2um1y9QeliyysqElTJ-SUhC_8R8aXRygrmUgM

docker compose -f deploy/docker-compose.yml exec \
  -e IDEN_BOOTSTRAP_ADMIN_PASSWORD='...' provider python -m scripts.seed

What it created¶

The seed is idempotent — re-run it any time, including after an upgrade that ships new permissions. Running it again on a seeded database prints Nothing new to create and leaves existing credentials untouched. It creates nothing structural; that is Alembic's job.

6. Point the dashboard client at your hostname¶

Skip this on a laptop — the seeded client already allows http://localhost:3000/console/callback and http://localhost:5173/console/callback.

Anywhere else, the dashboard client's redirect URIs still name localhost, and the sign-in will loop until they name your origin.

This is a bootstrap problem: the Clients screen and the admin API both edit this, and both need you to be signed in — which is the thing that is broken. So do it in the database:

docker compose -f deploy/docker-compose.yml exec -T postgres \
  psql -U iden -d iden -c \
  "update clients set redirect_uris = ARRAY['https://iden.example.org/console/callback']
   where client_id = 'dashboard';"

redirect_uris is a PostgreSQL array (character varying[]), not JSON, so it is ARRAY[...] and not a bracketed string — a JSON literal fails with malformed array literal. Note /console/callback: the dashboard's redirect URI moved with the app.

Check it worked. A wrong value here presents as a sign-in loop rather than an error, so it is worth ten seconds now:

docker compose -f deploy/docker-compose.yml exec -T postgres \
  psql -U iden -d iden -c \
  "select client_id, redirect_uris from clients where client_id = 'dashboard';"

 client_id |                redirect_uris
-----------+---------------------------------------------
 dashboard | {https://iden.example.org/console/callback}

Once you can sign in, the dashboard's Clients page is the place to change this. The admin API can too, though it identifies a client by its UUID rather than by dashboard, so it takes a lookup first:

curl -X PATCH https://iden.example.org/admin/clients/{uuid} \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"redirectUris": ["https://iden.example.org/console/callback"]}'

7. Sign in¶

Open http://localhost:3000/console/ — or your own hostname. Either way / redirects there, so the bare address works too.

You are redirected to the sign-in page, and back to the dashboard afterwards. That round trip is the whole system working: the dashboard is an ordinary OIDC client of the provider, with no special path of its own.

Change the bootstrap password immediately, under Security. A password that was printed to a terminal and pasted into a chat window is not a password.

Check every part works¶

Fifteen minutes, entirely through the two applications. Each row exercises a different part of the system, and the order matters — later rows depend on earlier ones.

Signing in¶

That fourth row is worth pausing on. Once an authenticator is enrolled, IDEN asks for the code on every sign-in, whatever the application requested — see Assurance.

Self-service¶

That last screen is the one worth looking at twice. It answers why can this person do that? — and it is the same view administrators get for anyone else.

Administration¶

The parts that are supposed to refuse¶

A system that only works when you do the right thing has not been tested.

The last three are the ones people skip. The refusals are the product.

Set up your organization¶

In the order that avoids rework:

1. Profile fields — what you record about people beyond name and email. Everyone's profile form is built from this, so define it before you add anyone.
2. APIs and scopes — register each backend that will trust IDEN, and define the permissions it understands.
3. Roles — bundle those permissions into job functions. Name them after the job, not after the permissions they happen to contain.
4. Groups — your departments and teams. Give them roles; membership does the rest.
5. People — add them, put them in groups. Direct grants exist for genuine exceptions, not as the normal path.
6. Your applications — register each one and choose what it may request.

Before you let anyone else in¶

Work through Before you expose it in full. The short version: TLS with IDEN_ENV=prod, a proxy doing flood protection, the bootstrap password changed, and the signing keys backed up somewhere that is not this server.

Common problems¶

sudo chown 1000:1000 provider/keys

cd provider && uv run python -m scripts.gen_keys

More in Troubleshooting.