Define core SSO architecture for external identity providers

NS8 applications currently authenticate users only against internal user domains (Samba AD, OpenLDAP) or external LDAP servers. There is growing demand to let applications authenticate against cloud identity providers, enabling single sign-on (SSO) across the cluster.

🎯 Define the core NS8 architecture for federated authentication with external identity providers, such as Microsoft Entra ID and Google. This is a design issue: the expected outcome is an architectural document covering at least:

the authentication protocol choice (e.g. OpenID Connect) and how the core mediates between applications and identity providers
how external identities relate to the existing user domain model (provisioning, mapping, group membership)
which core components are involved (e.g. an identity broker service, HTTP routes, TLS certificates) and their configuration UI
how future application integrations (Nextcloud, WebTop, NethVoice) will consume the architecture

Non-goals

Implementing SSO support in individual applications: each integration will be tracked by its own issue, once this architecture is defined.
Replacing existing LDAP-based authentication, which remains fully supported.

See also

Discussion https://mattermost.nethesis.it/nethesis/pl/jsk9jeewdjfomprqmpmcg18f5a

Open questions not yet addressed by the ns8-idp module and by the interface documented in NethServer/ns8-core#1271. Settled so far: OpenID Connect (OIDC) as the protocol, the provider module mediates (not the core), one realm per user domain backed by its LDAP database, client registration and provider discovery.

Protocol and mediation

SAML clients: Keycloak supports them, but register-client creates OIDC clients only
How an application chooses among several OIDC providers in the cluster

External identities and the user domain model

Federation with external identity providers (Microsoft Entra ID, Google): who configures it, and where
Matching an external login with an existing LDAP account (first-login account linking, never trusting an upstream email claim)
Group membership in tokens: no groups claim is emitted yet; mapping of Entra ID and Google groups
Realms without a user domain, backed by the Keycloak local user store
Applications that speak only LDAP cannot see users that exist only at an external provider: accept it, or front them with an auth proxy (e.g. oauth2-proxy)

Core components and configuration UI

Exposure of the Keycloak admin console
SSO status in the core UI, e.g. realm and registered modules on the User domains page
Backup and restore of the provider (Keycloak database)
Several instances or replicas of the same realm; several host names for one provider

Application integrations

First real consumers: Nextcloud, WebTop, NethVoice, Mail (token introspection through the audience attribute is untested)
How an application learns what a realm provides (e.g. a groups claim) before offering it to the administrator
Delegated access for AI agents (OAuth token exchange, RFC 8693)

ns8-idp follow-ups

Test the recovery of the ns8-agent admin client
Identify the extra port opened by the Keycloak JVM
Test coverage: Active Directory domain in CI, a real calling module, events, concurrent registrations, survival across updates

Generated by Claude Code:claude-opus-5.5

Single Sign-On docs: https://nethserver.github.io/ns8-core/core/user_domains/#single-sign-on
ns8-idp module alpha: https://github.com/NethServer/ns8-idp

Navigation Menu

Repository navigation

Define core SSO architecture for external identity providers #8080

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Define core SSO architecture for external identity providers #8080

Description

Activity

DavidePrincipi commented on Oct 2, 2026

DavidePrincipi commented on Oct 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions