Keycloak SPID Integration for Production: Prevent Duplicate Accounts

Yes, Keycloak can be integrated with Italy’s SPID digital identity system, and the recommended path is the italia/spid-keycloak-provider module. Deploy the compiled provider JAR into your Keycloak instance, then import official SPID Identity Provider metadata from registry.spid.gov.it. From there, the configuration work is mostly parameter tuning and flow customisation, not custom protocol engineering.

TL;DR:

• Ensuring version compatibility between Keycloak and the spid-keycloak-provider JAR is critical; mismatched versions often cause runtime failures.
• Configuring SPID attributes requires setting the sync mode to force and mapping fiscalNumber as the primary identity attribute to prevent duplicate accounts.
• Creating a custom First Broker Login flow with automatic user linking minimizes login friction and avoids duplicate account creation.
• Using self-signed RSA certificates for signing requests and assertions is permitted and easily handled within Keycloak’s realm keys settings.
• Regularly refreshing metadata, monitoring certificate expirations, and rehearsing upgrades in staging are essential to prevent silent login failures due to metadata drift.

Table of Contents

• Prerequisites for Keycloak SPID setup
• How do you install the spid Keycloak provider module?
• Configuring SPID identity providers with official metadata
• Why does SPID need a custom First Broker Login flow?
• Setting up SPID-compliant keys and certificates
• How do you test a SPID Keycloak integration before launch?
• Compatibility, upgrades and production hardening
• When should you bring in an engineering partner for SPID integration?
• Practitioner perspective: what actually breaks in production
• Get help finishing your SPID and Keycloak rollout
• Sources
• FAQ

Prerequisites for Keycloak SPID setup

Before touching a configuration screen, get the environment right. SPID integration fails more often from mismatched versions and missing test credentials than from anything in the SAML specification itself.

• A supported Keycloak baseline consistent with the provider’s documented compatibility matrix, plus a clear understanding of your $KEYCLOAK_PATH layout
• JDK and Maven installed locally for building the provider from source, alongside Git for pulling the repository
• Docker or Podman available, since the SPID SAML Check testing suite runs as a containerised service
• A working knowledge of the Keycloak documentation covering identity brokering and authentication flows
• Access to Registry for metadata and Demo for test logins
• Test credentials for the SPID demo identity provider and a hostname mapping strategy (via /etc/hosts or a local DNS override) so your development realm resolves correctly during callback handling

Skipping the hostname mapping step is the single most common reason developers see broken redirects during their first login attempt.

How do you install the spid Keycloak provider module?

The provider ships as source you build yourself, not a prebuilt binary you download and forget. That matters because SPID’s SAML dialect shifts slightly between Keycloak releases, and building from the tagged version matching your Keycloak instance avoids a class of obscure runtime errors.

1. Clone the italia/spid-keycloak-provider repository and check out the release tag matching your Keycloak version.
2. Run mvn clean package to produce the provider JAR in the target directory.
3. Copy the JAR into {$KEYCLOAK_PATH}/providers/ for Keycloak’s newer quarkus distribution, or {$KEYCLOAK_PATH}/standalone/deployments/ if you are running the legacy WildFly distribution.
4. Set correct owner and group permissions on the file so the Keycloak service account can read it, then run kc.sh build to trigger provider registration.
5. Restart Keycloak and open Identity Providers → Add provider. SPID should now appear in the provider list.

If SPID does not appear, check the server log for a ServiceLoader failure first. That almost always points to a JAR built against the wrong Keycloak major version.

Pro Tip: Keep a versioned build of the provider JAR alongside your Keycloak upgrade notes. When you bump Keycloak versions, rebuild from the matching provider tag rather than reusing an old JAR, even if it appears to load without error.

Configuring SPID identity providers with official metadata

Once the provider is loaded, the next task is defining the actual Identity Provider entries using metadata pulled from the SPID registry. Keycloak accepts this either as a direct URL import or as an uploaded XML file, and either method works fine for production as long as you refresh it periodically rather than treating it as a one-time import.

The parameters that actually make SPID work correctly, rather than merely appear to work, are:

• Sync Mode: Force — ensures user attributes are refreshed from the assertion on every login rather than cached from first contact
• Force Authentication: ON — SPID mandates this to prevent silent re-authentication from a cached session at the identity provider
• Attribute Consuming Service Index: 1 — tells the identity provider which attribute set to release, and mismatches here are a frequent cause of empty attribute assertions
• NameID Format: Transient — SPID does not issue persistent identifiers, so your linking strategy has to work around this
• Principal Type: Attribute [Name], mapped to fiscalNumber — this is what gives you a stable, reusable identifier despite the transient NameID

Set up attribute mappers for fiscalNumber, name, familyName, and email at minimum. Treat fiscalNumber as the only attribute you trust for identity linking. It is the sole SPID attribute guaranteed to be both present and stable across sessions.

Why does SPID need a custom First Broker Login flow?

Because SPID issues transient NameIDs, Keycloak’s default First Broker Login behaviour will treat every login from the same person as a brand new identity, prompting the classic “confirm link to existing account” screen every single time. In a production system with thousands of citizens logging in, that friction is unacceptable, and worse, it risks duplicate account creation if users dismiss the prompt incorrectly.

The fix documented in the provider’s wiki is a copy of the First Broker Login flow with one targeted change:

1. Duplicate the default First Broker Login flow and rename it, for example, “First Broker Login SPID”.
2. Add the Automatically Set Existing User execution to the new flow.
3. Move this execution above Confirm Link Existing Account in the flow ordering.
4. Set the requirement on Automatically Set Existing User to Alternative or Required depending on whether you want any fallback prompt at all, and set Confirm Link Existing Account to Disabled if you want full automation.
5. Assign the new flow to the First Login Flow parameter on each SPID Identity Provider entry, then test with a returning user to confirm no duplicate account gets created.

Pro Tip: Test account linking with a user who has already registered manually through your realm’s normal registration form. That scenario, not a brand new SPID user, is where broken flow ordering actually surfaces.

Setting up SPID-compliant keys and certificates

SPID requires signed AuthnRequests, signed assertions, and signed Service Provider metadata, and Italy’s AGID guidance permits self-signed RSA X509 certificates for public administration service providers rather than mandating certificate authority issuance. The provider bundles a dedicated SPID RSA Generated key provider specifically for this purpose.

To configure it correctly:

• Add the SPID RSA Generated provider under Realm Settings → Keys, generating a fresh RSA keypair through the admin console rather than importing an external certificate
• Set it as Active and assign it a priority higher than any existing default signing key so it becomes the effective signer
• Enable Want AuthnRequests Signed
• Enable Want Assertions Signed
• Enable Sign Service Provider Metadata

Miss any one of these three toggles and the SPID identity provider will either reject your requests outright or, worse, accept them silently while flagging your service provider as non-compliant during an audit.

How do you test a SPID Keycloak integration before launch?

Never point a first integration attempt at a real SPID identity provider. The SPID SAML Check suite and the official demo IdP exist precisely so you can validate metadata, signatures, and flow behaviour without touching production identity infrastructure.

1. Pull and run the SPID SAML Check Docker environment locally, mapping a hostname entry so your Keycloak realm and the check tool can resolve each other correctly.
2. Import your Service Provider metadata into the check environment and resolve any schema validation warnings before moving on.
3. Trigger a login through Keycloak’s Account client, authenticate against demo.spid.gov.it, and confirm the returned attributes match what your mappers expect.
4. Test the logout flow explicitly. SPID’s single logout behaviour is a common blind spot, and a session that survives logout at the identity provider but not at Keycloak (or vice versa) is a compliance problem, not a cosmetic bug.

Pro Tip: Most “signature validation failed” errors trace back to a hostname mismatch between what’s declared in your metadata and what the browser actually requests. Check that first, before touching your certificate configuration.

Common failure patterns to check first: hostname mismatches between declared and actual endpoints, stale metadata imports that predate an identity provider certificate rotation, and attribute mappers pointing at the wrong SAML attribute name.

Compatibility, upgrades and production hardening

Keycloak’s SPID support is not a “configure once, forget forever” affair. As Keycloak’s admin UI evolved, provider ID naming became stricter, and versions from Keycloak 24.x onward require a manual database migration: UPDATE IDENTITY_PROVIDER SET PROVIDER_ID='spid-saml' WHERE PROVIDER_ID='spid'. Run this before upgrading the admin UI, not after, or you risk losing visibility into your existing SPID provider configuration entirely.

For a production-hardened deployment, treat these as non-negotiable:

• Version-pin the provider JAR against your exact Keycloak release and validate configuration in a staging realm before every upgrade
• Automate provider JAR deployment through your existing CI/CD pipeline rather than manual file copying
• Monitor certificate expiry on your SPID RSA Generated key and back up realm export configuration on a schedule
• For realms managing dozens of SPID identity providers, use the keycloak-spid-provider-configuration-client to generate the hundreds of required parameters programmatically rather than by hand

When should you bring in an engineering partner for SPID integration?

Handle this internally when your team already runs Keycloak in production and has bandwidth for SAML debugging under deadline pressure. Bring in outside engineering help when compliance timelines are fixed, in-house SPID or SAML experience is thin, or the integration sits on a critical path you cannot afford to get wrong twice. Vicedomini Softworks works this way through direct engineer collaboration rather than an account-manager layer, with peer-reviewed code and documented delivery outcomes. A sensible starting point is a short assessment engagement covering configuration review and acceptance testing before a full rollout commitment.

Practitioner perspective: what actually breaks in production

Metadata drift is the quiet killer here. An identity provider rotates a certificate, nobody refreshes the import, and logins fail weeks later with no code change in sight. Build a metadata refresh cadence, rehearse upgrades in staging, and monitor certificate expiry as seriously as you monitor uptime.

— Pepe F.

Get help finishing your SPID and Keycloak rollout

A do-it-yourself SPID integration can work, but the gap between “logs in on the demo environment” and “holds up under an AGID compliance review” is where most internal projects stall. Vicedomini Softworks approaches this differently from a typical outsourced build: you work directly with the engineers configuring your identity providers and writing your First Broker Login flow, not through an account manager relaying requirements back and forth.

A short advisory engagement typically covers an assessment of your current Keycloak realm, hands-on configuration of the SPID provider and its signing keys, acceptance testing against the demo identity provider, and a clean handover with documentation your team can maintain afterwards. Because the delivery model puts engineers directly in front of clients, technical decisions about attribute mapping, flow design, and certificate rotation stay aligned with your actual compliance deadlines rather than getting lost in translation. If you want a rapid, focused starting point, the CTO Advisory engagement begins at €1,800 per month and is built for exactly this kind of scoped, technical assessment. For longer integration projects needing full build and ongoing support, the custom software development services page outlines the broader engagement options. Get in touch to scope your SPID rollout before your next compliance deadline lands.

Sources

• italia/spid-keycloak-provider
• Registry
• Demo
• Keycloak documentation

FAQ

What Is the spid-keycloak-provider Module?

It is an open-source Keycloak extension that adapts SPID’s specific SAML dialect into a format Keycloak’s identity brokering natively understands. It handles the custom NameID format, attribute consuming service indexes, and the SPID RSA Generated signing key provider that standard Keycloak lacks, as documented in the project repository.

Why Does Keycloak Need a Custom First Broker Login Flow for SPID?

SPID issues transient NameIDs rather than persistent ones, so Keycloak’s default flow would prompt users to confirm account linking on every login. A custom flow adding the “Automatically Set Existing User” execution links accounts automatically using the fiscalNumber attribute instead.

Can I Use a Self-Signed Certificate for SPID in Keycloak?

Yes. AGID’s guidance permits self-signed RSA X509 certificates for public administration service providers, and the SPID RSA Generated provider inside the spid-keycloak-provider module generates these directly within the Keycloak admin console.

Do I Need to Migrate Anything When Upgrading Keycloak?

Yes, on Keycloak 24.x and later you must run a SQL update changing the provider ID from spid to spid-saml before upgrading the admin UI, otherwise existing SPID provider configuration can become invisible or broken in the console.

How Much Does a SPID Integration Engagement With Vicedomini Softworks Cost?

Pricing depends on scope, but a focused assessment through the CTO Advisory plan starts from €1,800 per month, while full custom development engagements are quoted individually through the services page.