Fast eIDAS integration in Keycloak: GRNET steps and EUDI Wallet prep

The fastest path to federated eIDAS login is installing a SAML v2.0 extension such as the GRNET eIDAS Keycloak extension, configuring Keycloak as the broker against your national eIDAS node, and mapping the PersonIdentifier through a Username Template Importer. That combination of provider JAR, identity provider configuration, certificate exchange, mappers, and an amended browser flow delivers a working federated login within days, and it also gives you a clean upgrade path towards EUDI Wallet support later.

TL;DR:

• Using the latest supported Keycloak version and pinning extension JARs avoids silent failures during upgrades and ensures compatibility with the extended eIDAS profile.
• Properly matching the node’s metadata certificate and the SP’s country code or CN prevents common rejection errors during certificate exchange.
• Configuring strict signature, encryption, and binding settings, including proper attribute mapping with unique usernames, is critical for a stable and successful eIDAS federation.
• Wallet support requires community plugins for OID4VP, with emphasis on SD-JWT, issuer validation, and testing in isolated staging environments before production deployment.
• Ongoing monitoring for certificate rotations, LoA changes, and mapper stability is essential, as most failures stem from operational issues rather than initial setup errors.

Table of Contents

• Prerequisites and architecture for eIDAS integration Keycloak
• Installing and deploying the eIDAS Keycloak extension
• Configuring the Keycloak identity provider for eIDAS SAML v2.0
• Certificate exchange and the eIDAS security checklist
• Getting ready for eIDAS 2.0 and the EUDI Wallet
• Common pitfalls when integrating eIDAS with Keycloak
• Minimal testing and verification steps
• Implementation considerations from Vicedomini Softworks
• What actually matters in an eIDAS Keycloak build
• How Vicedomini Softworks supports your eIDAS rollout
• Sources
• FAQ

Prerequisites and architecture for eIDAS integration Keycloak

Before touching the admin console, confirm the groundwork is in place. Keycloak’s SAML broker has supported the eIDAS-flavoured dialect since well before recent releases, but the extended profile still depends on third-party providers rather than anything shipped natively.

• Run a supported Keycloak version and confirm you can drop custom provider JARs into providers/ (Quarkus distribution) or the legacy standalone/deployments/ path on older WildFly-based builds.
• Request eIDAS node metadata and a technical contact from your national operator early. Node onboarding queues can take longer than the actual configuration.
• Prepare an SP certificate whose CN or country code matches what the node expects. Some operators reject requests where the certificate country does not align with the registered SP.
• Decide early whether you need the SAML v2.0 broker extension (current eIDAS production nodes) or an OIDC/EUDI Wallet plugin (forward-looking pilots). Most production integrations still need the former.

Installing and deploying the eIDAS Keycloak extension

Once the metadata and certificate requests are in motion, the deployment itself is mechanical. The GRNET eIDAS Keycloak extension remains the reference implementation for the extended SAML v2.0 dialect, bundling an eIDAS SAML v2.0 identity provider type, a Username Template Importer, an Attribute Importer, and a Citizen Country Selection authenticator.

1. Build or download the provider JAR from the extension’s releases and copy it into Keycloak’s providers/ directory.
2. Restart Keycloak and check the startup logs for the provider registering correctly. A missing entry usually means a classpath conflict or wrong Keycloak version.
3. Place your SP keystore and certificate in the resource path the extension expects, then confirm the SP metadata endpoint responds when queried directly.
4. Run a quick smoke check: hit the realm’s SAML descriptor URL and verify it returns valid XML with your entity ID, ACS location, and certificate embedded.

Pro Tip: Keep the provider JAR version pinned in your build pipeline. Extension releases sometimes lag behind Keycloak’s own SAML API changes, and an unpinned dependency will break silently on your next Keycloak upgrade.

If the metadata endpoint returns a 404 or an empty descriptor, the provider almost certainly failed to register. Check the logs before assuming the network path or reverse proxy is at fault.

Configuring the Keycloak identity provider for eIDAS SAML v2.0

The identity provider configuration is where most integrations succeed or fail, because the eIDAS profile enforces stricter defaults than a typical SAML setup. Set the SP Entity ID to your realm’s broker descriptor URL exactly as the node expects it, and point the Single Sign-On Service URL at the eIDAS node’s SAML endpoint rather than a generic identity provider.

Several settings are effectively mandatory rather than optional:

• Enable HTTP-POST bindings for both the AuthnRequest and the response; redirect bindings are rarely accepted by production nodes.
• Require signed AuthnRequests and encrypted assertions. Nodes commonly reject unsigned requests outright rather than returning a helpful error.
• Set the signature algorithm to match the node’s mandate, often RSA_SHA512_MGF1 rather than Keycloak’s older RSA_SHA256 default.

Attribute mapping is where the eIDAS extension earns its place. Add a Username Template Importer mapper using a template like ${ALIAS}.${ATTRIBUTE.PersonIdentifier}, which keeps usernames unique across countries by binding the broker alias to the citizen’s persistent identifier. Add a matching Attribute Importer mapper for each required attribute (given name, family name, date of birth) so they land in the user’s federated profile rather than getting dropped silently.

Configuration examples in the extension’s own documentation show working JSON snippets for requested attributes, which is worth copying rather than reconstructing from scratch. Finally, duplicate the Browser authentication flow and insert the Citizen Country Selection step alongside an Identity Provider Redirector, so users pick their country before Keycloak routes them to the correct node.

Certificate exchange and the eIDAS security checklist

Certificate and metadata mismatches cause more failed integrations than any coding error. The eIDAS node publishes its own SAML metadata document, and you need the X.509 certificate from inside md:IDPSSODescriptor copied into Keycloak’s validating certificates for that identity provider.

• Fetch the node’s metadata XML and extract the signing certificate; paste it into Keycloak’s IdP configuration rather than trusting automatic metadata refresh, since some nodes disable dynamic metadata polling.
• Enable “Sign service provider metadata” on the Keycloak side, then send your SP metadata URL to the node operator so they can register it.
• Confirm your SP certificate’s country code or CN matches what the node’s registration process demands. Practitioner notes from the GRNET extension repository flag this mismatch as a recurring, entirely avoidable cause of rejected requests.
• Check signature and encryption algorithm parity on both sides. A node expecting SHA512 while your SP still signs with SHA256 fails silently rather than throwing a clear error.

Treat this checklist as a pre-flight step for every environment, not a one-off setup task. Staging and production nodes frequently run different certificate rotations.

Getting ready for eIDAS 2.0 and the EUDI Wallet

eIDAS 2.0 shifts the model from synchronous SAML round-trips to asynchronous, wallet-mediated presentation flows, and that changes how Keycloak needs to behave under the hood. Research from the PISTIS project on federated data trading confirms that adding EUDI Wallet support to Keycloak requires session handling and state binding changes, not just a new identity provider type, because the authentication session has to stay valid while the user completes a presentation on a separate device.

Community plugins such as eudi-wallet-keycloak implement the OID4VP verifier SPI: generating a QR code or deep link, building the presentation request, validating the returned verifiable presentation, and mapping its claims into Keycloak’s user attributes.

When evaluating a plugin for this role, check for:

• SD-JWT support for selective disclosure credentials, not just full-credential presentation.
• A trust policy resolver that can validate issuer certificates against a configurable trust list.
• Clear issuer verification modes, since a plugin that trusts any issuer by default is not production-ready.

Pro Tip: Run wallet plugins in an isolated staging realm first. Keycloak’s own issue tracker shows native OID4VP and OID4VCI support is still under active discussion, so community plugins are currently carrying production weight that upstream Keycloak has not fully absorbed yet.

Common pitfalls when integrating eIDAS with Keycloak

Most failures trace back to one of four categories, and diagnosing them quickly saves hours of guessing.

1. Metadata or certificate mismatches: re-fetch the node’s metadata and diff the certificate against what Keycloak currently trusts, since operators rotate certificates without always announcing it.
2. Mapper misconfiguration causing BROKER_ID collisions: if two users end up merged or overwritten, check that your Username Template Importer actually includes the PersonIdentifier rather than a mutable attribute like given name.
3. AuthnContext or Level of Assurance mismatches: a node configured to require substantial or high LoA will reject requests asking for a lower level, often with a vague SAML status code.
4. Signature algorithm rejections: enable SAML tracing in Keycloak’s logs and compare the signed XML against what the node’s own documentation specifies before assuming the certificate itself is invalid.

When logs alone don’t resolve it, ask the node operator directly for their side of the SAML trace. Cross-referencing both traces usually isolates the mismatch within minutes.

Minimal testing and verification steps

A working configuration still needs verification against a real or test node before you trust it in production.

• Trigger sign-in from your application’s account service and confirm the Citizen Country Selection screen appears and redirects to the correct national node.
• After a successful round-trip, inspect the user’s attributes in the Keycloak admin console and confirm PersonIdentifier and the other requested attributes populated correctly.
• Validate that outgoing AuthnRequests are signed and incoming assertions are encrypted, either through Keycloak’s SAML debug logs or an external SAML trace tool.
• Where a test node is available, run repeatable integration tests against it. Example client configurations in projects like keycloak-eid-identity-provider are a useful reference for structuring these tests locally.

Repeat this sequence after every metadata refresh or certificate rotation, not just at initial go-live.

Implementation considerations from Vicedomini Softworks

Delivering an eIDAS integration that survives certificate rotations and node upgrades takes more than following the setup steps once. Vicedomini Softworks approaches these engagements with direct engineer involvement throughout, so architectural decisions around mapper design and broker IDs get made by the people who will maintain them.

• Every deployment goes through peer-reviewed configuration changes, with certificate lifecycle and expiry tracked as a first-class operational concern rather than an afterthought.
• Monitoring and logging get scoped specifically to authentication events, so a failed handshake with the eIDAS node surfaces immediately rather than during a user complaint.
• Mapper templates and broker identifiers are kept stable by design, which matters because a future migration to EUDI Wallet support should not require re-issuing every user’s identity mapping from scratch.

Case studies and delivery examples are helpful for organisations weighing whether to build this internally or bring in dedicated engineering support.

What actually matters in an eIDAS Keycloak build

Most guidance on this topic treats the SAML configuration as the hard part and the operational side as an afterthought. That gets the priority backwards. The GRNET extension’s mappers and authenticator components solve the protocol problem reliably once you follow the documented steps; the failures that actually cost teams weeks are certificate rotation surprises, LoA mismatches nobody flagged until a live node rejected requests, and mapper templates built around attributes that turned out to be mutable.

The conventional advice, treat eIDAS integration as a one-time SAML configuration exercise, is where most teams go wrong. It isn’t one. National nodes rotate certificates, tighten LoA requirements, and occasionally change binding support without much warning, so the integration needs monitoring and a maintenance owner, not just a deployment checklist.

If you are starting from zero, prioritise the PersonIdentifier-based username template before anything else. Get that identity binding right early, because unpicking a broken user mapping after go-live is far harder than fixing a signature algorithm mismatch. Everything else, including EUDI Wallet readiness, builds more easily on top of a stable identity layer than on top of a well-polished SAML handshake with a fragile mapping underneath it.

— Pepe F.

How Vicedomini Softworks supports your eIDAS rollout

An alternative to a generic integration consultancy for eIDAS work is to get direct access to the engineers configuring your mappers and certificate chain, not an account layer relaying instructions between you and whoever actually writes the code.

If your team is weighing whether to build this internally or wants a second set of eyes on an existing SAML broker setup, scoped architecture reviews, integration builds, proof-of-concept pilots, and ongoing maintenance contracts can be arranged around components such as extension deployment, IdP configuration, certificate lifecycle, and monitoring. For teams weighing device-based authentication alongside eIDAS, it’s worth understanding how passkey synchronisation across devices is evolving too, since wallet-based flows share some of the same UX assumptions.

Request a scoped audit or a pilot engagement through the services page and get a concrete assessment of what your current Keycloak setup needs before your next certificate rotation catches you off guard.

FAQ

What is the fastest way to add eIDAS integration to Keycloak?

Install a SAML v2.0 broker extension such as the GRNET eIDAS Keycloak extension, configure it as an identity provider against your national node, and add the Username Template Importer and Attribute Importer mappers.

Does Keycloak support eIDAS natively?

No. Keycloak’s core SAML broker doesn’t ship the extended eIDAS dialect out of the box, so production integrations rely on third-party providers like the GRNET extension for the Citizen Country Selection authenticator and related components.

What is the Username Template Importer used for?

It builds a stable username from federated attributes, typically combining the broker alias with the citizen’s PersonIdentifier using a template like ${ALIAS}.${ATTRIBUTE.PersonIdentifier}, which prevents identity collisions across countries.

Is Keycloak ready for EUDI Wallet and OID4VP flows?

Native support is still under development, so most teams add EUDI Wallet capability through community plugins implementing the OID4VP verifier SPI, alongside session and state-binding changes for asynchronous wallet presentations.

What causes most eIDAS Keycloak integration failures?

Certificate and metadata mismatches, mapper misconfigurations that break user lookups through BROKER_ID collisions, and Level of Assurance or signature algorithm mismatches between the SP and the node account for the majority of failures.