constructorfabric · mozhaev-dev · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
@@ -46,6 +46,22 @@ Secret.
 ==============================================================================
 */}}
 
+{{/*
+First-login provisioning preconditions. Checked OUTSIDE the credential-mode
+body below on purpose: `credentials.autoGenerate: false` is the documented
+GitOps path, where this file emits nothing and the config Secret is composed by
+deploy/gitops/scripts/compose-app-secrets.sh — a guard living inside that body
+would fall silent in exactly the mode that most needs it.
+*/}}
+{{- if .Values.authenticator.oidc.provisionOnLogin }}
+{{- if not ((.Values.global | default dict).tenantDefaultId) }}
+{{- fail "authenticator.oidc.provisionOnLogin=true requires global.tenantDefaultId — it feeds tenant_default_id in insight-identity-resolution-config, which the login bootstrap checks the token's tenant against before writing. Without it identity refuses every provision, so first-login sign-in would still fail. Set global.tenantDefaultId, or leave provisionOnLogin off." }}
+{{- end }}
+{{- if not .Values.identityResolution.deploy }}
+{{- fail "authenticator.oidc.provisionOnLogin=true requires identityResolution.deploy=true — the login bootstrap provisions by calling identity-resolution's internal route, and there is nothing to call when the service is not deployed." }}
+{{- end }}
+{{- end }}
+
 {{- if .Values.credentials.autoGenerate }}
 
 {{- /* Attempt lookup; on first install this returns nil. Helm 3 skips
@@ -220,6 +236,11 @@ stringData:
   # id_token claim carrying the IdP's stable external user id for source_type
   # (Entra: "oid"; the generic OIDC "sub" is not the same directory-stable id).
   APP__gears__authenticator__config__idp__external_id_claim: {{ .Values.authenticator.oidc.externalIdClaim | default "sub" | quote }}
+  # Provision a person on first login instead of refusing one the journal has
+  # no binding for yet. Off by default: it widens who may ENTER, so it is a
+  # deployment's policy to set. Identity still mints only for an account a
+  # connector has already observed, so the roster keeps deciding who exists.
+  APP__gears__authenticator__config__idp__provision_on_login: {{ .Values.authenticator.oidc.provisionOnLogin | default false | quote }}
   {{- with .Values.authenticator.oidc.scopes }}
   # Requested OIDC scopes (space-delimited; the gear splits on space/comma).
   # `offline_access` is what makes the IdP issue a refresh token — required for

@@ -384,6 +384,19 @@ authenticator:
     # id_token claim carrying the IdP's stable external user id for
     # sourceType (e.g. Entra's "oid"). Defaults to "sub".
     externalIdClaim: "sub"
+    # Provision a person on first successful login instead of refusing one the
+    # journal has no binding for yet.
+    #
+    # The login-bootstrap row is otherwise written only by the nightly
+    # persons-seed, which links a person by e-mail — so a roster member whose
+    # directory publishes no address (a GitHub member with a hidden e-mail, for
+    # one) cannot enter until an operator binds them by hand.
+    #
+    # Off by default because it widens who may ENTER. It does not widen who
+    # EXISTS: identity mints only for an account a connector has already
+    # observed, refuses one the source has closed, refuses one an operator
+    # excluded, and writes only under the tenant its own journal is keyed by.
+    provisionOnLogin: false
   # Honor `/auth/login?__override=<email>` (view-as, #1941): the session is
   # minted for that person instead of the authenticated one. Dev/demo
   # environments ONLY — MUST stay false anywhere real users log in.

@@ -253,6 +253,12 @@ authenticator:
                                       # for sourceType. Default "sub" is correct when `sub` itself is
                                       # that stable id; Entra needs "oid" instead (its `sub` is
                                       # pairwise-unique per client, NOT the directory-stable id).
+    # provisionOnLogin: true         # let a roster member enter on first login instead of waiting
+                                      # for the nightly persons-seed — which links by e-mail, so a
+                                      # member whose directory publishes none never gets a person.
+                                      # Note the indentation: this is authenticator.oidc.*, and a
+                                      # misplaced key is ignored in silence. See "First login
+                                      # provisioning" below before turning it on.
   # csrfOrigins: ["https://<HOST>"]  # fail-closed by default: if the UI's POST /auth/logout,
                                      # /auth/refresh or DELETE /auth/sessions return 403, set this
 
@@ -442,6 +448,21 @@ Other notable (non-placeholder) settings in this file:
 - Image tags are omitted deliberately. Each subchart renders `image.tag | default .Chart.AppVersion`, so a chart release already carries a tested set of product images. Set `<service>.image.tag` only to pin one service to a different build.
 - `credentials.deploymentMode: helm` and `credentials.autoGenerate: true` — this enables the "bring your own" credentials path, where the chart keeps a labelless `insight-db-creds` Secret instead of generating random passwords.
 - `identityResolution.deploy: true` — the chart default; don't flip it off.
+- `authenticator.oidc.provisionOnLogin` — **First login provisioning.** Off by
+  default. A person can sign in only once `persons` holds a `value_type='id'`
+  row binding their IdP external id to a person, and that row is written by the
+  nightly persons-seed, which groups accounts **by e-mail**. A roster member
+  whose directory publishes no address therefore never gets one: they
+  authenticate at the IdP and are still refused, until an operator binds them by
+  hand in Manage → Identities. Turning this on lets identity mint the person
+  during the login itself. It widens who may **enter**, not who **exists** —
+  identity mints only for an account a connector has already observed, refuses
+  one the source has closed, refuses one an operator excluded as not-a-person,
+  and writes only under the tenant its own journal is keyed by — so
+  `global.tenantDefaultId` is required, and the chart refuses to render without
+  it rather than leaving the switch on and inert. The minted person carries
+  the source-native id alone until the next seed run attaches the roster's name
+  and org placement to it.
 - `authenticator.tlsDiscovery.issuerRef.name` — the cert-manager `ClusterIssuer` the JWKS-discovery Certificate is issued from. Always set this: the chart ships `local-ca`, which is the self-signed root that `make bootstrap-cert-manager ENV=local` creates for the local k3s sandbox, not anything a real cluster has.
 - There is no auth-off toggle anywhere in this chart. `authenticator.oidc.issuerUrl` and `authenticator.oidc.redirectUri` are hard `required` fields, so a real IdP is a prerequisite; install Keycloak as a separate release if the stand has none. The bundled `keycloak` subchart is wired for this repo's own environments (roster realm, config-cli-managed content) and not a substitute here.
 

@@ -123,6 +123,12 @@ gears:
         tenant_claim: "tenant_id"
         # Fallback tenant for a claim-less IdP (e.g. Okta); empty = fail closed.
         default_tenant_id: ""
+        # Mint a person on first login instead of refusing one the journal has
+        # no binding for yet (the nightly persons-seed links by e-mail, so a
+        # roster member without one never gets a binding). Off here: the
+        # compose stand seeds `persons` up front, so nothing needs it — turn it
+        # on to exercise the path.
+        provision_on_login: false
       # Service tokens (§10 G1 / DD-AUTH-05). The token endpoint runs on its own
       # listener (token_bind_addr) so it never shares the main port. Service
       # tokens are always tenant-scoped; the caller names the tenant.

@@ -148,6 +148,9 @@ AUTH_SOURCE_TYPE=$(yq -r '.authenticator.oidc.sourceType // ""' "$VALUES")
 # id_token claim carrying the IdP's stable external user id for source_type
 # (Entra: "oid"; the generic OIDC "sub" is not the same directory-stable id).
 AUTH_EXTERNAL_ID_CLAIM=$(yq -r '.authenticator.oidc.externalIdClaim // "sub"' "$VALUES")
+# Off unless a values file says otherwise: it widens who may enter, and the
+# chart-rendered path defaults it the same way.
+AUTH_PROVISION_ON_LOGIN=$(yq -r '.authenticator.oidc.provisionOnLogin // false' "$VALUES")
 # `__override` view-as login (insight#1941/#1944) — dev/demo stands ONLY.
 AUTH_OVERRIDE_ENABLED=$(yq -r '.authenticator.overrideEnabled // false' "$VALUES")
 AUTH_EXPERIMENTS_ENABLED=$(yq -r '.authenticator.experimentsEnabled // false' "$VALUES")
@@ -280,6 +283,7 @@ stringData:
   APP__gears__authenticator__config__idp__default_tenant_id: "${AUTH_DEFAULT_TENANT_ID}"
   APP__gears__authenticator__config__idp__source_type: "${AUTH_SOURCE_TYPE}"
   APP__gears__authenticator__config__idp__external_id_claim: "${AUTH_EXTERNAL_ID_CLAIM}"
+  APP__gears__authenticator__config__idp__provision_on_login: "${AUTH_PROVISION_ON_LOGIN}"
   APP__gears__authenticator__config__redirect_uri: "${AUTH_REDIRECT_URI}"
   APP__gears__authenticator__config__oidc_scopes: "${AUTH_SCOPES}"
   APP__gears__authenticator__config__service_tokens__audience: "${AUTH_TOKEN_AUD}"

@@ -320,6 +320,11 @@ services:
       APP__gears__identity_resolution__config__clickhouse_database: "${CLICKHOUSE_DATABASE:-insight}"
       APP__gears__identity_resolution__config__clickhouse_user: "${CLICKHOUSE_USER:-insight}"
       APP__gears__identity_resolution__config__clickhouse_password: "${CLICKHOUSE_PASSWORD:-insight-local}"
+      # The tenant this journal is keyed by. The seed already passes it per
+      # invocation; the SERVICE needs it too, because a write that has no
+      # caller context to infer a tenant from (the login bootstrap) checks the
+      # asserted one against this rather than trusting it.
+      APP__gears__identity_resolution__config__tenant_default_id: "${TENANT_DEFAULT_ID:-00000000-df51-5b42-9538-d2b56b7ee953}"
     volumes:
       - type: bind
         source: ./deploy/compose/build/identity-resolution/identity-resolution

@@ -304,9 +304,17 @@ pub async fn callback(
         tracing::info!(session_id = %old_sid, "session-fixation guard: revoked presented session");
     }
 
-    // Resolve the internal person. Unknown -> 403 (first-admin bootstrap / RBAC
-    // are out of step-04 scope; local dev seeds the persons table).
-    let resolution = match state.resolver.resolve(&idp.identity).await {
+    // Identity requires a connector to have observed the principal before it
+    // mints, so this decides who waits for the batch, not who exists.
+    let resolved = match state.resolver.resolve(&idp.identity).await {
+        Ok(Some(p)) => Ok(Some(p)),
+        Ok(None) if state.cfg.idp.provision_on_login => {
+            state.resolver.provision(&idp.identity).await
+        }
+        other => other,
+    };
+
+    let resolution = match resolved {
         Ok(Some(p)) => p,
         Ok(None) => {
             tracing::warn!(

@@ -71,6 +71,10 @@ pub struct IdpConfig {
     /// to `sub` (fine for IdPs where `sub` IS the stable directory id, e.g.
     /// Keycloak).
     pub external_id_claim: String,
+    // INVARIANT: off by default — it widens who may ENTER, which is a
+    // deployment's policy to set. Identity refuses to mint for a principal no
+    // connector has observed, so it never widens who exists.
+    pub provision_on_login: bool,
     /// Fallback tenant when the id_token carries no tenant claim at all (e.g.
     /// Okta). Empty = no fallback: the gateway JWT gets an empty `tenant_id`
     /// and downstream services fail closed. Interim until the Identity
@@ -115,6 +119,7 @@ impl Default for IdpConfig {
             tenant_claim: "tenant_id".to_owned(),
             source_type: String::new(),
             external_id_claim: "sub".to_owned(),
+            provision_on_login: false,
             default_tenant_id: String::new(),
             extra_ca_cert_path: String::new(),
             hosts: HashMap::new(),

@@ -78,6 +78,18 @@ pub trait PersonResolver: Send + Sync {
     /// # Errors
     /// Fails when the Identity Service is unreachable or errors.
     async fn resolve(&self, id: &IdpIdentity) -> anyhow::Result<Option<PersonResolution>>;
+
+    /// Resolve, minting a person when the journal has no binding yet.
+    /// `Ok(None)` = still unknown, and the caller denies the login.
+    ///
+    /// # Errors
+    /// Fails when the Identity Service is unreachable or errors.
+    // INVARIANT: the default refuses, so a resolver without minting power
+    // fails closed rather than by omission.
+    async fn provision(&self, id: &IdpIdentity) -> anyhow::Result<Option<PersonResolution>> {
+        let _ = id;
+        Ok(None)
+    }
 }
 
 /// `PersonResolver` backed by the Identity Service.
@@ -111,6 +123,16 @@ struct ResolveProfile {
     insight_source_id: Option<Uuid>,
 }
 
+// INVARIANT: only a normal login may provision. The `__override` view-as
+// resolves by an email its operator typed, and minting there would turn a typo
+// into a person to become.
+fn provisionable_external_id(target: &ResolveTarget) -> Option<&str> {
+    match target {
+        ResolveTarget::ExternalId(external_id) => Some(external_id),
+        ResolveTarget::Email(_) => None,
+    }
+}
+
 impl IdentityPersonResolver {
     /// `base_url` is the Identity Service root, e.g. `http://identity:8082`.
     /// `keystore` / `issuer` / `audience` are used to mint the service JWT that
@@ -206,6 +228,43 @@ impl IdentityPersonResolver {
         .await
     }
 
+    async fn provision_person_by_external_id(
+        &self,
+        external_id: &str,
+        tenant_id: &str,
+    ) -> anyhow::Result<Option<Uuid>> {
+        if self.base_url.is_empty() {
+            return Ok(None);
+        }
+        let url = format!("{}/internal/persons/provision", self.base_url);
+        let token = self.mint_service_token(tenant_id)?;
+        let resp = self
+            .http
+            .post(&url)
+            .bearer_auth(token)
+            .json(&serde_json::json!({
+                "source_type": self.source_type,
+                "external_id": external_id,
+                "tenant_id": tenant_id,
+            }))
+            .send()
+            .await
+            .context("Identity provision request")?;
+        // INVARIANT: only 404 means "no such principal". Folding any other
+        // status into it would dress a broken deployment up as an ordinary
+        // access denial, which is the version nobody diagnoses.
+        let status = resp.status();
+        if status == reqwest::StatusCode::NOT_FOUND {
+            return Ok(None);
+        }
+        anyhow::ensure!(
+            status.is_success(),
+            "Identity returned {status} for /internal/persons/provision"
+        );
+        let profile: ResolveProfile = resp.json().await.context("decode ResolveProfile")?;
+        Ok(profile.insight_source_id.filter(|id| !id.is_nil()))
+    }
+
     /// Admin `__override` (view-as) lookup: resolve by email — an operator
     /// types an email, not an IdP external id. A DISTINCT route from the
     /// login-bootstrap lookup above (never dispatched from the same call).
@@ -243,4 +302,65 @@ impl PersonResolver for IdentityPersonResolver {
             tenant_id: id.tenant_id.clone(),
         }))
     }
+
+    async fn provision(&self, id: &IdpIdentity) -> anyhow::Result<Option<PersonResolution>> {
+        let Some(external_id) = provisionable_external_id(&id.resolve_by) else {
+            return Ok(None);
+        };
+        let person_id = self
+            .provision_person_by_external_id(external_id, &id.tenant_id)
+            .await?;
+        Ok(person_id.map(|person_id| PersonResolution {
+            person_id: person_id.to_string(),
+            tenant_id: id.tenant_id.clone(),
+        }))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// A resolver with no minting power at all — the trait default is what a
+    /// future implementation inherits, so it must refuse rather than forget.
+    struct LookupOnly;
+
+    #[async_trait]
+    impl PersonResolver for LookupOnly {
+        async fn resolve(&self, _id: &IdpIdentity) -> anyhow::Result<Option<PersonResolution>> {
+            Ok(None)
+        }
+    }
+
+    fn identity(resolve_by: ResolveTarget) -> IdpIdentity {
+        IdpIdentity {
+            sub: "subject".to_owned(),
+            email: "someone@example.com".to_owned(),
+            tenant_id: Uuid::from_u128(7).to_string(),
+            resolve_by,
+        }
+    }
+
+    #[test]
+    fn only_a_login_is_provisionable_never_the_view_as_override() {
+        assert_eq!(
+            provisionable_external_id(&ResolveTarget::ExternalId("octocat".to_owned())),
+            Some("octocat"),
+        );
+        assert_eq!(
+            provisionable_external_id(&ResolveTarget::Email("typo@example.com".to_owned())),
+            None,
+            "an operator's typed email must never mint the person it names",
+        );
+    }
+
+    #[tokio::test]
+    async fn a_resolver_without_minting_power_fails_closed() -> anyhow::Result<()> {
+        let provisioned = LookupOnly
+            .provision(&identity(ResolveTarget::ExternalId("octocat".to_owned())))
+            .await?;
+
+        assert!(provisioned.is_none());
+        Ok(())
+    }
 }