Federate Open Data Hub with IDEM GARR via SATOSA (SAML ↔ OIDC) #98
Description
This issue describes a proposed technical approach to federate Open Data Hub with the IDEM GARR SAML federation using a SATOSA-based SAML ↔ OpenID Connect proxy in front of Keycloak.
IDEM GARR federation via SATOSA - implementation level technical description
1. Objective
Enable authentication for users from Italian universities participating in the IDEM GARR federation in Open Data Hub, using their home university credentials, without introducing SAML support into Keycloak or Open Data Hub applications.
2. Design constraints and rationale
• IDEM GARR is a SAML 2.0 based federation.
• Open Data Hub uses Keycloak, which supports OpenID Connect for identity brokering.
• Direct Keycloak - IDEM GARR integration is not feasible due to protocol mismatch.
Therefore, a protocol translation layer is required.
3. Chosen solution: SATOSA-based federation proxy
SATOSA is selected as the federation proxy for the following concrete reasons:
• SATOSA is explicitly designed for identity brokering and protocol translation (SAML - OIDC).
• It is widely used in eduGAIN-style national federations, which matches the IDEM GARR context.
• Attribute transformation and normalization are first-class concepts in SATOSA pipelines.
• SimpleSAMLphp is primarily SAML-centric, with OIDC added via modules, whereas SATOSA is purpose-built for this gateway role.
SATOSA will act simultaneously as:
• a SAML Service Provider (SP) towards IDEM GARR, and
• an OpenID Connect Provider (OP) towards Keycloak.
4. Concrete system topology
University IdP
↑ (SAML)
IDEM GARR Federation
↑ (SAML)
SATOSA (SAML SP + OIDC OP)
↑ (OIDC)
Keycloak
↑
Open Data Hub applications
Keycloak never consumes SAML. IDEM GARR never consumes OIDC.
SATOSA is the only component handling both protocols.
5. SATOSA deployment (what is actually installed)
SATOSA is deployed as a standalone service, not as a library.
Concrete characteristics:
• Python-based WSGI application
• Typically run behind nginx or Apache
• HTTPS only
• Publicly reachable by:
o Keycloak (OIDC endpoints)
o IDEM GARR (SAML endpoints)
Artifacts created at this stage:
• SATOSA service URL (e.g. https://satosa.)
• TLS certificates
• SATOSA configuration directory (pipelines, backend/frontends)
Operational responsibility:
• SATOSA is an additional component that must be monitored and maintained.
6. SATOSA configuration as SAML Service Provider (towards IDEM GARR)
Service Provider identity and metadata
SATOSA generates:
• SAML EntityID
• SP metadata (ACS endpoints, certificates)
• Signing and encryption certificates
This metadata is:
• Submitted to IDEM GARR
• Approved and included in IDEM GARR federation metadata
SATOSA is then configured to:
• Consume IDEM GARR federation metadata
• Trust all IDEM-approved university IdPs
From IDEM GARR’s perspective, SATOSA is a standard SAML SP.
7. SATOSA authentication pipeline configuration
SATOSA authentication is defined via pipelines, which explicitly describe how identity data flows through the system.
Typical pipeline stages configured here:
• Request handling
• SAML assertion reception
• Signature and issuer validation
• Attribute extraction
• Attribute normalization
• Internal attribute representation
• Output generation (OIDC claims)
Expected SAML attributes from universities include:
• eduPersonPrincipalName
• mail
• givenName
• sn
• eduPersonAffiliation
SATOSA must be configured to:
• Accept variability in attribute presence across universities
• Normalize attributes into a consistent internal format
• Enforce mandatory attributes (e.g. email or unique identifier)
This is the primary point where federation heterogeneity is handled.
8. SATOSA configuration as OpenID Connect Provider (towards Keycloak)
SATOSA exposes standard OIDC endpoints:
• /authorize
• /token
• /userinfo
OIDC configuration includes:
• Client registration for Keycloak
• Client ID and secret
• Redirect URIs (Keycloak)
• Supported scopes and claims
SATOSA issues:
• ID tokens
• Access tokens
From Keycloak’s point of view, SATOSA behaves like any other external OIDC Identity Provider (e.g. Google, Azure AD).
9. Attribute and claim mapping (explicit responsibility split)
SATOSA is responsible for mapping SAML attributes to OIDC claims.
Example mapping:
• mail → email
• givenName → given_name
• sn → family_name
• eduPersonPrincipalName → preferred_username
• eduPersonAffiliation → custom or standard claim
Keycloak never sees raw SAML attributes.
10. Keycloak configuration (what Rudi would actually configure)
In Keycloak:
• Add a new Identity provider.
• Type: OpenID Connect
• Point to SATOSA OIDC endpoints
• Configure:
o Client ID / secret
o Claim mappings
o User linking or auto-provisioning behavior
Keycloak handles:
• User creation
• Account linking
• Role and authorization logic
• Token issuance to Open Data Hub applications
No changes are required in Open Data Hub applications themselves.
11. End-to-end success criteria
A successful setup means:
1. User clicks “Login with IDEM GARR”
2. Redirect chain completes via SATOSA and IDEM GARR
3. Keycloak creates or links a user
4. User is redirected back to Open Data Hub
5. No passwords are handled by Keycloak or Open Data Hub
12. Risks and operational considerations
• SATOSA introduces an additional operational component
• Attribute completeness differs between universities
• Federation metadata and certificates require lifecycle management
These risks are standard in academic federations and mitigated by using IDEM-supported tooling and patterns.
13. Future outlook
IDEM GARR indicated an ongoing eduGAIN OpenID Federation initiative. Once native OpenID federation becomes production-ready, the SATOSA proxy could potentially be removed and Keycloak could integrate directly.
14. References and primary documentation sources
The following primary sources describe the federation technologies and configuration concepts summarized above and can be used as authoritative references for the concrete implementation.
IDEM GARR federation (SAML, SP onboarding, metadata, attributes)
IDEM GARR federation overview and SAML-based architecture:
https://www.idem.garr.it/en/federazione-idem-en/idem-federation
IDEM GARR technical documentation and guidelines (SP/IdP configuration, metadata exchange, attributes):
https://wiki.idem.garr.it/wiki/Documentazione
SATOSA (SAML Service Provider → OpenID Connect Provider gateway)
Official SATOSA repository (source code, documentation, configuration examples):
https://github.com/IdentityPython/SATOSA
SATOSA SAML → OIDC gateway configuration guide (describes SAML frontend + OIDC backend setup):
https://github.com/IdentityPython/SATOSA/blob/master/doc/saml2-to-oidc.md
Keycloak (OpenID Connect identity brokering)
Keycloak identity brokering documentation (external IdPs, brokering concepts):
https://www.keycloak.org/docs/latest/server_admin/#_identity_broker
Keycloak OpenID Connect identity provider configuration:
https://www.keycloak.org/docs/latest/server_admin/#_oidc