How do I integrate SPID with Clavex?

Clavex includes built-in SPID support for all 9 AgID identity providers. Enable the spid connector in config.yaml, set your entity ID and ACS URL, then upload your SP metadata to the AgID registry. Users authenticate via SPID and receive a standard OIDC token from Clavex — no SPID SDK needed in your application.

Does Clavex support all SPID identity providers?

Yes. Clavex connects to all 9 AgID-registered SPID identity providers including Aruba, Infocert, Namirial, Poste Italiane, Sielte, Tim, Lepida, Register, and Intesi. The IdP list is kept up to date automatically.

Can I use SPID and CIE on the same Clavex instance?

Yes. SPID and CIE 3.0 connectors can both be active simultaneously on the same Clavex organisation. Users see a unified login screen and your application receives a single OIDC token regardless of which eID method they used.

Does integrating SPID via Clavex require a plugin or external adapter?

No. SPID support is built into the Clavex binary — no Keycloak plugin, no separate SPID proxy, no SDK in your application. Configure once via config.yaml or the admin API and Clavex handles the entire SAML exchange with AgID identity providers.

What SPID LoA (Level of Assurance) does Clavex support?

Clavex supports SPID LoA1, LoA2, and LoA3. The required assurance level is configurable per OIDC client using the acr_values parameter in the authorization request.

Protocols

SPID Integration

SPID (Sistema Pubblico di Identità Digitale) is Italy's national digital identity system. Clavex acts as a SAML 2.0 Service Provider and federates with all accredited SPID identity providers — your users authenticate at their chosen IdP, and Clavex issues OIDC tokens to your application, transparently bridging SAML and OpenID Connect.

Also supported: CIE (Carta d'Identità Elettronica) uses the same SAML 2.0 infrastructure. Enable both independently per-organization.

How It Works

User ─────> Your App "Login with SPID"

Your App ─────> Clavex OIDC /authorize?acr_values=https://www.spid.gov.it/SpidL2

Clavex ─────> SPID IdP SAML AuthnRequest (signed, SP-initiated)

SPID IdP ─────> Clavex ACS SAMLResponse (signed + encrypted)

Clavex ─────> Your App OIDC code → tokens with SPID claims

Step 1 — Prerequisites

Before enabling SPID you need:

A valid X.509 certificate + private key for your Service Provider (SP). Use openssl to generate a 2048-bit RSA key pair signed by a trusted CA, or self-signed for testing.
A public HTTPS domain for your Clavex instance — SPID IdPs will not accept localhost for production.
An AgID accreditation for production. For testing, use the SPID validator at https://validator.spid.gov.it.

bash

# Generate SP key pair (production: use a CA-signed cert) $ openssl req -x509 -newkey rsa:2048 -keyout spid-sp.key -out spid-sp.crt \ -days 3650 -nodes \ -subj "/C=IT/ST=Italy/O=Acme Corp/CN=id.acme.eu"

Step 2 — Enable SPID in config

Add the SPID section to your config.yaml. The SP entity ID and ACS URL must be publicly reachable — they are embedded in your SAML metadata and registered with AgID.

yaml

spid: enabled: true # SP entity ID — must be a HTTPS URL, typically your metadata URL sp_entity_id: https://id.acme.eu/saml/spid/metadata # X.509 cert PEM (public key — shared with SPID IdPs) sp_cert_file: /etc/clavex/spid-sp.crt sp_key_file: /etc/clavex/spid-sp.key # AgID federation registry (production vs. test) registry_url: https://registry.spid.gov.it/entities-idp # registry_url: https://demo.spid.gov.it/entities-idp # for testing # Attribute set (1=minimum, 2=email+fiscal code, 3=full set) attribute_consuming_service_index: 1 # SPID level: SpidL1 (username+password), SpidL2 (+ OTP), SpidL3 (+ hardware token) default_authn_context_class_ref: https://www.spid.gov.it/SpidL2

Step 3 — Publish SP Metadata

Clavex auto-generates SAML SP metadata at startup. Register this URL with the AgID federation portal. For testing, download and upload it to the SPID validator.

bash

# Your SP metadata URL (pass to AgID registration) https://id.acme.eu/saml/spid/metadata
# Verify metadata is valid $ curl -s https://id.acme.eu/saml/spid/metadata | xmllint --noout - ✓ metadata valid
# ACS (Assertion Consumer Service) endpoint https://id.acme.eu/saml/spid/acs
# SLO (Single Logout) endpoint https://id.acme.eu/saml/spid/slo

Step 4 — Enable Per-Organization

SPID is enabled globally in config, but each organization must activate it individually. This allows multi-tenant deployments where only some orgs need SPID.

bash

$ curl -s -X PUT https://id.acme.eu/api/v1/organizations/$ORG_ID/providers/spid \ -H "Authorization: Bearer $ORG_TOKEN" \ -H "Content-Type: application/json" \ -d '{"enabled": true, "spid_level": "SpidL2"}'
# SPID login button now appears on the org's login page: https://id.acme.eu/acme/login → "Accedi con SPID"

Step 5 — OIDC Claims Mapping

SPID attributes are mapped to standard OIDC claims automatically. The fiscalNumber attribute becomes available as a custom claim.

SPID Attribute	OIDC Claim	Notes
name	given_name	As per SPID attribute set
familyName	family_name
email	email	Attribute set 2+
fiscalNumber	fiscal_number	Italian codice fiscale
dateOfBirth	birthdate	ISO 8601 (YYYY-MM-DD)
placeOfBirth	birthplace	Municipality code (Belfiore)
spidCode	spid_code	Unique SPID identifier

Step 6 — Test with SPID Demo

bash

# Trigger SPID login via OIDC (acr_values selects the SPID level) https://id.acme.eu/acme/authorize ?client_id=clavex_01925... &redirect_uri=https://app.example.com/callback &response_type=code &scope=openid+email+profile &acr_values=https://www.spid.gov.it/SpidL2 &idp_hint=https://demo.spid.gov.it # idp_hint skips the IdP picker — use for direct IdP linking

Production note: Before going live you must register your SP with AgID, pass the SPID compliance checker, and obtain a SPID button kit from AgID (specific graphics requirements apply).

CIE — Carta d'Identità Elettronica

CIE uses a separate SAML SP configuration but follows the same flow. Enable it in config:

yaml

cie: enabled: true sp_entity_id: https://id.acme.eu/saml/cie/metadata sp_cert_file: /etc/clavex/cie-sp.crt sp_key_file: /etc/clavex/cie-sp.key

CIE's SAML IdP metadata is fetched from https://collaudo.idserver.servizicie.interno.gov.it/idp/shibboleth (pre-production) and https://idserver.servizicie.interno.gov.it/idp/shibboleth (production). Clavex refreshes it automatically on a 24-hour schedule.