Archigov · docs
  1. Docs
  2. Guides

Sign-In with Microsoft Entra ID

Configure OpenID Connect sign-in with Microsoft Entra ID, and map app roles to system roles, the platform admin flag and board seats.

#How Sign-in Works

With AUTH_MODE=entra, every request except /api/health, /api/auth/* and inbound webhooks requires a signed-in session. Archigov uses the OpenID Connect authorization code flow with PKCE; the ID token is verified against Microsoft's published keys (issuer, tenant, audience, expiry and nonce). The user's identity is <tenant id>:<object id> — never the email address, which can change.

An unauthenticated API call receives 401 {"error":"sign_in_required","login_url":…} and the UI sends the browser to sign in.

#1. Register the Application

In the Entra admin centre, App registrations → New registration:

  • Name: Archigov
  • Supported account types: accounts in this organisational directory only
  • Redirect URI (Web): https://archigov.example.org/api/auth/callback

Under Certificates & secrets, create a client secret (or omit it and use a public client with PKCE).

#2. Define App Roles

Under App roles, create roles whose values Archigov understands:

ValueGrants
authorThe author system role
auditorThe auditor system role
serviceThe service system role (read-only)
platform_adminThe platform admin flag
DA:chair, DA:decision_maker, PCB:reviewer …A seat on a board, as <BOARD CODE>:<seat>
board/DA/secretaryThe same, in path form

Seats are chair, decision_maker, reviewer, secretary and observer. Values are case-insensitive. For a dotted value such as archigov.author, the last segment is used.

Assign the roles to users or groups under Enterprise applications → Archigov → Users and groups.

Note

A user holds at most one system role; if several are present the first wins. The system role and the platform admin flag follow the app roles on every sign-in. A seat value creates or updates that seat at sign-in (a board code that does not exist is skipped), but removing the app role does not remove the seat — remove it on the board. Areas of responsibility are always managed in the product, on each board.

#3. Configure Archigov

Env
AUTH_MODE=entra
APP_BASE_URL=https://archigov.example.org
ENTRA_TENANT_ID=<directory (tenant) id>
ENTRA_CLIENT_ID=<application (client) id>
ENTRA_CLIENT_SECRET=<secret>      # omit for a public client

Optional:

VariablePurpose
ENTRA_ROLE_MAPRemap existing role values, e.g. arb.chair=DA:chair,archigov.owner=platform_admin
ENTRA_DEFAULT_ROLEThe system role for users whose token carries none. Unset: no system role (read-only, plus any seats)
SESSION_SECRETSession-cookie signing secret. Generated into /data/keys/session.secret when unset

Older role names are accepted as aliases: admin (platform admin flag only), architect, engineer and submitter (author), chair (author + DA chair), reviewer (author + DA reviewer), board_member (DA decision maker).

#4. Check

Restart the container, open the instance, and sign in. The account panel shows the system role, the platform admin flag and the seats you hold. Every sign-in and sign-out is written to the audit log.

#Troubleshooting

SymptomLikely cause
Redirect URI mismatchThe registration's redirect URI must equal APP_BASE_URL + /api/auth/callback exactly
Signed in, but cannot do anythingNo app role assigned, and ENTRA_DEFAULT_ROLE unset — the user is read-only
id_token tenant mismatchENTRA_TENANT_ID is not the tenant the user signed in to
Cookie not kept behind a proxyAPP_BASE_URL must be the public HTTPS URL