How do I integrate CIE with Clavex?

Clavex implements CIE OpenID Connect 3.0 (the current Ministero dell'Interno profile) as a standard OIDC Authorization Code flow with PKCE (S256) and nonce. Register a CIE provider via POST /api/v1/organizations/{org}/cie with your client_id, client_secret, and environment (production or preproduction). Clavex handles the full OIDC exchange with the CIE identity server — no SAML, no separate CIE SDK.

Does CIE require registration with the Ministero dell'Interno?

Only for production. The pre-production environment (preproduzione.idserver.servizicie.interno.gov.it) accepts test integrations with no prior registration, using the CieID app's test accounts. Production requires registering your Relying Party at id.servizicie.interno.gov.it/idp/registrazioneRP.

What assurance level does CIE provide?

CIE authentication is always treated as eIDAS High assurance in Clavex, since it requires physical possession of the electronic ID card and PIN. This is recorded via OpenID Connect for Identity Assurance (OIDC4IDA) metadata on the user, distinguishing CIE logins from lower-assurance methods like SPID L1/L2.

Can Clavex issue a Verifiable Credential from a CIE login?

Yes. If an OID4VCI credential config has source_idp_type set to "cie", Clavex automatically creates a pre-authorized credential offer immediately after a successful CIE login, using the verified fiscal number, name, and date of birth as claims. See the eIDAS 2.0 quickstart.

Protocols

CIE Integration

CIE (Carta d'Identità Elettronica) is Italy's electronic ID card. Unlike SPID, CIE authentication in Clavex uses the CIE OpenID Connect 3.0 profile — a standard OIDC Authorization Code flow with PKCE (S256) and nonce, issued by the Ministero dell'Interno. There is no SAML exchange and no separate CIE SDK to embed: Clavex speaks OIDC directly to the CIE identity server and hands your application a normal OIDC token.

vs. SPID: SPID is a SAML 2.0 federation with 9 accredited identity providers. CIE is a single OIDC identity server run by the Ministero dell'Interno. Both can be active simultaneously on the same organisation, and both surface as login buttons on the same hosted login page.

How It Works

User ─────> Your App 302 → Clavex /authorize (standard OIDC login)

User ─────> Clavex login page clicks "Accedi con CIE"

Clavex ─────> CIE IdP OIDC AuthorizationRequest (PKCE S256 + nonce)

User ─────> CieID app NFC card read + PIN, or test account (preprod)

CIE IdP ─────> Clavex callback authorization code

Clavex ─────> Your App OIDC code → tokens with CIE-verified claims

Step 1 — Prerequisites

Before enabling CIE you need:

For testing: the CieID app (iOS/Android) with a pre-production test account — no physical card or Ministry registration required.
For production: a physical CIE card with NFC, the CieID app, and a registered Relying Party.
A client_id / client_secret pair issued by the environment you're integrating against.

Step 2 — Register a CIE Provider

CIE is registered as an identity provider scoped to your organisation. The authorization, token, userinfo, and JWKS URLs are filled in automatically based on environment — you only supply your client credentials.

bash

$ curl -s -X POST https://id.clavex.eu/api/v1/organizations/$ORG_ID/cie \ -H "Authorization: Bearer $ORG_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "CIE (preprod)", "client_id": "your-rp-client-id", "client_secret": "your-rp-client-secret", "environment": "preproduction", "allow_jit": true, "is_active": true }' | jq '{id,provider_type,is_active}' { "id": "01925f3a-...", "provider_type": "cie", "is_active": true }

No separate enable step: unlike SPID, CIE providers go live immediately when created with is_active: true — there is no per-organization PUT toggle. Set environment: "production" once you have a registered production RP.

Step 3 — Environment Endpoints

Clavex resolves these automatically from environment; shown here for reference and troubleshooting.

Endpoint	Production	Pre-production
Authorize	`https://{host}/idp/profile/oidc/authorize`
Token	`https://{host}/idp/profile/oidc/token`
Userinfo	`https://{host}/idp/profile/oidc/userinfo`
JWKS	`https://{host}/idp/profile/oidc/keyset`
`{host}`	`idserver.servizicie.interno.gov.it`	`preproduzione.idserver.servizicie.interno.gov.it`

Step 4 — Login

Once active, the CIE button appears automatically on your organisation's hosted login page — no client-side change required. Your application only needs a standard OIDC login redirect; the CIE option is presented to the user by Clavex.

bash

# Standard OIDC login — CIE (and SPID, if enabled) appear as login options https://id.clavex.eu/acme/authorize ?client_id=clavex_01925... &redirect_uri=https://app.example.com/callback &response_type=code &scope=openid+email+profile

Step 5 — Claims & JIT Provisioning

CIE userinfo claims are mapped to Clavex user fields automatically. The fiscal number arrives prefixed TINIT-; Clavex strips the prefix before storing it.

CIE Claim	Clavex Field	Notes
given_name	first_name
family_name	last_name
email	email	Not always present — CIE may omit it
fiscal_number	cie_fiscal_number (metadata)	`TINIT-` prefix stripped
birthdate	cie_date_of_birth (metadata)
gender	cie_gender (metadata)

With allow_jit: true, a Clavex user account is created automatically on first CIE login. Without it, only pre-existing users (matched by email) can log in via CIE.

Step 6 — Assurance Level

CIE logins are always recorded as eIDAS High assurance (OpenID Connect for Identity Assurance metadata), since they require physical card possession + PIN. This lets you gate sensitive operations — e.g. a check_verified login flow step with upgrade: "cie" — to force an in-session CIE re-authentication when a lower-assurance session (e.g. password-only) needs to be stepped up before a privileged action.

Next: CIE-verified identity claims (fiscal number, name, date of birth) can automatically seed OID4VCI credential offers — e.g. issuing an mDL or IT-Wallet PID immediately after a CIE login. See the eIDAS 2.0 quickstart.

Production note: production access requires registering your Relying Party at id.servizicie.interno.gov.it/idp/registrazioneRP (client_id, redirect URIs, RP signing certificate). The pre-production environment requires no registration — test immediately with the CieID app's test accounts.