Validate identity realm candidates

Author: RamazanKara

CHANGELOG.md

@@ -28,6 +28,7 @@
 - Added a reproducible Datadog example refresh target and checked-in full example output.
 - Added fixture integration evidence refs and validation coverage for integration evidence.
 - Added Forgejo migration candidate validation for the GitHub Enterprise assessment path.
+- Added identity realm/client candidate validation for the Okta/Auth0 assessment path.
 - Updated CI and release workflows to Node.js 24-native GitHub Actions.
 
 ## 0.1.0 - 2026-05-24

README.md

@@ -116,7 +116,7 @@ Included in the current implementation:
 - OpenTelemetry Collector sketch.
 - ArgoCD starter manifest.
 - Typed migration plan manifest and phase-gate Markdown plan.
-- Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, and Forgejo migration candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
+- Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, and identity realm/client candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
 - Evidence bundle export.
 - Evidence bundle path-safety checks that reject symlinks in exported project sections.
 - No-op assist provider and explicit opt-in LiteLLM assist.
@@ -160,7 +160,7 @@ The release checklist lives in `docs/release.md`. A release build should pass `m
 
 GitHub Enterprise to Forgejo collects repository, team, branch protection, Actions workflow, secret metadata, runner, deploy key, and GitHub App installation metadata from live GitHub/GitHub Enterprise APIs or local fixtures. It generates Forgejo migration assessment, CI compatibility, branch protection mapping, runner migration, repository ownership reports, and a validated Forgejo migration candidate YAML.
 
-Okta/Auth0 to Keycloak/Zitadel collects applications, SAML/OIDC client metadata, groups, policies, MFA settings, redirect URIs, owners, and break-glass account metadata from live Okta/Auth0 APIs or local fixtures. It generates identity migration risk, realm/client candidate config, break-glass, cutover, and rollback artifacts.
+Okta/Auth0 to Keycloak/Zitadel collects applications, SAML/OIDC client metadata, groups, policies, MFA settings, redirect URIs, owners, and break-glass account metadata from live Okta/Auth0 APIs or local fixtures. It generates identity migration risk, validated realm/client candidate config, break-glass, cutover, and rollback artifacts.
 
 Cloudflare/Akamai to Varnish/HAProxy/Coraza collects DNS records, WAF rules, cache rules, redirects, origins, TLS settings, bot rules, and page rules from live Cloudflare/Akamai APIs or local fixtures. The Akamai collector uses read-only EdgeGrid-authenticated calls for Edge DNS, Property Manager, and optional AppSec metadata. It generates VCL, HAProxy, Coraza, cache parity, and WAF enforcement review artifacts.
 

docs/cli.md

@@ -27,11 +27,11 @@ The CI test suite also runs this definition-of-done pipeline against the fixture
 
 The checked-in Datadog example can be refreshed with `make example VERSION=0.1.0-dev`. CI also runs `make example-smoke` as part of `make verify` to ensure the example fixture still completes the full pipeline.
 
-`openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
+`openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, identity realm/client candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
 
 `openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree.
 
-Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`.
+Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`; the identity path also supports `realm-client-candidate`.
 
 The GitHub Enterprise to Forgejo fixture path uses local JSON metadata:
 

docs/okta-auth0-to-keycloak-zitadel.md

@@ -61,4 +61,6 @@ Generated artifacts:
 - `identity-cutover-plan.md`
 - `identity-rollback-plan.md`
 
+Validation checks the identity realm/client candidate for source/target metadata, non-production safety flags, absence of credentials, realm provider metadata, application/client coverage, group coverage, policy coverage, MFA settings, break-glass account metadata, and preserved evidence refs.
+
 The assessment flags missing owners, missing group mappings, insecure redirect URIs, OIDC implicit grant usage, SAML signing metadata gaps, MFA policy gaps, weak MFA factors, and break-glass account issues.

docs/release.md

@@ -16,7 +16,7 @@ Release-blocking v0.1 requirements:
 - Markdown handover artifacts.
 - Grafana, Prometheus, OpenTelemetry, and ArgoCD candidate generators.
 - Typed migration plan manifest with assessment, pilot, shadow, and cutover phase gates.
-- Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, and Forgejo migration candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
+- Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, and identity realm/client candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
 - Evidence bundle export with checksums and OpenExit version metadata.
 - No-op AI assist and optional external assist behind explicit opt-in.
 - Documentation, examples, CI, release draft workflow, and reproducible release artifacts.
@@ -52,6 +52,7 @@ The AI provider path is complete for local fixture assessment workflows and incl
 - [ ] `validation/validation-report.md` includes `opentelemetry-candidate: passed` for the Datadog definition-of-done pipeline.
 - [ ] `validation/validation-report.md` includes `argocd-candidate: passed` for the Datadog definition-of-done pipeline.
 - [ ] `validation/validation-report.md` includes `forgejo-migration-candidate: passed` for the GitHub Enterprise to Forgejo pipeline.
+- [ ] `validation/validation-report.md` includes `identity-realm-client-candidate: passed` for the Okta/Auth0 to Keycloak/Zitadel pipeline.
 - [ ] `CHANGELOG.md` has a `0.1.0` section.
 - [ ] Exported bundle README includes version, commit, build date, bundle timestamp, and candidate warning.
 - [ ] Export refuses symlinks in exported project sections, including when `--force` is used.

internal/app/e2e_test.go

@@ -516,20 +516,7 @@ func TestValidationRejectsBrokenForgejoRepositoryCandidate(t *testing.T) {
 
 func TestIdentityFixturePipeline(t *testing.T) {
 	projectDir := filepath.Join(t.TempDir(), "identity-demo")
-	fixturePath := filepath.Join("..", "..", "testdata", "identity", "small.json")
-
-	commands := [][]string{
-		{"init", projectDir, "--source", "identity", "--target", "keycloak-zitadel"},
-		{"collect", "identity-fixture", "--project", projectDir, "--input", fixturePath},
-		{"assess", "--project", projectDir, "--target", "keycloak-zitadel"},
-		{"generate", "--project", projectDir, "--all"},
-		{"validate", "--project", projectDir},
-	}
-	for _, args := range commands {
-		if err := executeForTest(args...); err != nil {
-			t.Fatalf("openexit %s failed: %v", strings.Join(args, " "), err)
-		}
-	}
+	runIdentityFixturePipeline(t, projectDir)
 	for _, rel := range []string{
 		"inventory/openexit.inventory.yaml",
 		"mapping/openexit.mapping.yaml",
@@ -566,6 +553,67 @@ func TestIdentityFixturePipeline(t *testing.T) {
 			t.Fatalf("expected assessment finding %s", id)
 		}
 	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "identity-realm-client-candidate: passed") {
+		t.Fatalf("expected identity candidate validation marker, got:\n%s", string(report))
+	}
+}
+
+func TestValidationRejectsProductionReadyIdentityCandidate(t *testing.T) {
+	projectDir := filepath.Join(t.TempDir(), "identity-demo")
+	runIdentityFixturePipeline(t, projectDir)
+	candidatePath := filepath.Join(projectDir, "generated-config", "identity", "realm-client-candidate.yaml")
+	data, err := os.ReadFile(candidatePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupt := strings.Replace(string(data), "productionReady: false", "productionReady: true", 1)
+	if corrupt == string(data) {
+		t.Fatal("test fixture did not contain productionReady marker")
+	}
+	if err := os.WriteFile(candidatePath, []byte(corrupt), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeForTest("validate", "--project", projectDir); err == nil {
+		t.Fatal("expected validation to fail when identity candidate is marked production ready")
+	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "identity-realm-client-candidate") || !strings.Contains(string(report), "productionReady") {
+		t.Fatalf("expected identity candidate productionReady failure in validation report, got:\n%s", string(report))
+	}
+}
+
+func TestValidationRejectsBrokenIdentityClientCandidate(t *testing.T) {
+	projectDir := filepath.Join(t.TempDir(), "identity-demo")
+	runIdentityFixturePipeline(t, projectDir)
+	candidatePath := filepath.Join(projectDir, "generated-config", "identity", "realm-client-candidate.yaml")
+	data, err := os.ReadFile(candidatePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupt := strings.Replace(string(data), "clientId: api-web", "clientId: api-web-drifted", 1)
+	if corrupt == string(data) {
+		t.Fatal("test fixture did not contain clientId metadata")
+	}
+	if err := os.WriteFile(candidatePath, []byte(corrupt), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeForTest("validate", "--project", projectDir); err == nil {
+		t.Fatal("expected validation to fail when identity client candidate drifts from inventory")
+	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "identity-realm-client-candidate") || !strings.Contains(string(report), "clientId") {
+		t.Fatalf("expected identity candidate clientId failure in validation report, got:\n%s", string(report))
+	}
 }
 
 func TestEdgeFixturePipeline(t *testing.T) {
@@ -708,6 +756,23 @@ func runGitHubEnterpriseFixturePipeline(t *testing.T, projectDir string) {
 	}
 }
 
+func runIdentityFixturePipeline(t *testing.T, projectDir string) {
+	t.Helper()
+	fixturePath := filepath.Join("..", "..", "testdata", "identity", "small.json")
+	commands := [][]string{
+		{"init", projectDir, "--source", "identity", "--target", "keycloak-zitadel"},
+		{"collect", "identity-fixture", "--project", projectDir, "--input", fixturePath},
+		{"assess", "--project", projectDir, "--target", "keycloak-zitadel"},
+		{"generate", "--project", projectDir, "--all"},
+		{"validate", "--project", projectDir},
+	}
+	for _, args := range commands {
+		if err := executeForTest(args...); err != nil {
+			t.Fatalf("openexit %s failed: %v", strings.Join(args, " "), err)
+		}
+	}
+}
+
 func executeForTest(args ...string) error {
 	cmd := NewRootCommand()
 	cmd.SetArgs(args)

internal/generate/markdown.go

@@ -852,11 +852,15 @@ func writeIdentityRealmClientCandidate(ctx *Context) error {
 			"name":     inventory.Slug(ctx.Assessment.Metadata.Project),
 			"provider": ctx.Inventory.Source.Site,
 		},
-		"clients":            identityClientCandidates(ctx.Inventory.Assets.IdentityApps),
-		"groups":             identityGroupCandidates(ctx.Inventory.Assets.IdentityGroups),
-		"policies":           identityPolicyCandidates(ctx.Inventory.Assets.IdentityPolicies),
-		"mfaSettings":        identityMFACandidates(ctx.Inventory.Assets.MFASettings),
-		"breakGlassAccounts": identityBreakGlassCandidates(ctx.Inventory.Assets.BreakGlassAccounts),
+		"clients":                identityClientCandidates(ctx.Inventory.Assets.IdentityApps),
+		"groups":                 identityGroupCandidates(ctx.Inventory.Assets.IdentityGroups),
+		"policies":               identityPolicyCandidates(ctx.Inventory.Assets.IdentityPolicies),
+		"mfaSettings":            identityMFACandidates(ctx.Inventory.Assets.MFASettings),
+		"breakGlassAccounts":     identityBreakGlassCandidates(ctx.Inventory.Assets.BreakGlassAccounts),
+		"humanReviewRequired":    true,
+		"credentialsIncluded":    false,
+		"productionReady":        false,
+		"candidateGeneratedFrom": "redacted-openexit-inventory",
 	}
 	data, err := yaml.Marshal(candidate)
 	if err != nil {
@@ -865,7 +869,7 @@ func writeIdentityRealmClientCandidate(ctx *Context) error {
 	if err := os.WriteFile(filepath.Join(dir, "realm-client-candidate.yaml"), data, 0o644); err != nil {
 		return err
 	}
-	readme := "# Identity Candidate Config\n\nThis directory contains deterministic Keycloak/Zitadel candidate configuration derived from redacted identity inventory. Review every client, redirect URI, policy, and break-glass account before use.\n"
+	readme := "# Identity Candidate Config\n\nThis directory contains deterministic Keycloak/Zitadel candidate configuration derived from redacted identity inventory. It contains no client secrets, user passwords, MFA secrets, or token values, and it is not production-ready. Review every client, redirect URI, policy, MFA setting, and break-glass account before use.\n"
 	return os.WriteFile(filepath.Join(dir, "README.md"), []byte(readme), 0o644)
 }