Interface specifications DV-HM RequestADlist
For preselection of an AD by the user at the DV, the DV retrieves a list of relevant AD's for that service from the HM (that the HM compiles from network metadata), to complete AUC8 Verkrijgen lijst Authenticatiediensten.
DV-HM sequence diagram |
---|
RequestADlist (1)
A DV may request a list of all accredited ADs, by making a HTTP GET request at an endpoint provided by its HM.
Parameter | 0..n | Description |
---|---|---|
ServiceUUID | 1 | ServiceUUID is an identifier of a ServiceInstance as listed in the Service catalog. Provided here to refer to the service for which the list is requested. |
RequestedAuthnContext | 0..1 | Optionally, an additional parameter 'RequestedAuthnContext' MAY be included with a LoA equal to or lower than listed in the Service Catalog. |
Example RequestADlist
GET /listAD.xml?ServiceUUID=a392d917-d965-4cb8-bff4-238694fc3336 HTTP/1.1
Host: hm.example.nl
Processing rules for RequestADList
A requesting DV:
- MUST supply the ServiceUUID registered in the Service Catalog for the ServiceInstance for which authentication will be requested as the 'ServiceUUID' parameter.
- MAY optionally request the list of ADs for a LoA equal to or lower than listed in the Service Catalog.
A receiving HM:
- MUST validate a request.
ProvideADlist (2)
A HM MUST respond with a signed list of valid, applicable and accredited ADs for the requested service. This list MUST be a subset of the Network metadata.
The list is a signed SAML EntitiesDescriptor, containing one EntityDescriptor per AD or two in case validity dates are used as in Metadata for participants.
Each EntityDescriptor contains one IDPSSODscriptor with one or more SingleSignOnService elements and one Organization element. The Orgnization element contains a OrganizationName, OrganizationDisplayName and OrganizationURL, as per SAML metadata specification. Other element and attributes as described in Metadata for participants MAY be present.
Example ProvideADlist (SAML metadata)
<md:EntitiesDescriptor
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:eme="urn:etoegang:1.11:metadata-extension">
<ds:Signature>...</ds:Signature>
<md:EntityDescriptor entityID="urn:etoegang:AD:...">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:SingleSignOnService Location="https://..." Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" eme:name="app" />
<md:SingleSignOnService Location="https://..." Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" eme:name="web" />
</md:IDPSSODescriptor>
<md:Organization>
<md:OrganizationName xml:lang="nl">AD A</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="nl">AD A</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="nl">https://...</md:OrganizationURL>
</md:Organization>
</md:EntityDescriptor>
<md:EntityDescriptor entityID="urn:etoegang:AD:...">
<md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:SingleSignOnService Location="https://..." Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" />
</md:IDPSSODescriptor>
<md:Organization>
<md:OrganizationName xml:lang="nl">AD B</md:OrganizationName>
<md:OrganizationDisplayName xml:lang="nl">AD B</md:OrganizationDisplayName>
<md:OrganizationURL xml:lang="nl">https://...</md:OrganizationURL>
</md:Organization>
</md:EntityDescriptor>
</md:EntitiesDescriptor>
Processing rules for ProvideADlist
A responding HM:
- MUST provide a subset of the Network metadata, containing all applicable ADs for the requested service. The subset:
- MUST contain all valid ADs supporting at least a LevelOfAssurance equal to or greater than the minimum requested level of assurance.
- The eIDAS Berichtenservice (EB) MUST NOT be included as one of the valid ADs.
- MUST contain the requested NameIDFormat(s) (=EntityConcernedType).
- MUST contain values holding an exact copy of the corresponding values in the Network metadata.
- MUST be sorted alphabetically by OrganizationDisplayName.
- MUST not contain any other entries.
- MUST contain all valid ADs supporting at least a LevelOfAssurance equal to or greater than the minimum requested level of assurance.
- MUST sign this metadata using its own certificate as listed in the Network metadata for signing.
A receiving DV:
- MUST validate the signature on the response before processing the response.
- MUST display all ADs using the OrganizationDisplayName in the provided list when presenting a User the list for AD preselection.
- MUST display all ADs in the order of the list provided by the HM.
- MUST use the entityID of the EntityDescriptor and Location attribute of the SignleSignOnService element corresponding with the User's selection to populate the IDPEntry in the Scoping element.
- In case of the eIDAS-berichtenservice (EB).
- The DV MUST use a separate login-link for the eIDAS-berichtenservice (EB), and MUST NOT present the EB in the eHerkenning list of AD's (see GUC1 Gebruiken eToegang als dienstafnemer).
- MAY use the ISOName to change the language settings for a user.
- SHOULD ignore other elements and attributes in the list.
- SHOULD take 'validFrom' and 'validUntil' of entries into account.
- SHOULD cache the list received from an HM per service, for the duration of maximum 15 minutes. The DV MUST NOT use a list older than 30 minutes for presentation to a User; in case the list expires the DV MUST forwarded the User to the HM as if no pre-selection is implemented.