Roadmap: Identity Federation & SSO

1. Overview

This roadmap defines an enterprise identity federation architecture using Keycloak for:

Single Sign-On (SSO) across all services
SAML 2.0 federation with ISE Admin Portal
OIDC/OAuth integration for modern applications
User federation with Active Directory
MFA enforcement across all authentication flows

Identity is the new perimeter in Zero Trust. This roadmap establishes Keycloak as the central identity provider, federating authentication across network (ISE), infrastructure (Vault), and applications (Gitea, Synology).

2. Architecture Vision

direction: down

keycloak: "KEYCLOAK\n(Identity IdP)" {
  shape: rectangle
  style.fill: "#313244"
  style.stroke: "#cba6f7"
  style.font-size: 16
}

protocols: "Protocols" {
  style.fill: transparent
  style.stroke: transparent

  saml: "SAML 2.0\n(Legacy)" {
    shape: rectangle
    style.fill: "#45475a"
    style.stroke: "#f9e2af"
  }
  oidc: "OIDC\n(Modern)" {
    shape: rectangle
    style.fill: "#45475a"
    style.stroke: "#a6e3a1"
  }
  ldap: "LDAP\n(Backend)" {
    shape: rectangle
    style.fill: "#45475a"
    style.stroke: "#89b4fa"
  }
}

apps: "Applications" {
  style.fill: transparent
  style.stroke: transparent

  saml_apps: "ISE Admin\niPSK Manager\nNAS WebUI" {
    shape: rectangle
    style.fill: "#313244"
    style.stroke: "#f9e2af"
  }
  oidc_apps: "Gitea\nVault\nPortainer" {
    shape: rectangle
    style.fill: "#313244"
    style.stroke: "#a6e3a1"
  }
  ldap_apps: "AD DS\n(Source)" {
    shape: rectangle
    style.fill: "#313244"
    style.stroke: "#89b4fa"
  }
}

keycloak -> protocols.saml
keycloak -> protocols.oidc
keycloak -> protocols.ldap

protocols.saml -> apps.saml_apps
protocols.oidc -> apps.oidc_apps
protocols.ldap -> apps.ldap_apps: "federation"

notes: |md
  **User Federation:** AD → Keycloak (sync every 60s)
  **Group Mapping:** AD Groups → Keycloak Roles → App Permissions
  **MFA:** TOTP/WebAuthn enforced for admin roles
| {
  shape: text
  style.font-size: 12
}

3. Current State

Component	Status	Notes
Keycloak	OPERATIONAL	Deployed on keycloak-01, realm configured
Active Directory	OPERATIONAL	User source, not identity provider
ISE SAML	PARTIAL	Admin portal configured, needs testing
OIDC Apps	PLANNED	Gitea, Vault, Portainer not integrated
User Federation	PARTIAL	AD sync configured, groups need mapping
MFA	PLANNED	TOTP not enforced yet

Component

Status

Notes

Keycloak

OPERATIONAL

Deployed on keycloak-01, realm configured

Active Directory

OPERATIONAL

User source, not identity provider

ISE SAML

PARTIAL

Admin portal configured, needs testing

OIDC Apps

PLANNED

Gitea, Vault, Portainer not integrated

User Federation

PARTIAL

AD sync configured, groups need mapping

MFA

PLANNED

TOTP not enforced yet

4. Phase 1: Keycloak Hardening & HA

4.1. Objectives

Production-harden Keycloak deployment
Configure PostgreSQL backend (vs H2)
Establish backup/recovery procedures
Plan HA with keycloak-02

4.2. Tasks

#	Task	Priority
1.1	Migrate from H2 to PostgreSQL database	HIGH
1.2	Configure TLS with Vault-issued certificate	HIGH
1.3	Enable audit logging to external syslog	MEDIUM
1.4	Create backup script for realms/config export	HIGH
1.5	Document disaster recovery in domus-infra-ops	HIGH
1.6	Plan keycloak-02 for HA (future)	LOW

#

Task

Priority

1.1

Migrate from H2 to PostgreSQL database

HIGH

1.2

Configure TLS with Vault-issued certificate

HIGH

1.3

Enable audit logging to external syslog

MEDIUM

1.4

Create backup script for realms/config export

HIGH

1.5

Document disaster recovery in domus-infra-ops

HIGH

1.6

Plan keycloak-02 for HA (future)

LOW

4.3. Success Criteria

PostgreSQL backend in production
TLS with valid DOMUS-ISSUING-CA cert
Automated daily realm backups
Recovery procedure documented and tested

5. Phase 2: Active Directory Federation

5.1. Objectives

Complete user federation from AD
Map AD groups to Keycloak roles
Implement incremental sync for changes

5.2. Federation Configuration

direction: right

ad: "Active Directory" {
  shape: cylinder
  style.fill: "#313244"
  style.stroke: "#89b4fa"

  url: "ldaps://dc01:636"
  bind: "keycloak-svc"
}

keycloak: "Keycloak Federation" {
  shape: rectangle
  style.fill: "#313244"
  style.stroke: "#cba6f7"

  sync: "Sync Settings" {
    style.fill: "#45475a"
    full: "Full: daily (86400s)"
    changed: "Changed: 60s"
  }
}

ad -> keycloak: "LDAPS" { style.stroke: "#a6e3a1" }

groups: "Group Mapping" {
  shape: rectangle
  style.fill: "#1e1e2e"
  style.stroke: "#f9e2af"

  g1: "Domain Admins → keycloak-admin"
  g2: "ISE Admins → ise-admin"
  g3: "Network Team → network-operator"
  g4: "Help Desk → readonly"
}

keycloak -> groups: "maps to"

5.3. Tasks

#	Task	Priority
2.1	Configure LDAPS connection to AD (port 636)	HIGH
2.2	Create keycloak-svc service account in AD	HIGH
2.3	Map organizational AD groups to Keycloak roles	HIGH
2.4	Test incremental sync (user changes propagate)	MEDIUM
2.5	Configure group-based role assignment	HIGH
2.6	Document in domus-identity-ops	MEDIUM

#

Task

Priority

2.1

Configure LDAPS connection to AD (port 636)

HIGH

2.2

Create keycloak-svc service account in AD

HIGH

2.3

Map organizational AD groups to Keycloak roles

HIGH

2.4

Test incremental sync (user changes propagate)

MEDIUM

2.5

Configure group-based role assignment

HIGH

2.6

Document in domus-identity-ops

MEDIUM

5.4. Success Criteria

All AD users sync to Keycloak
Group membership determines Keycloak roles
User changes sync within 60 seconds
Service account uses minimal privileges

6. Phase 3: SAML Integration - ISE Admin Portal

6.1. Objectives

Complete ISE Admin Portal SAML integration
Enable role-based admin access
Test failover to local ISE accounts

6.2. SAML Configuration

Parameter	Value
IdP Entity ID	keycloak.inside.domusdigitalis.dev/realms/domus
SSO Service URL	keycloak…/protocol/saml
Signing Certificate	Keycloak realm signing cert
SP Entity ID	ise.inside.domusdigitalis.dev/admin
ACS URL	ise…/admin/saml/SSO
Attribute Mapping	groups → memberOf (for RBAC)

Parameter

Value

IdP Entity ID

keycloak.inside.domusdigitalis.dev/realms/domus

SSO Service URL

keycloak…/protocol/saml

Signing Certificate

Keycloak realm signing cert

SP Entity ID

ise.inside.domusdigitalis.dev/admin

ACS URL

ise…/admin/saml/SSO

Attribute Mapping

groups → memberOf (for RBAC)

6.3. Tasks

#	Task	Priority
3.1	Export Keycloak IdP metadata XML	HIGH
3.2	Import metadata into ISE Admin Settings	HIGH
3.3	Configure ISE admin groups mapping to SAML assertions	HIGH
3.4	Test SSO login flow end-to-end	HIGH
3.5	Configure fallback to local admin account	MEDIUM
3.6	Document ISE SAML in domus-identity-ops	HIGH

#

Task

Priority

3.1

Export Keycloak IdP metadata XML

HIGH

3.2

Import metadata into ISE Admin Settings

HIGH

3.3

Configure ISE admin groups mapping to SAML assertions

HIGH

3.4

Test SSO login flow end-to-end

HIGH

3.5

Configure fallback to local admin account

MEDIUM

3.6

Document ISE SAML in domus-identity-ops

HIGH

6.4. Success Criteria

ISE admin portal accepts Keycloak SSO
AD group membership grants ISE admin roles
Local admin fallback works when Keycloak unavailable
Session logout propagates correctly

7. Phase 4: OIDC Integration - Modern Apps

7.1. Objectives

Integrate Gitea with OIDC
Integrate Vault with OIDC
Integrate Portainer with OIDC
Standardize on OIDC for new applications

7.2. OIDC Client Configuration

Application	Client Type	Scopes
Gitea	Confidential	openid, profile, email, groups
Vault	Confidential	openid, profile, groups
Portainer	Confidential	openid, profile, groups
Synology DSM	Confidential	openid, profile, email

Application

Client Type

Scopes

Gitea

Confidential

openid, profile, email, groups

Vault

Confidential

openid, profile, groups

Portainer

Confidential

openid, profile, groups

Synology DSM

Confidential

openid, profile, email

7.3. Tasks

#	Task	Priority
4.1	Create Gitea OIDC client in Keycloak	MEDIUM
4.2	Configure Gitea authentication settings	MEDIUM
4.3	Create Vault OIDC auth method	MEDIUM
4.4	Map Vault policies to Keycloak groups	MEDIUM
4.5	Configure Portainer OIDC authentication	LOW
4.6	Test group-based authorization in each app	MEDIUM

#

Task

Priority

4.1

Create Gitea OIDC client in Keycloak

MEDIUM

4.2

Configure Gitea authentication settings

MEDIUM

4.3

Create Vault OIDC auth method

MEDIUM

4.4

Map Vault policies to Keycloak groups

MEDIUM

4.5

Configure Portainer OIDC authentication

LOW

4.6

Test group-based authorization in each app

MEDIUM

7.4. Success Criteria

Gitea SSO with AD credentials
Vault login via OIDC with policy mapping
All apps respect Keycloak session timeout
Group membership drives permissions

8. Phase 5: MFA Enforcement

8.1. Objectives

Require TOTP for administrative roles
Support WebAuthn (YubiKey) for security team
Configure conditional MFA policies

8.2. MFA Strategy

User Type	MFA Requirement	Method
Domain Admins	Always required	TOTP or WebAuthn
ISE Admins	Always required	TOTP or WebAuthn
Network Team	On new device/location	TOTP
Standard Users	Optional	TOTP (self-service)

User Type

MFA Requirement

Method

Domain Admins

Always required

TOTP or WebAuthn

ISE Admins

Always required

TOTP or WebAuthn

Network Team

On new device/location

TOTP

Standard Users

Optional

TOTP (self-service)

8.3. Tasks

#	Task	Priority
5.1	Enable TOTP authenticator in Keycloak	HIGH
5.2	Create authentication flow with MFA step	HIGH
5.3	Configure role-based MFA requirements	HIGH
5.4	Enable WebAuthn for admin accounts	MEDIUM
5.5	Test MFA enrollment flow	HIGH
5.6	Document MFA recovery procedures	MEDIUM

#

Task

Priority

5.1

Enable TOTP authenticator in Keycloak

HIGH

5.2

Create authentication flow with MFA step

HIGH

5.3

Configure role-based MFA requirements

HIGH

5.4

Enable WebAuthn for admin accounts

MEDIUM

5.5

Test MFA enrollment flow

HIGH

5.6

Document MFA recovery procedures

MEDIUM

8.4. Success Criteria

Admin logins require MFA
TOTP enrollment self-service works
WebAuthn supported for YubiKey users
Recovery codes documented and secured

9. Phase 6: Future Integrations

9.1. Planned Integrations

System	Integration Type	Status
iPSK Manager	SAML	PLANNED
NetBox	OIDC	PLANNED
Prometheus/Grafana	OIDC + OAuth proxy	PLANNED
Synology NAS	OIDC	PLANNED

System

Integration Type

Status

iPSK Manager

SAML

PLANNED

NetBox

OIDC

PLANNED

Prometheus/Grafana

OIDC + OAuth proxy

PLANNED

Synology NAS

OIDC

PLANNED

10. Work Applicability

This roadmap directly supports work enterprise requirements:

SSO: Single identity across all systems
Compliance: Audit trail for all authentications
Zero Trust: Identity-based access decisions
MFA: Regulatory requirement for admin access
Federation: Partner/contractor access via SAML

Keycloak patterns deploy to enterprise identity infrastructure.

11. Related Documentation

12. Revision History

Date	Author	Changes
2026-02-11	EvanusModestus	Initial roadmap from domus-identity-ops gaps

Date

Author

Changes

2026-02-11

EvanusModestus

Initial roadmap from domus-identity-ops gaps