Architecture

Authority first. Transport second. Automation third.

FreeSCIM is a mediation layer between systems with different responsibilities. It does not become trustworthy by centralizing every credential. It becomes trustworthy by making the owner of each decision explicit.

profile authoritySCIM mediationLinux enforcementevidence plane
SourceOktaHuman auth, MFA, profile lifecycle, SCIM assignment.
FS
Control planeFreeSCIM

Protocol mediation, policy, mapping, sync, audit.

Target authorityFreeIPADirectory, Kerberos, POSIX, groups, HBAC, Linux access.
Durable statePostgreSQLsync + mappingsAuditactions + outcomesDriftreconciliationHealthreadiness
System contract

Five responsibilities, five explicit owners.

Most identity outages become harder when teams cannot tell which system was supposed to make the decision. FreeSCIM keeps that answer visible.

Human authenticationOkta handles user authentication, MFA, and the preferred SAML production path.
Provisioning transportSCIM carries lifecycle intent over bearer-authenticated HTTP into the mediation layer.
Mediation and policyFreeSCIM normalizes fields, checks scope, applies guards, tracks sync, and records evidence.
Linux enforcementFreeIPA owns directory state, Kerberos, POSIX identity, groups, HBAC, sudo policy, and hosts.
Primary data flow

A user lifecycle request is transformed, not blindly forwarded.

The bridge exists because Okta profile semantics and FreeIPA directory semantics are related, but not identical.

01SCIM requestOkta sends the lifecycle transaction with bearer authentication.
02NormalizeIdentifiers and SCIM or flat profile attributes map into a stable internal contract.
03GuardValidation, scope, ETag behavior, redaction, and mutation policy run before apply.
04Directory adapterFreeIPA receives only the bounded operation through LDAP/LDAPS or an approved agent path.
05EvidenceSync state, audit, health, mappings, drift, and downstream checks preserve the result.
Password path

Password material is a transaction, never a standing data source.

When password push is eventually enabled for an approved scope, FreeSCIM can inspect and apply the secret only inside the incoming provisioning transaction.

INBOUND

Receive only when Okta pushes it.

There is no architecture where FreeSCIM later downloads a user’s current cleartext password. The secret can only arrive inside a qualifying SCIM transaction.

SAFETY

Detect, redact, gate, discard.

Password material must not enter logs, SQL, evidence payloads, command-line arguments, or later replay storage. Guardrails decide whether any write is allowed.

ENFORCEMENT

HBAC remains separate.

Even after password authority changes, a synchronized credential does not grant host access. FreeIPA authorization policy remains authoritative.

Federation model

SAML stays primary while OIDC is introduced as a governed parallel path.

The current architecture does not require a disruptive protocol replacement to validate new trust capabilities.

SAML / PRODUCTION

Preferred human SSO path

Okta authenticates the user, FreeSCIM validates the federation response, and mapped roles determine administrative session access.

OIDC / GOVERNED

Parallel readiness and broker work

OIDC RP and broker capabilities can be validated behind enablement flags without removing the SAML ACS or changing the identity authority.

SESSIONS / EVIDENCE

One observable session model

Authentication method, identity provider, trust path, role mapping, failures, and key readiness can be surfaced in one operator view.

Extensions

Operational integrations connect beside the core identity path, not through it.

Foreman, Puppet, topology, remote support, and database controls can contribute context and evidence without inheriting identity authority.

Sanitized FreeSCIM system context showing identity, directory, infrastructure and evidence relationships
System context is useful only when each relationship retains its transport and authority label.
Architectural rule

Do not centralize what only needs to be correlated.

FreeSCIM centralizes policy visibility, mapping, evidence, and lifecycle coordination. It leaves credentials, Linux enforcement, and provider-specific authority where they belong.

See capability boundariesInspect the security model