Identity federation

Available in the standalone edition since version 1.78.0.

Your people can sign in with the accounts they already have. AarView’s identity provider stays in place as a broker: it sends the user to your IdP (OpenID Connect, authorization code with PKCE), checks the answer, and gives AarView its usual session. Local accounts (akadmin included) keep working. SAML is not supported.

1. Register AarView at your IdP as a web application (confidential client), with this redirect URI:

https://<AARVIEW_DOMAIN>/source/oauth/callback/sso/

• Microsoft Entra ID: App registrations > New registration, platform Web, the redirect URI above. Certificates & secrets > New client secret. Token configuration > Add groups claim > Security groups (or Groups assigned to the application, which avoids the 200-group limit), in the ID token: the claim carries group object ids. Optional claims > ID token: email. Note the tenant id (Overview).
• Okta: Applications > Create App Integration > OIDC > Web Application, sign-in redirect URI above, grant type Authorization Code. Sign On > OpenID Connect ID Token > Groups claim type Filter, claim name groups (for example Matches regex .*, or only your SOC groups). Assign the people or groups to the application.
• Any OpenID Connect provider (Keycloak, Authentik, ADFS 2019+, Google Workspace…): a confidential client, the redirect URI above, and a groups claim in the id_token (or another claim, see AARVIEW_FEDERATION_GROUPS_CLAIM).

2. Set in .env and run ./install.sh again:

Setting	Value
AARVIEW_FEDERATION	entra, okta or oidc
AARVIEW_FEDERATION_ISSUER	Entra: https://login.microsoftonline.com/<tenant id>/v2.0 (never common or organizations, which accept any tenant). Okta: https://<org>.okta.com or https://<org>.okta.com/oauth2/<server id>
AARVIEW_FEDERATION_CLIENT_ID, AARVIEW_FEDERATION_CLIENT_SECRET	from the registration
AARVIEW_FEDERATION_GROUP_MAP	<IdP group>=<role> separated by ;, role super_admin, admin or analyst. Entra: object ids; Okta: group names
AARVIEW_FEDERATION_MFA	authentik (default) or idp, see below

Optional: AARVIEW_FEDERATION_NAME (button label), AARVIEW_FEDERATION_GROUPS_CLAIM (roles for Entra app roles), AARVIEW_FEDERATION_SCOPES (groups by default for Okta), AARVIEW_FEDERATION_TOKEN_AUTH (post_body for Entra, basic_auth otherwise), AARVIEW_FEDERATION_CA_CERT (/certs/<file>, an IdP with a private CA). The installer checks every value before building, reads your IdP’s discovery document, and refuses to continue if the issuer it publishes is not exactly the one you set. Empty AARVIEW_FEDERATION and re-run: the button disappears.

Who gets in, with which role. Deny by default: a person who is in none of the mapped groups is refused at the IdP broker and gets no account. A mapped person gets the highest mapped role, in your own tenant (AARVIEW_OPERATOR_TENANT); the role is re-read at every sign-in, so moving someone between groups at your IdP takes effect at their next sign-in. A person removed from every mapped group cannot sign in again; a session already open ends within AarView’s session limits (30 minutes idle, 8 hours). Your IdP’s group names are never copied: a group named “authentik Admins” or “aarview-super-admin” at your IdP means nothing, and no mapping can target an identity provider administrator group. Federated accounts are always your staff; client accounts stay local.

Accounts are matched by the IdP’s subject (sub), never by e-mail or username. An e-mail address in an id_token is not proof of ownership at every IdP, and matching on it would let an IdP account take over a local one (the administrator’s, for instance). If a local account already has the same username or e-mail as a federated person, that person is refused until you remove or rename the local account: one person, one account.

Second factor. AARVIEW_FEDERATION_MFA=authentik (default): federated users also enrol AarView’s own second factor (TOTP) at their first sign-in, whatever your IdP did. idp: AarView trusts your IdP’s MFA, but only when the signed id_token proves it: amr contains mfa, or two kinds of factor (for example pwd and otp), or acr is one of AARVIEW_FEDERATION_MFA_ACR. Without that proof the sign-in is refused, never let through. Okta puts amr in its id_tokens. For Entra, check that your tokens carry it before choosing idp; if they do not, keep authentik.

Every id_token is verified (signature with the IdP’s published keys, audience, exact issuer, expiry), and its subject must match the userinfo subject. Refusals are logged with their reason: docker compose logs authentik-server | grep aarview-federation.

Good to know: a first sign-in abandoned during the second-factor enrolment is picked up again at the next attempt by the same IdP subject, never by anyone else. Federated accounts have no AarView password, so the password-protected self-service screens (changing one’s own factor) do not apply to them: an administrator resets a lost factor. A private CA for your IdP (AARVIEW_FEDERATION_CA_CERT) must carry the keyUsage extension (keyCertSign): the identity provider’s TLS stack refuses a CA without it.

What was tested, what was not. The federation test bench runs the whole browser path against a local test OIDC provider (TLS, PKCE) and checks mapped, unmapped and hostile identities (55 checks). It was not tested against real Entra ID or Okta tenants: the registration steps above follow their documentation, and the first sign-in at your site is the real check.