Service catalogue
The service catalogue holds the information of your eHerkenning services. Services correspond to distinct administrative functions or processes, such as applying for subsidy or parking permits. A service catalogue can contain multiple services which are shared with the eHerkenning network.
When you define a service in the catalogue, you configure aspects such as the service name, the level of assurance and the user attributes that you want to receive. You also provide a description to communicate clearly the purpose of a service to your end-users.
This page guides you through the steps to configure the eHerkenning service catalogue and add a service in the Signicat Dashboard.
Prerequisites
This guide assumes you have already completed the steps in the following guides:
Authentication settings
The Authentication settings must be configured before creating the service catalogue.
Before you can create a service in the service catalogue, you need to provide some information about your organisation in the Authentication settings. To do this:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > Settings.
- Scroll down to Metadata settings.
- Fill in the following required fields:
- Organisation name
- Organisation display name
- Organisation URL
- Click Save to save the settings.
Note that the organisation name in the Metadata settings will be visible to your end-user during authentication.
Authentication settings
eHerkenning Service Catalogue
After configuring the Authentication settings, you can set up your eHerkenning Service Catalogue.
A Service Catalogue holds information about your eHerkenning services and who has access to them.
Services are characterised by a ServiceID, which contains an Organisational Identification Number (OIN, or Government Identification Number) and a service index. The OIN is retrieved automatically from the information on your PKIo certificate.
How to add a service to the catalogue
To add a new service to the service catalogue, do the following:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > eIDs and choose eHerkenning.
- In the eHerkenning configuration page, select Setup eHerkenning service catalogue.
- Select Add a service.
- Select eHerkenning as a service type. Note that depending on your use case you can choose between these types of service:
- eHerkenning (used by Dutch organisations)
- eIDAS (used by European citizens)
- Configure the service, as explained below in the eHerkenning service configuration.
- Select Add to create the service.
After you add a new service, the changes need to propagate to the eHerkenning network. The process may take up to two hours. Then, you are ready to connect to the service.
eHerkenning service configuration
The service configuration is comprised of three separate categories:
- General
- Certificates
- User attributes
- Requested attributes
Below you find more information about the fields in each category:
General
- Configure as portal service: Tick the checkbox when your organisation has a web service portal that includes multiple eHerkenning services. When ticked, select the name of the portal services to include.
- Select portal services: Select all the services you wish to include in the configuration for your portal service.
- Service index: Every service has an index to distinguish it from the other services you (might) create. This can be any value between 1 and 9999. Note that the 0 index is reserved for the portal function in eHerkenning.
- Level of Assurance (LoA): Select the desired assurance level. Read more about which LoA to choose for your services.
- Service name: Provide a proper and descriptive name for your service (max 64 characters). It should be clear to the users what the service is intended for. Make sure you use a unique service name so no misunderstanding with other services occurs. For example, Apply for a parking permit.
How to choose a service name
It is important to use a clear service name. For example, the names Department 1 or Municipality X may not be clear enough for the user. The user should immediately know what to do based on the name of the service. For example, if your service is used to apply for a subsidy, call it Apply for a subsidy.
If you need help choosing the service name, contact us by creating a support ticket in the Signicat Dashboard or follow the instructions in the official eHerkenning - Handbooks and support. - Service description: Enter a short description of what the service is intended for (max 1024 characters).
- Service description URL: Provide a valid URL to your website, where you explain what the service can be used for.
- Support SSO: Tick the checkbox to enable Single Sign On (SSO). It only works for LoA lower than 4.
Certificate
This section is only available when you want to receive encrypted responses.
- Certificate keyname: The name to help you identify the certificate.
- Upload certificate: Drag and drop a file or click Browse files to upload the (public) PKIo certificate that you want to use to decrypt the eHerkenning payload you receive from Signicat.
Use a PKIo certificate
If you want to receive an encrypted response and decrypt it yourself, you must upload the (public) PKIo certificate. Then, you decrypt the payload in your application's backend by using the private key related to the PKIo certificate.
Note that this certificate is different from the PKIo certificate that you upload to establish a connection with eHerkenning.
To add more certificates, click + Add certificate. The settings above also apply to any extra certificate.
User attributes
- I want to receive: Also known as Entity Concerned Types (ECTAs), these are an Identifier Set and are a combination of one or more identifying attributes. Individual identifiers possible in ECTA sets are: KvK, RSIN, BSN (if allowed), PseudoID, and Pseudo. eIDASLegalIdentifier is currently not yet supported by the EU countries. Here are all the possibilities and combinations per service type:
- kvk (eH)
- rsin (eH)
- bsn (eH / eIDAS)
- kvk+rsin (eH)
- kvk+bsn (eH)
- pseudo (eIDAS)
- pseudoid (eIDAS)
- bsn+pseudoid (eIDAS)
- bsn+pseudo (eIDAS)
- bsn+pseudoid+pseudo (eIDAS)
- eidasLegalIdentifier (eIDAS)
- + Add user attributes: Allows you to add alternative attributes when the attribute you want to receive is not found.
- Support branch offices: If you accept login transactions for branch offices the following applies:
- You must also accept login transactions without branch office number.
- You must respect the restriction to act only for a branch office, to ensure a legally valid legal act has been concluded.
- You may not use the branch office to determine the location, only to determine the limits of the power of representation.
Requested attributes
- Attributes: You may request additional attributes. For more information, check the attribute catalogue (in Dutch). You can make attributes Mandatory or Optional. When you choose Mandatory, the end-user will not be able to log in to your service if they refuse to, or cannot, supply the requested attribute.
Important
Not all attributes are supported or available by the authentication services or authorisation registries. Therefore, do not set optional attributes as "Mandatory" for your service, since that might prevent a portion of users from logging in.
- Purpose statements: When you add a requested attribute, you must provide a purpose statement to explain your end-users the reason for requesting such attribute.
- Privacy policy URL: When you add a requested attribute, you must add a valid URL to your privacy policy. This is required by law and should follow EU privacy regulations.
For further information regarding the obligations and advice on filling in service catalogue entries, refer to the official manual (in Dutch).
To learn more about service catalogue requirements, see the eHerkenning official manual.
Set a default service
You can set a service as your default service where all the authentication flows are directed automatically. Note that you can always override the default service in a specific authentication by passing a parameter in the request.
To set a service as your default service, do the following:
- In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > eIDs.
- Choose eHerkenning.
- In the eHerkenning configuration page, click Setup eHerkenning service catalogue.
- Select Add a service.
To override the default service in an authentication flow, you specify the service index as a parameter in the authorisation request.
You can find more about what query parameters to use with eHerkenning in the Attributes reference.
Next steps
If you want to simulate how an authentication flow would look like, you can test your eHerkenning configuration in the Dashboard.
When you have configured a service in the catalogue, you can connect your application to eHerkenning by using an authentication protocol.