Microsoft Entra ID

Prerequisites

Complete the preparation checklist.

Application setup

1. In Entra ID > App registrations, create an application for Accounts in this organizational directory only.
2. Under Authentication, select Add a platform > Web. Add these Redirect URIs:
   • Sign-in callback: https://api.<platform-host>/identity/callback.
   • Sign-out return: https://<platform-host> and any other approved frontend addresses. Use Web redirect URIs for these, not the front-channel logout field.
3. Under Certificates & secrets, create a client secret and save its Value, not its Secret ID.
4. If assignments are required, assign users through Enterprise applications > Users and groups.

Replace <platform-host> with your Istari domain, for example istari.example.com. If the API uses a different hostname or base URL, use the configured callback address.

Collected values

Collect Application (client) ID, Directory (tenant) ID, and the secret Value. Use the directory GUID in the issuer below. For other Microsoft clouds use the directory's published tenant-specific issuer. Never use common, organizations, or consumers. Collect each person's immutable Object ID (oid) from their user record, separately from application configuration.

Installation configuration

istari-values.yaml (excerpt)

identity:
  oidc:
    provider: entra
    issuer: "https://login.microsoftonline.com/<directory-tenant-guid>/v2.0"
    clientId: "<client-id>"
    clientAuthMethod: client_secret_basic
    scopes: "openid profile email offline_access"
  idpMigration:
    enabled: false

Store ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_CLIENT_SECRET in the Identity Service Secret. Set ISTARI_DIGITAL_IDENTITY_SERVICE_ENROLLMENT_POLICY=pre-registered-only.

Account preparation

Use authoritative Object ID mappings before sign-in. For a new user, include email,upstream_subject,tenant_slug in the shared import and set upstream_subject to their oid. For an existing user, link their old subject to oid with the subject mapping import. The directory ID (tid) validates the issuer; neither it nor groups/app roles selects an Istari tenant. Tenancy comes from the person's Istari membership.

See account import commands and administrator setup.

Verification

Confirm the token's upstream subject corresponds to the expected oid, the local principal and tenant match preparation, and a user without a prepared mapping cannot gain access. Test refresh and return from logout against the registered URLs.

Limitations

Both client_secret_basic and client_secret_post are supported. The default policy does not trust Entra email for account linking; these recipes use subject imports. No Microsoft Graph permission, directory-reading credential, group claim, or app role is required for normal sign-in. See Microsoft's registration guide.