Interface specifications HM-MR chain authorization

This page describes the messages for the backchannel interface between an Herkenningsmakelaar (HM) (broker) and a Machtigingenregister (MR) (authorization information provider).

Elektronische Toegangsdiensten only supports chains with one intermediary:

User_G (user) > Intermediary_A > ServiceConsumer_B.

The Intermediary_A registers a mandate for User_G at MR1 and the ServiceConsumer_B registers a mandate for Intermediary_A at MR2. MR2 has no user-interaction, therefore the User_A has to select ServiceConsumer_B (including appropriate MR2) at MR1 in order to proceed with chain authorization flow. MR1 can use discovery-services (of all MR2) during mandate registration of Intermediary_A or during user authorization flow.

MR1 receives a HM-MR request

After receiving the AD-response, the HM forwards User_G via a HM-MR request to MR1. At that point the MR1 will decide together with the User_G if the request will be a standard or 'authorisation-chain' request. In the case of a chain authorisation the the rules for processing will be slightly different than described in Interface specifications HM-MR. Below only the differences to default HM-MR process rules are described per 'subsection'.

Rules for processing request

Subsection

Differences to default HM-MR process rules

A receiving MR MUST provide an Assertion:

MR1 will create a XACMLAuthzDecision Statement in the Authorisation assertion containing:
- a <Obligations> element that MUST contain the EntityID of MR2 in urn:etoegang:core:RequireConfirmationFromNextMR attribute
- a <Request><Subject> element that MUST contain an LegalSubjectID with and EncryptedID only for MR2 (not for the ServiceProvider, MR2 wil add the appropriate ECTA's for ServiceConsumer_B )
- a <Request><Resource> element that:
  - MUST contain an IntermediateEntityID generated of the type urn:etoegang:1.9:IntermediateEntityID:KvKnr OR urn:etoegang:1.13:IntermediateEntityID:TRR-BD. Other intermediary entity ID's MUST NOT be included.
  - MUST contain the ServiceID and ServiceUUID for which the User_G MUST has a mandate from Intermediary_A and for which Intermediary_A SHOULD have a mandate from ServiceConsumer_B at MR2. MR1 can use MR2 discovery service to determine appropriate ServiceUUID. For Portal Request see "ServiceUUID and Portal Request" infobox below.
  - MUST ignore requested attributes (MR2 wil provide ServiceConsumer_B attributes and eHerkenning does not have attributes for Intermediary other than CompanyName).

Rules for processing response

Subsection	Differences to default HM-MR process rules
A receiving HM:	Determines 'Authorisation Chain' flow IF the MR1-assertion specifies MR2 in the urn:etoegang:core:RequireConfirmationFromNextMR element in <XACMLAuthzDecision Statement><Obligations> Determines the appropriate AD-assertion based on the AssertionIDRef in the <Advice> element of the MR1-Assertion. This AssertionIDRef references the AD-Assertion this MR1-Assertion is directly linked to.

Examples

Example of Response with Obligations

TEXT

<xacml-context:Response xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
	<xacml-context:Result>
		<xacml-context:Decision>Permit</xacml-context:Decision>
			<xacml-context:Status>
				<xacml-context:StatusCode Value="urn:oasis:names:tc:xacml:1.0:status:ok" />
			</xacml-context:Status>
			<xacml-policy:Obligations>
				<xacml-policy:Obligation ObligationId="urn:etoegang:core:RequireConfirmationFromNextMR" FulfillOn="Permit">
				<xacml-policy:AttributeAssignment DataType="http://www.w3.org/2001/XMLSchema#string"
				 AttributeId="urn:etoegang:core:AuthorizationRegistryID">urn:nl:eherkenning:MR:99999900000001:entities:0017
				</xacml-policy:AttributeAssignment>
			</xacml-policy:Obligation>
		</xacml-policy:Obligations>
	</xacml-context:Result>
</xacml-context:Response>

HM requests MR2 via SOAP interface

This query and response resemble the XACMLAuthzDecisionQuery and Response as described in Interface specifications HM-MR, but differs on the following aspects.

Rules for processing request

Subsection

Differences to default HM-MR process rules

A requesting HM:

MUST get MR2 EntityID from MR1-assertion from <Obligations> element
Create a SOAP-message with an XACMLAuthzDecisionQuery in the message body and send this message via a SOAP backchannel to MR2
XACMLAuthzDecisionQuery MUST provide
- a verbatim copy of both the MR1-Assertion and AD-Assertion in <Extensions><Assertion> element:
  - MR1-Assertion is copied from MR1-response
  - AD-Assertion is copied from (the original) AD-response as referenced to by the AssertionIDRef in the <Advice> element of the above MR1-Assertion
- a LegalSubjectID in <Request><Subject> containing the appropriate EntityConcernedID of the ServiceConsumer_B (default is KvKnr) as an EncryptedID@MR2 (not as an EncryptedID@DV!)
- an IntermediairyEntityID in <Request><Subject> containing exactly one value with Intermediary KvK-nr (urn:etoegang:1.9:IntermediateEntityID:KvKnr)
- ServiceID and ServiceUUID in <Request><Resource> which MUST be copied from <Request><Resource> in MR1-assertion

Rules for processing request

Subsection

Differences to default HM-MR process rules

A receiving MR MUST provide an Assertion:

MR2 recognizes this as a claim confirmation request based on the presence of the urn:etoegang:1.9:IntermediateEntityID:KvKnr OR urn:etoegang:1.13:IntermediateEntityID:TRR-BD attribute in the MR1 assertion (in<Request><Resource> element of the XACMLAuthzDecision Statement).
MR2 MUST use ServiceUUID(s) from MR1.assertion (instead of HM-request) to determine response. ServiceID's for which the Intermediate has a valid mandate.
MUST provide and <Advice> element containing an AssertionIDRef referencing to the MR1-assertion (not AD-Assertion!), see Linking of Assertions.
MUST provide an <XACMLAuthzDecision>
- containing in <Subject>
  - a <LinkedDeclarationSignatureValue> with Signature value of the MR1-Assertion referenced to via AssertionIDRef in <Advice> element mentioned above.
  - NO <ActingSubjectID> (or <ActingEntityID> in case of backward compatibility), because MR1 should add ActingSubjectID not MR2
  - a <LegalSubjectID> with the appropriate ECTA's and identifiers (see infobox on HM-MR page) for ServiceConsumer_B based on the requested ECTA-set as described in the ServiceCatalog for the original ServiceUUID/ServiceID that is requested by the DV and added as Attribute in the AD-assertion (which is included in the HM-MR2 request).
- containing in <Resource>
  - IF Intermediate.CompanyName (of Intermediate_A) is not available THEN 'Deny' and start Error Handling
  - IF available SP-certificate THEN an extra EncryptedAttribute@SP with the Intermediate.CompanyName (of Intermediate_A as known by the ServiceConsumer_B) as a value of urn:etoegang:1.13:attribute-Intermediate:CompanyName
  - IF NOT available SP-certificate THEN continue without Intermediate.CompanyName
  - IF any attributes of ServiceConsumer B are requested, MR2 MUST assume UserConsent
  - the ServiceID and ServiceUUID with value(s) identical to MR1 assertion for which Intermediary_A the MUST have a mandate from ServiceConsumer_B, otherwise Deny

ServiceUUID and Portal Request

A ServiceUUID (value) in the specifications always represents a ServiceInstanceUUID, which is a DV-specific ServiceInstance of a ServiceDefinition. A ServiceDefinition is identified using a ServiceUUID which is can be referred to as a ServiceDefinitionUUID. Mandates are registered on a ServiceDefinition (not a DV-specific ServiceInstance). Therefor MR1 and MR2 have to check on valid mandates by looking up the ServiceDefinition belonging to the requested ServiceInstance.

MR2 is not allowed to extent or reduce the ServiceInstance-list in MR1 assertion. Even more, MR2 will Deny the request if Intermediairy_A does not have a valid mandate for all of the services in this list. To prevent such a deny, MR1 should be very carefull composing the ServiceInstance-list and only add ServiceInstance's in the response for which the Intermediary has a mandate (from ServiceConsumer_B) at MR2. MR1 can use DiscoveryService for this purpose.

Intermediate.CompanyName

is the name of the Intermediate Company that MR2 uses when ServiceConsumer_B is registering or managing mandates for this intermediate. The Intermediate CompanyName is either the registered official name or trade name (KvK: statutaire naam of handelsnaam). CompanyName has a value of urn:etoegang:1.13:attribute-Intermediate:CompanyName. MR2 always has to return the Intermediate CompanyName. Except when the ServiceProvider does not have an encryption certifiate in the ServiceCatalog for this service. Because attributes always need to be encrypted.