Skip to content

eIDAS (EU Cross-Border)

Sign in EU citizens from across the Union with eIDAS cross-border login. The connector is included; connecting to production runs through your national eIDAS node (see below).

What it is

eIDAS is the European framework for cross-border electronic identification: a citizen authenticates with their own national eID and is recognised by services in another member state through the eIDAS network. With HelixIAM the eIDAS connector is built in: you add it from the identity-provider wizard, and the realm can authenticate citizens from across the EU, provisioning the user just-in-time and mapping the cross-border identity into your realm.

Out-of-the-box pan-European citizen login is one of HelixIAM's flagship differentiators — reach into every member state without building bespoke integrations.

eIDAS is an identity provider with protocol: "eidas". It builds on the SAML 2.0 SP profile (signed AuthnRequest, encrypted assertion) and reads the eIDAS minimum dataset — the PersonIdentifier and name attributes — from the assertion returned by your national eIDAS node.

Watch: start an eIDAS connection

58 seconds, no sound. Choose eIDAS in the identity-provider wizard, set the alias and minimum level, tick the attribute mappers and create the connection (on a localhost installation this is a local trial), then open its eID & assurance tab (Beta). Fictitious example values only. Recorded on the current release.

In the console

  1. Open Identity providers (under Federation & eIDs), click Add identity provider and choose eIDAS (EU).
  2. Choose the Minimum level (low, substantial or high), add mappers for the eIDAS minimum dataset (PersonIdentifier and names) if you need them, and create the connection. There is no trust-material step in the wizard: the node's details come from its metadata on the next screen. The connection starts switched off.
  3. On the connection's eID & assurance tab, answer Is this for a Dutch service?, set Your service, and under The eIDAS node click Import metadata (URL or file). Enter the Fingerprint from the node's operator and click Confirm signer and import.
  4. Under Your metadata, copy the Entity ID and metadata address or download the Signed metadata file, and give it to the node operator.
  5. Switch the connection on once the node's signer is confirmed.

The full setup is in DigiD and eIDAS setup.

Entity ID and https

Your entity ID is the address the server publishes your metadata at, and cannot be changed: IDP_BASE_URL + /realms/{realm}/broker/{alias}/eidas/metadata, for example https://auth.example.com/realms/acme/broker/eidas/eidas/metadata. The wizard and the connection screen take it from the server.

eIDAS requires https. When IDP_BASE_URL is plain http on any host other than localhost, 127.0.0.1 or [::1], no eIDAS connection can be saved, and the console says so up front; set IDP_BASE_URL to the https address and restart the server. A plain-http IDP_BASE_URL on localhost (the quick start) is a local trial: you can create the connection and download its metadata, but the console marks it as not for production, because an eIDAS node accepts only https.

Operational note — production accreditation

The eIDAS connector is built in and configurable now. Connecting to production is a formal process: you connect through your national eIDAS node, which carries its own admission and accreditation requirements. Plan that accreditation track separately from the technical configuration, which you can complete immediately.

Over the API

eIDAS is created like any identity provider, with protocol: "eidas". The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

Create an eIDAS connector

First read the entity ID and ACS URL the server publishes for the alias. publishable is false when nothing can be saved (plain http on a public host); localTrial is true on plain-http localhost.

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers/eidas/eidas/sp-addresses"
{
  "entityId": "https://auth.example.com/realms/acme/broker/eidas/eidas/metadata",
  "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/eidas/callback",
  "publishable": true,
  "localTrial": false
}

Then create the connection, switched off, with those addresses. The node's endpoints and signing certificate come from its metadata, imported afterwards; the SP keys are made in the realm's key store.

# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "alias": "eidas",
        "protocol": "eidas",
        "displayName": "eIDAS",
        "enabled": false,
        "config": {
          "scheme": "eidas",
          "spType": "public",
          "minimumLoa": "substantial",
          "spEntityId": "https://auth.example.com/realms/acme/broker/eidas/eidas/metadata",
          "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/eidas/callback",
          "responseBinding": "post"
        }
      }' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers"

# Import the node's metadata, confirming its signer with the operator's fingerprint
curl -s -b cookies.txt -H "X-XSRF-TOKEN: $CSRF" -H "Content-Type: application/json" \
  -d '{"url":"https://eidas-node.example/EidasNode/ConnectorMetadata","confirmSigner":"AB:CD:…"}' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers/eidas/eidas/node-metadata"

An entity ID that is not the published address is refused with the code eidasEntityIdNotPublished; a save on a plain-http public base URL with eidasHttpsBaseRequired.

Config keys

spEntityId and assertionConsumerServiceUrl (from sp-addresses), minimumLoa (low, substantial, high, or the http://eidas.europa.eu/LoA/* URN; an unknown value is refused with 400), spType (public or private, required to enable the connection), subjectAttribute (defaults to the PersonIdentifier) and responseBinding. The node's idpEntityId, ssoUrl and idpSigningCertificate are set by the metadata import.

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /identity-providers · POST /identity-providers List / create providers
GET · PUT · DELETE /identity-providers/{alias} Read / update / delete a provider
GET /identity-providers/{alias}/eidas/sp-addresses The entity ID and ACS URL the server publishes (entityId, assertionConsumerServiceUrl, publishable, localTrial)
POST /identity-providers/{alias}/eidas/node-metadata Import the node's metadata (url or xml, and confirmSigner)
GET /realms/{realm}/broker/{alias}/eidas/metadata (protocol endpoint, public) Your signed SP metadata, for the node operator

See Identity providers for the shared flow, and the API reference for every field.

See also