# eHerkenning Service Catalogue

# Introduction

In order to publish a service in the eHerkenning network so that organisations can authorise their members to log into those services, data on the service must be published to eHerkenning. This data is published through service catalogues.

The service catalogue is a file specifying the level assigned to each of your services. The catalogue can include details of multiple services and levels. A service catalogue can contain information for multiple services.

# Create service catalogue

Service catalogues define information about your services. Services are indicated through a ServiceID, which contains an Overheids Identificatie Number (OIN, or Organisational Identification Number). The ServiceID format is urn:etoegang:DV:oin:services:service index

The required Level of Assurance for each of your services is listed in the service catalogue. Each service can have its own Level of Assurance. It also indicates what kind of identifying attribute (EntityConcernedTypesAllowed) you want to receive in your application and whether or not you wish to enable eIDAS (Classifier).

TIP

Read more about the eHerkenning service catalogue (opens new window).

To create a service catalogue, copy the following information into a text file and fill it out. Send this file via email to Signicat's Technical Support <technicalsupport@signicat.com> (opens new window). Signicat will ensure the eHerkenning / eIDAS network will subsequently be updated with your changes.

<?xml version="1.0" encoding="UTF-8"?>
<esc:ServiceCatalogue xmlns:esc="urn:etoegang:1.13:service-catalog" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                      xmlns:ds="http://www.w3.org/2000/09/xmldsig#" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                      esc:IssueInstant="2019-12-28T10:19:57Z" esc:Version="urn:etoegang:1.13:53"
                      ID="198d678c-239e-43c4-acf7-b4f6f1f6d8c0">
    <esc:ServiceProvider esc:IsPublic="true">
        <esc:ServiceProviderID><!--OIN van organistatie--></esc:ServiceProviderID>
        <esc:OrganizationDisplayName xml:lang="nl"><!--Naam van organistatie--></esc:OrganizationDisplayName>
        <esc:ServiceDefinition esc:IsPublic="true">
            <esc:ServiceUUID><!--unieke ID genereren via uuidgenerator.net--></esc:ServiceUUID>
            <esc:ServiceName xml:lang="nl"><!--Naam van de Service--></esc:ServiceName>
            <esc:ServiceName xml:lang="en"><!--Naam van de Service--></esc:ServiceName>            
            <esc:ServiceDescription xml:lang="nl"><!--Beschrijving van de Service--></esc:ServiceDescription>
            <esc:ServiceDescription xml:lang="en"><!--Beschrijving van de Service--></esc:ServiceDescription>
            <esc:ServiceDescriptionURL xml:lang="nl">http://example.etoegang.nl</esc:ServiceDescriptionURL>
            <saml:AuthnContextClassRef>urn:etoegang:core:assurance-class:<!--Loa van de Service--></saml:AuthnContextClassRef>
            <esc:HerkenningsmakelaarId>00000003244440010000</esc:HerkenningsmakelaarId>
            <esc:EntityConcernedTypesAllowed>urn:etoegang:1.9:EntityConcernedID:KvKnr</esc:EntityConcernedTypesAllowed>
              <esc:ServiceRestrictionsAllowed>urn:etoegang:1.9:ServiceRestriction:Vestigingsnr</esc:ServiceRestrictionsAllowed>
        </esc:ServiceDefinition>
        <esc:ServiceInstance esc:IsPublic="true">
            <esc:ServiceID>urn:etoegang:DV:<!--OIN -->:services:<!--Service Index--></esc:ServiceID>
            <esc:ServiceUUID><!--unieke ID genereren via uuidgenerator.net--></esc:ServiceUUID>
            <esc:InstanceOfService><!-- UUID of service definition--></esc:InstanceOfService>
            <esc:ServiceURL xml:lang="nl">vul hier een service url in</esc:ServiceURL>
            <esc:ServiceURL xml:lang="en">vul hier een service url in</esc:ServiceURL>
            <esc:PrivacyPolicyURL xml:lang="nl">vul hier een privacy url in</esc:PrivacyPolicyURL>
            <esc:PrivacyPolicyURL xml:lang="en">vul hier een privacy url in</esc:PrivacyPolicyURL>
            <esc:HerkenningsmakelaarId>00000003244440010000</esc:HerkenningsmakelaarId>
            <esc:SSOSupport><!-- a boolean that indicates if the service supports SingleSignOn --></esc:SSOSupport>
            <esc:ServiceCertificate>
        <md:KeyDescriptor use="encryption">
          <ds:KeyInfo>
            <ds:KeyName>..............</ds:KeyName>
            <ds:X509Data>
              <ds:X509Certificate>..............</ds:X509Certificate>
            </ds:X509Data>
          </ds:KeyInfo>
        </md:KeyDescriptor>
      </esc:ServiceCertificate>
        </esc:ServiceInstance>
    </esc:ServiceProvider>
</esc:ServiceCatalogue>

# Configure identifying attributes

By setting a value for EntityConcernedTypesAllowed, you determine which types of identifying attributes (in other words, which kinds of users) are allowed to log into your service. Different values can be used, depending on whether your service is coupled to eHerkenning or eIDAS.

The following values for EntityConcernedTypesAllowed are available for:

# 1. eHerkenning

Value	Description
EntityConcernedID:RSIN	Used to identify a user through the RSIN (Rechtspersonen en Samenwerkingsverbanden Identificatienummer) (Legal persons and Partnerships Identification Number) of the represented organisation.
EntityConcernedID:KvKnr	The KvK number (Dutch Chamber of Commerce number) of the represented organisation.
ServiceRestriction:Vestigingsnr	Can only be used together with EntityConcernedID:KvKnr. The field “vestigingsnummer (nieuwe formaat)” (“branch number (new format)”) as available in the Chamber of Commerce will be included in the response.

# 2. eIDAS

EntityConcernedID:eIDASLegalIdentifier	Identifying attribute to allow a non-legal person (Niet Natuurlijk Persoon) to log into eHerkenning and eIDAS.
EntityConcernedID:Pseudo (opens new window)	Identifying attribute for a consumer in eIDAS.

# Classifier (eIDAS)

By specifying a Classifier element, you can couple your service to eIDAS, instead of eHerkenning. Please use one of these options:

Omit the <Classifier> element	The service is coupled to eHerkenning
Specify a <Classifier> element as shown in the example, i.e. <Classifier>eIDAS-inbound<Classifier>	The service is coupled to eIDAS

Omit the <Classifier> element

The service is coupled to eHerkenning

Specify a <Classifier> element as shown in the example, i.e.

<Classifier>eIDAS-inbound<Classifier>

The service is coupled to eIDAS

If you include ServiceRestriction:Vestigingsnr (opens new window) in the EntityConcernedTypesAllowed field, then users can also log in if they are only authorised to represent a particular branch of the organisation. You must include this restriction in your service. This means that you should craft your application so that the user can only act on behalf of this branch, and not on behalf of the entire organisation.

# Requested attributes

RequestedAttributes allow you to request additional data on the users of your service. The use of RequestedAttributes is optional. Please take note, however, that the eHerkenning specifications do not guarantee that the extra RequestedAttributes are known for each user, and can thus be returned in the response. When logging in via eIDAS, the delivery of attributes is guaranteed for so-called required attributes (verplichte attributen). The optional attributes will only be delivered in eIDAS when they are known to the user that is logging in.

TIP

See the attribute catalogue for more information:

Example of an eIDAS service with RequestedAttributes

<esc:EntityConcernedTypesAllowed>urn:etoegang:1.9:EntityConcernedID:Pseudo</esc:EntityConcernedTypesAllowed>
  <esc:RequestedAttribute Name="urn:etoegang:1.9:attribute:FirstName" isRequired="true">
     <esc:PurposeStatement xml:lang="en">For testing purposes.</esc:PurposeStatement>
     <esc:PurposeStatement xml:lang="nl">Voor testdoeleinden.</esc:PurposeStatement>
  </esc:RequestedAttribute>
  <esc:RequestedAttribute Name="urn:etoegang:1.9:attribute:FamilyName" isRequired="true">
     <esc:PurposeStatement xml:lang="en">For testing purposes.</esc:PurposeStatement>
     <esc:PurposeStatement xml:lang="nl">Voor testdoeleinden.</esc:PurposeStatement>
  </esc:RequestedAttribute>
  <esc:RequestedAttribute Name="urn:etoegang:1.9:attribute:DateOfBirth" isRequired="true">
     <esc:PurposeStatement xml:lang="en">For testing purposes.</esc:PurposeStatement>
     <esc:PurposeStatement xml:lang="nl">Voor testdoeleinden.</esc:PurposeStatement>
  </esc:RequestedAttribute>

TIP

For more information on creating the Service Catalogue, check out the Service Catalogue Manual (in Dutch).

TIP

Would you like more info on which Level of Assurance (LoA) to use for your services? Take a look at the LoA documentation (opens new window) (in Dutch).

← Direct Connection to eHerkenning Broker Example Messages →