ConnectSoft Identity Platform Federation¶
Federation allows users to authenticate through external providers while the ConnectSoft platform continues to issue its own internal tokens and enforce its own authorization model.
Provider Categories¶
| Category | Examples | Preferred protocol |
|---|---|---|
| Social providers | Google, Facebook | OAuth2/OIDC |
| Enterprise OIDC | Keycloak, Entra ID | OIDC |
| Enterprise SAML | AD FS, Keycloak, Entra ID | SAML 2.0 |
| Directory source | LDAP, Active Directory | LDAP bind, sync, or federation bridge |
| Mock providers | Mock social, enterprise, LDAP | Development-only adapter contracts |
Federation Broker Model¶
Authorization Server acts as the federation broker. It challenges external providers, validates external responses, and then asks Identity Service to resolve or provision an internal user. Identity Service owns the external account links and normalized identity state.
Backend services never authorize directly from external provider tokens or raw external groups.
External Account Link Model¶
Every external login must map to an internal user through a link record with at least:
| Field | Purpose |
|---|---|
| Provider | Stable provider key, such as google, facebook, keycloak-contoso, or entra-default. |
| Provider user id | External immutable subject. |
| Internal user id | ConnectSoft sub. |
| Tenant id | Tenant context when provider is tenant-bound. |
| Normalized email at linking time. | |
| Status | Active, pending, disabled, or requires review. |
Email is useful for discovery but must not be the only account binding key.
JIT Provisioning¶
JIT provisioning creates an internal user after successful federation when no link exists. A provider or tenant policy decides whether JIT is allowed.
Provisioning must normalize:
- internal user id;
- email and display name;
- tenant membership;
- external link;
- initial roles/groups according to mapping rules;
- MFA assurance state if trusted from provider.
If provisioning is not allowed, the platform returns account_link_required or routes to an approval workflow.
Account Linking¶
Account linking requires one of these controls:
- the user is already logged in locally and then adds an external provider;
- the user proves both local and external account ownership;
- an administrator links the account under an audited support workflow.
Email collision alone must not automatically link accounts.
Account Unlinking¶
Unlinking is allowed only when the user retains another valid login method or an administrator explicitly performs recovery. Unlink operations must be audited.
Claim and Group Normalization¶
External claims are mapped into internal platform concepts:
| External value | Internal value |
|---|---|
| Provider subject | Internal sub through account link |
| Provider email | Normalized email claim when trusted and scope allows |
| External group | Internal role/scope/permission assignment |
| External tenant/domain | Internal tenant membership |
| Upstream MFA indicator | Internal amr/acr only when provider trust policy allows |
Raw external groups should not be forwarded to backend services as authorization facts unless they are explicitly normalized.
Upstream MFA Trust¶
The platform may trust upstream MFA only when:
- provider is configured as trusted for MFA;
- tenant policy allows upstream MFA;
- the protocol response contains a verifiable MFA or assurance indicator;
- the authentication event is recent enough for the target operation.
If any condition fails, local step-up MFA is required.
LDAP and Active Directory Patterns¶
LDAP Bind Through Identity¶
Identity validates username/password against LDAP and then returns normalized internal user state to Authorization Server. This pattern is useful for legacy directories but does not make LDAP browser-facing.
LDAP Sync¶
Identity periodically syncs users and groups from LDAP/AD. Login can still occur through local credentials or federation, while authorization uses synced internal memberships.
Federation Bridge¶
Keycloak, Entra ID, or AD FS connects to LDAP/AD, and Authorization Server federates to that provider. This is the preferred enterprise model when SSO, conditional access, and upstream MFA are required.
Provider Notes¶
- Google and Facebook are social providers. They usually prove user identity but should not define enterprise roles.
- Keycloak can act as enterprise IdP, SAML bridge, OIDC provider, or LDAP-backed IdP.
- Entra ID is preferred for Microsoft enterprise SSO and conditional access.
- AD FS is supported for legacy enterprise SAML/WS-Fed environments.
- LDAP/AD is a directory and credential source, not a direct browser federation protocol.
Security Risks¶
| Risk | Control |
|---|---|
| Account takeover through email collision | Link by immutable provider subject plus proof/approval, not email alone. |
| Spoofed external groups | Normalize through provider-specific mapping and tenant policy. |
| Stale LDAP group membership | Sync with bounded TTL and re-evaluate sensitive operations. |
| External provider token leakage | Do not forward external tokens to backend APIs. Store only when delegated provider API access is explicitly required. |
| Upstream MFA over-trust | Require provider and tenant trust policy plus verifiable assurance claims. |