mitgliederverwaltung/docs/admin-bootstrap-and-oidc-role-sync.md

Admin Bootstrap and OIDC Role Sync

Overview

• Admin bootstrap: In production, the Docker entrypoint runs migrate, then Mv.Release.run_seeds/0 (skips if admin user already exists unless FORCE_SEEDS=true; set RUN_DEV_SEEDS=true to also run dev seeds), then seed_admin/0 from ENV, then the server. Password can be changed without redeploy via bin/mv eval "Mv.Release.seed_admin()".
• OIDC role sync: Optional mapping from OIDC groups (e.g. from Authentik profile scope) to the Admin role. Users in the configured admin group get the Admin role on registration and on each sign-in.

Admin Bootstrap (Part A)

Environment Variables

• RUN_DEV_SEEDS – If set to "true", run_seeds/0 also runs dev seeds (members, groups, sample data). Otherwise only bootstrap seeds run.
• FORCE_SEEDS – If set to "true", seeds are run even when the admin user already exists (e.g. after changing bootstrap data such as roles or custom fields). Otherwise seeds are skipped when bootstrap was already applied.
• ADMIN_EMAIL – Email of the admin user to create/update. If unset, seed_admin/0 does nothing.
• ADMIN_PASSWORD – Password for the admin user. If unset (and no file), no new user is created; if a user with ADMIN_EMAIL already exists (e.g. OIDC-only), their role is set to Admin (no password change).
• ADMIN_PASSWORD_FILE – Path to a file containing the password (e.g. Docker secret).

Release Tasks

• Mv.Release.run_seeds/0 – If the admin user already exists (bootstrap already applied), skips unless FORCE_SEEDS=true; otherwise runs bootstrap seeds (fee types, custom fields, roles, settings). If RUN_DEV_SEEDS env is "true", also runs dev seeds (members, groups, sample data). Safe to call on every start.
• Mv.Release.seed_admin/0 – Reads ADMIN_EMAIL and password from ADMIN_PASSWORD or ADMIN_PASSWORD_FILE. If both email and password are set: creates or updates the user with the Admin role. If only ADMIN_EMAIL is set: sets the Admin role on an existing user with that email (for OIDC-only admins); does not create a user. Idempotent.

Entrypoint

• rel/overlays/bin/docker-entrypoint.sh – After migrate, runs run_seeds(), then seed_admin(), then starts the server.

Seeds (Dev/Test)

• priv/repo/seeds.exs – Uses ADMIN_PASSWORD or ADMIN_PASSWORD_FILE when set; otherwise fallback "testpassword" only in dev/test.

OIDC Role Sync (Part B)

Configuration

• OIDC_ADMIN_GROUP_NAME – OIDC group name that maps to the Admin role. If unset, no role sync.
• OIDC_GROUPS_CLAIM – JWT claim name for group list (default "groups").
• Module: Mv.OidcRoleSyncConfig (oidc_admin_group_name/0, oidc_groups_claim/0).

Sign-in page (OIDC-only mode)

• OIDC_ONLY (or Settings → OIDC → "Only OIDC sign-in") – When set to true/1/yes and OIDC is configured, the sign-in page shows only the Single Sign-On button (password login is hidden). ENV takes precedence over Settings.

Sync Logic

• Mv.OidcRoleSync.apply_admin_role_from_user_info(user, user_info) – If admin group configured, sets user role to Admin or Mitglied based on user_info groups.

Where It Runs

1. Registration: register_with_oidc after_action calls OidcRoleSync.
2. Sign-in: sign_in_with_oidc prepare after_action calls OidcRoleSync for each user.

Internal Action

• User.set_role_from_oidc_sync – Internal update (role_id only). Used by OidcRoleSync; not exposed.

See Also

• .env.example – Admin and OIDC group env vars.
• lib/mv/release.ex – seed_admin/0.
• lib/mv/oidc_role_sync.ex – Sync implementation.
• docs/oidc-account-linking.md – OIDC account linking.