Tenant Identity & Federation
Summary
Keymate supports Tenant-scoped identity provider (IdP) configuration, allowing each Tenant to federate authentication with its own enterprise identity systems. Federation settings are isolated per Tenant — one Tenant's IdP configuration does not affect another Tenant's authentication flow. This capability is provided by the underlying Keycloak platform, which Keymate leverages as part of its multi-tenant model.
Why It Exists
Enterprise Tenants require that their users authenticate through their own corporate identity provider rather than creating separate credentials. A healthcare organization may use a SAML-based IdP, while a technology company uses OpenID Connect. Tenant-scoped federation enables each organization to bring its own identity infrastructure without forcing a single IdP model on all Tenants.
Where It Fits in Keymate
Tenant identity and federation sits alongside the Tenant Model as a Tenant-level configuration concern. It connects to Membership & Application Assignment — users provisioned through federation become members of the Tenant that configured the IdP. It also feeds into Org-Aware Tokens & Sessions, as federated users receive tokens with the same organizational context as directly authenticated users.
Boundaries
What this concept covers:
- Tenant-scoped IdP configuration as a product capability
- Federation isolation between Tenants
- Supported federation protocol families (SAML, OpenID Connect, LDAP)
- Just-in-time provisioning and attribute mapping
What this concept does not cover:
- Federation protocol implementation details — refer to Keycloak documentation for protocol-specific configuration
- Identity provider management API — see platform API reference
- Tenant provisioning workflows — see Tenant Onboarding
How It Works
Tenant-Scoped IdP Configuration
Each Tenant can configure one or more identity provider connections through the admin console or management API. Configurations are scoped to the Tenant — they apply only to users authenticating within that Tenant's context.
Supported Protocol Families
Keymate supports the federation protocol families provided by Keycloak:
- SAML 2.0 — for enterprise IdPs using the Security Assertion Markup Language
- OpenID Connect — for modern OAuth 2.0 / OIDC-based identity providers
- LDAP / Active Directory — for directory-based authentication
Each protocol family supports its own set of configuration parameters (endpoint URLs, certificates, client credentials) as defined by Keycloak.
Attribute Mapping and Group Synchronization
When a user authenticates through a federated IdP, the platform maps external claims and attributes to Keymate's internal identity model. Tenant administrators configure these mappings to control how external identity attributes translate into Keymate user attributes. Group synchronization can be configured to align external group memberships with Keymate groups.
Just-in-Time Provisioning
Federated users can be provisioned on first login — the platform creates a user record and Tenant membership based on the federated identity and configured mapping rules. This eliminates the need to pre-create accounts for every federated user.
Federation Isolation
Federation configurations are strictly isolated per Tenant. One Tenant's IdP settings, attribute mappings, and provisioning rules have no effect on other Tenants. Each Tenant's authentication flow operates independently.
Diagram
Example Scenario
Scenario
Acme Corp configures a SAML-based corporate IdP so that its employees authenticate through their existing enterprise identity system.
Input
- Actor: Acme Corp Tenant administrator
- Resource: Tenant IdP configuration
- Action: Configure a SAML 2.0 identity provider with attribute mappings
- Context: Acme Corp's corporate IdP provides employee name, email, and department attributes
Expected Outcome
- Result: Acme Corp employees authenticate through their corporate IdP. On first login, the platform creates a user record, maps attributes from the SAML assertion, and establishes a Tenant membership.
- Why: Tenant-scoped federation allows Acme Corp to use its existing identity infrastructure. Other Tenants on the platform are unaffected by Acme Corp's IdP configuration.
Common Misunderstandings
- "Keymate implements its own federation protocols." — Tenant-scoped federation is provided by the underlying Keycloak platform. Keymate leverages this capability as part of its multi-tenant model.
- "All Tenants must use the same IdP type." — Each Tenant configures its own IdP independently. One Tenant can use SAML while another uses OpenID Connect.
- "Federated users bypass Tenant membership." — Federated users are provisioned into the Tenant that configured the IdP. They receive a standard Tenant membership and are subject to the same assignment and role rules as directly authenticated users.
Federation configuration is a Keycloak-level capability. For protocol-specific configuration details (endpoints, certificate setup, claim mapping syntax), refer to the Keycloak identity broker documentation.
Design Notes / Best Practices
- Configure attribute mappings before enabling just-in-time provisioning to ensure federated users receive correct internal attributes from the first login.
- Test federation configurations in a non-production environment before deploying to production Tenants.
- Use group synchronization to maintain consistency between external directory groups and Keymate groups, reducing manual group management.
Combine Tenant-scoped federation with Tenant Onboarding templates to pre-configure standard IdP connection templates for common enterprise IdP patterns.
Related Use Cases
- Connecting a Tenant to a corporate SAML 2.0 identity provider for employee SSO
- Enabling just-in-time user provisioning for federated Tenants
- Configuring separate IdP connections per Tenant on a shared platform