For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Connect with an authentication protocol

When an end-user wants to authenticate with your services using eHerkenning, your application sends/receives a series of requests/responses to/from Signicat eID and Wallet Hub, which acts as message broker between your application and the eHerkenning network.

To manage the communication between your application and the Signicat eID and Wallet Hub, you connect using an authentication protocol.

Prerequisites​

This guide assumes you have completed the steps in the following guides:

  1. Initial preparations.
  2. Manage certificates.
  3. Add eHerkenning in the Dashboard.
  4. Set up a service in the service catalogue.

Set up a connection​

With Signicat you can integrate using the following authentication protocols:

Picking a protocol

OIDC and SAML 2.0 are official identity protocols. We recommend using OIDC since implementing SAML 2.0 involves more advanced steps.

The Authentication REST API - developed and maintained by Signicat - offers more flexibility and supports headless and redirect integration flow(s) (grant type).

You can find integration guides and more information about each protocol in the Signicat eID and Wallet Hub documentation.

Want to learn more?

For general information about integrating with Signicat, see the eID and Wallet Hub Quick start guide.

Authentication requests​

The authentication protocol you integrate with determines how you build an authentication request and the format of the parameters you use. With eHerkenning, you can also configure provider-specific aspects like scoping the eID and the service. This allows you to skip selection screens and route the user directly to the service you intend to use for authentication.

Requesting LoA​

When starting an authentication session, you can specify your desired Level of Assurance (LoA). Read more about which LoA to choose for your services.

eHerkenning supports the following LoA levels:

LoA is a maximum ceiling

The Level of Assurance configured for a service in the Service Catalogue is a strict maximum ceiling. If an authentication requests a higher LoA than configured for that service index, Signicat rejects the transaction with an error.

Requesting LoA in your authentication request

Note that the LoA low parameter maps to the deprecated eHerkenning level 2, not 2+. To request a specific LoA, you need to follow these guidelines:

  • 2+: Omit the loa parameter so Signicat uses the LoA configured for the service in your Service Catalogue (or your default eID rule in Dashboard > eID and Wallet Hub > Advanced > eID rules).
  • 3: Include substantial (for example, in OIDC use acr_values=idp:eherkenning loa:substantial).
  • 4: Include high (for example, in OIDC use acr_values=idp:eherkenning loa:high).

How you pass the LoA in your requests varies per authentication protocol:

To specify the LoA with OIDC, define acr_values=loa:<LoA> in your authorisation request. For example, to ask for LoA high:

OIDC Authentication request with LoA
https://example.sandbox.signicat.com/auth/open/connect/authorize?
client_id=sandbox-vivid-blade-759
&response_type=code
&redirect_uri=https://oauth.tools/callback/code
&state=1734687023840-WGZ
&scope=openid%20profile%20nin
&code_challenge=7aEnwazbpKXHjOYbISsHWbtAWn33fE9cgDpS0y4-0UM
&code_challenge_method=S256
&acr_values=idp:eherkenning%20loa:high

Scoping eHerkenning services​

When starting an authentication session, you can specify a service that you defined in your eHerkenning service catalogue. This allows you to target one service in particular by using its index value. As a result, the end-users are automatically routed to the service you pass in your authentication request thus skipping any service selection screen.

When sending an authentication request with OIDC, the acr_values attribute allows you to provide additional parameters. To pass the eHerkenning service index, you need to provide the index with the service_index:SERVICE_INDEX parameter in the ACR Values. For example, to route to the Service Index 9701, you need to pass 9701 as the value for the service_index property, as shown below:

OIDC Authentication request with service index
https://example.sandbox.signicat.com/auth/open/connect/authorize?
client_id=sandbox-vivid-blade-759
&response_type=code
&redirect_uri=https://oauth.tools/callback/code
&state=1734687023840-WGZ
&scope=openid%20profile%20nin
&code_challenge=7aEnwazbpKXHjOYbISsHWbtAWn33fE9cgDpS0y4-0UM
&code_challenge_method=S256
&acr_values=idp:eherkenning%20service_index:9701

Note that idp:eherkenning allows you to specify eHerkenning as the eID where to direct your end-users therefore skipping the eID provider screen.

Authentication responses​

After the end-user completes the authentication flow, the Signicat eID and Wallet Hub returns an authentication response to your application.

Validate the authentication response

In accordance with the eHerkenning DV-HM interface specifications, your application must verify in its backend that the authentication response matches the assurance level and service required for the transaction before granting access:

  1. Cryptographic signature and request correlation: Verify the signature on the SAML <saml2p:Response> and <saml2:Assertion> (or OIDC ID token) and verify that InResponseTo (SAML 2.0) or state and nonce (OIDC) match the authentication request initiated by your application.
  2. Level of Assurance (LoA): Verify that <saml2:AuthnContextClassRef> in SAML 2.0 (rejecting urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified if a specific LoA is required) or the acr claim in the OIDC ID token meets or exceeds the Level of Assurance required by your service.
  3. eHerkenning service identifier: When your service catalogue contains multiple eHerkenning services or when you scope services using service_index or AttributeConsumingServiceIndex, request and verify that the returned service identifier matches the service your application intended to authenticate the end-user for:
    • SAML 2.0: Verify eherkenningServiceID and eherkenningServiceUUID (or legacy serviceID / serviceUUID / urn:etoegang:core:ServiceID / urn:etoegang:core:ServiceUUID) in <saml2:AttributeStatement>.
    • OpenID Connect: Request the eherkenning-extra scope and verify eherkenning_service_id and eherkenning_service_uuid in the UserInfo response (or serviceID and serviceUUID in the ID token). To prevent end-users from modifying acr_values in the browser URL, we also recommend enforcing Pushed Authorization Requests (PAR) or signed request objects.

Data and attributes​

To view the attributes supported by each authentication protocol and examples of requests and responses, see the Attributes reference page.

Communicating changes​

Once you have an eHerkenning connection, it is important to tell your customers about the new setup. For more information, see the Communication guide.