Interface specifications HM-MR
| Sequence diagram HM-MR |
|---|
 |
disclaimer
The example messages below need adjusment because of RFC2134. Contact the beheerorganisatie for more info.
In the interface described here, the use case GUC4 Aantonen bevoegdheid consists of an SAML 2.0 XACMLAuthzDecisionQuery and Response.
A column in a message description that starts with 'SAML:' or 'XACML:' indicates that this is the standard value. A value that starts with 'Elektronische Toegangsdiensten' indicates that the value is specific to Elektronische Toegangsdiensten.
XACMLAuthzDecisionQuery (1)
@ID | SAML: Unique message attribute | |
|---|---|---|
@Version | SAML: Version of the SAML protocol. The value MUST be '2.0'. | |
@IssueInstant | SAML: Time at which the message was created. | |
@ReturnContext | Elektronische Toegangsdiensten: The value MUST be 'true'. | |
@Destination | SAML: URL of the MR on which the message is offered. MUST match the MR's SAML metadata. | |
@Consent | Elektronische Toegangsdiensten: MUST NOT be included. | |
@InputContextOnly | Elektronische Toegangsdiensten: MUST NOT be included | |
Issuer | Elektronische Toegangsdiensten: MUST contain the EntityID of the HM. The attributes NameQualifier, SPNameQualifier, Format and SPProvidedID MUST NOT be included. | |
Signature | Elektronische Toegangsdiensten: MUST contain the Digital signature of the HM for the enveloped message. | |
Extensions | Elektronische Toegangsdiensten:
If the DV queries additional attributes, they MUST be included here by the HM. To this extent, one Elektronische Toegangsdiensten specific RequestedAttributes (see schema) element MUST be included containing the RequestedAttribute elements reflecting the DV's request. The requested attribute(s) MUST be defined in the Attribuutcatalogus and MUST be declared as RequestedAttribute in the Service catalog entry for the requested service. An MR not able to provide these attributes MUST act as specified in the alternative use case described in Attributen niet leverbaar of niet toegestaan. In case of chain authorization, different rules apply with regards to additional attributes, see Vervallen_Interface specifications HM-MR chain authorization. Other elements MUST NOT be included. | |
Request | Subject | Elektronische Toegangsdiensten: MUST contain a transient identifier which must be the same as the one contained in the <Assertion> element. |
Resource | Elektronische Toegangsdiensten: MUST contain the XACML attributes ServiceID and the corresponding ServiceUUID and MAY contain a XACML attribute LevelOfAssurance. When LevelOfAssurance is included in the request, it must contain the same or lower LevelOfAssurance (AuthnContextClassRef) as included in the Service catalog for the requested service. Other XML attributes MUST NOT be included. Other elements MUST NOT be included. An MR MAY ignore requests for additional attributes, but MUST NOT reject the message. | |
Action | Elektronische Toegangsdiensten: MUST contain the XACML attribute Action-ID. | |
Environment | Elektronische Toegangsdiensten: MUST be empty. | |
Rules for processing request
The MR MUST process the EntityConcernedTypesAllowed list.
A requesting HM:
- MUST include a copy of the AD Assertion for the authenticated User under Assertions in the extensions of the request.
IF ketenmachtiging see Vervallen_Interface specifications HM-MR chain authorization.
A receiving MR MUST provide an Assertion:
Determine required data for processing rules:
USE (AD-Assertion) AttributeStatement.Attribute.ActingSubjectID.EncryptedID@MR TO determine ActingSubject
USE Authentication-LoA, Requested.Minimum-LoA, Requested.ServiceRestrictions, ActingSubject and User input TO determine the response.LegalSubject, response.LOA, response.ServiceIDs and response.ServiceRestrictions accoording to Use Case Vaststellen bevoegdheid (or proces with similar result).
USE ActingSubject TO create response.SpecificPseudoniem@SP
USE Requested.EntityConcernedTypesAllowed and response.LegalSubject TO determine response.EntityConcernedTypes and corresponding response.LegalSubject.Identities
USE ActingSubject TO create response.SpecificPseudoniem@SP and response.SpecificPseudoniem@SI
USE XACMLAuthzDecisionQuery.Request.Resource.ServiceUUID TO determine ServiceCatalog.Minimum-LoA, Requested.Attributes, Requested.EntityConcernedTypesAllowed, Requested.ServiceRestrictions, ServiceIntermediation, SP-certificate from the Service Catalog
USE XACMLAuthzDecisionQuery.Request.Resource.ServiceID (<index>=0) TO determine PortalRequest
IF available XACMLAuthzDecisionQuery.Request.Resource.LevelOfAssurance THEN copy this value to Requested.Minimum-LoA ELSE copy ServiceCatalog.Minimum-LoA to Requested.Minimum-LoA.
Copy AD-Assertion - AuthnStatement.LevelOfAssurance to Authentication-LoA
IF (NOT Ketenmachtiging) OR (Ketenmachtiging AND last-MR) THEN
IF (any of the response.EntityConcernedTypes > r1.09 OR any Requested.Attributes) AND no available DV-certificate THEN start Error Handling
MUST provide an <XACMLAuthz-Decision> containing in <Subject> a <LinkedDeclarationSignatureValue> (see Linking of Assertions) with value:
AD-Assertion: Signature
MUST provide a <XACMLAuthz-Decision> containing
IF available SP-certificate THEN
Copy response.SpecificPseudoniem@SP as an EncryptedID@SP in <Subject> to <ActingSubjectID>
Copy all response.LegalSubject.Identities as EncryptedID@SP in <Subject> to <LegalSubjectID>
IF any requested.ServiceRestrictions THEN copy all requested.ServiceRestrictions in <Resource> to <ServiceRestriction> (eg ServiceRestriction:Vestigingsnr)
IF PortalRequest THEN copy all the response.ServiceID's and response.ServiceUUID's in <Resource> to (a multi valued XACML attribute) <ServiceID> respectively <ServiceUUID> (See GUC4.3 Portaalfunctie for more details).
IF requested.attributes AND User consent THEN in <Resource>
IF available SP-certificate THEN copy attributesvalue(s) to an EncryptedAttribute@SP
------- For backward compatibility -------
Copy response.SpecificPseudoniem@SP in <Subject> to <ActingEntityID>
IF NOT eIDAS-BS THEN FOR all EntityConcernedTypes in response.EntityConcernedTypes:
IF EntityConcernedType < r1.11 THEN copy response.EntityConcernedTypes with corresponding response.LegalSubject.Identifier (<value>)in <Resource> to <EntityConcernedID>
-------------------------------------------------
Determine appropriate ECTA and Identifiers:
- all the EntityConcernedTypes in an Identifier Set of EntityConcernedTypes with the same set number in the Service catalog.
- IF no set numbers are used, only one EntityConcernedType is allowed THEN handle this EntityConcernedType as if it was in 1 set.
- all the EntityConcernedTypes in the identifier set with the lowest possible set number the MR can provide for this response.LegalSubject.
- IF MR can't provide for any Identifier Set THEN start Error Handling
- Determine the response.EntityConcernedTypes and the corresponding response.LegalSubject.Identifiers for the selected identifier set
User consent for providing additional attributes can be granted the user OR by the authorization manager of the represented service consumer/intermediary (during the transaction or through prior consent)
All encryption is done using the DV-certificate from the Service Catalog.
Example message
<?xml version="1.0" encoding="UTF-8"?>
<xacml-samlp:XACMLAuthzDecisionQuery xmlns:xacml-samlp="urn:oasis:xacml:2.0:saml:protocol:schema:os" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID=" " Version="2.0" IssueInstant=" " ReturnContext="true" Destination=" ">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
</saml:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI=" ">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>
</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName>
</ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<samlp:Extensions>
<xacml-context:Attribute name="AssertionConsumerServiceIndex" DataType="http://www.w3.org/2001/XMLSchema#unsignedShort" Issuer=" ">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:Assertions" DataType="urn:oasis:names:tc:SAML:2.0:assertion:Assertion" Issuer=" ">
<xacml-context:attributevalue>
<saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_abc123">
<saml2:Issuer>urn:etoegang:AD:...</saml2:Issuer>
...
</saml2:Assertion>
</xacml-context:Attributevalue>
</xacml-context:Attribute>
<saml:Attribute Name="urn:etoegang:core:IntendedAudience">
<saml:AttributeValue>urn:etoegang:DV:OIN:entities:index</saml:AttributeValue>
</saml:Attribute>
<esp:RequestedAttributes>
<md:RequestedAttribute Name="urn:etoegang:1.11:attribute-represented:CompanyName" IsRequired="false" />
</esp:RequestedAttributes>
</samlp:Extensions>
<xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<xacml-context:Subject>
<xacml-context:Attribute AttributeId="urn:oasis:names:tc:SAML:2.0:assertion:NameID" DataType="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" Issuer=" ">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
</xacml-context:Subject>
<xacml-context:Resource>
<xacml-context:Attribute AttributeId="urn:etoegang:core:ServiceID" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue>
</xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:ServiceUUID" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue>
</xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:LevelOfAssurance" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue>
</xacml-context:AttributeValue>
</xacml-context:Attribute>
</xacml-context:Resource>
<xacml-context:Action>
<xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue>Authenticate</xacml-context:AttributeValue>
</xacml-context:Attribute>
</xacml-context:Action>
<xacml-context:Environment>
</xacml-context:Environment>
</xacml-context:Request>
</xacml-samlp:XACMLAuthzDecisionQuery>Response (2)
@ID | SAML: Unique message attribute |
|---|---|
@InResponseTo | SAML: Unique attribute of the XACMLAuthzDecisionQuery to which this response message is the answer. |
@Version | SAML: Version of the SAML protocol. The value MUST be '2.0'. |
@IssueInstant | SAML: Time at which the message was created. |
@Destination | SAML: URL of the HM on which the message is offered. MUST match the SAML metadata. |
@Consent | Elektronische Toegangsdiensten: MUST NOT be included |
Issuer | Elektronische Toegangsdiensten: MUST contain the EntityID of the MR. The attributes NameQualifier, SPNameQualifier, Format and SPProvidedID MUST NOT be included. |
Signature | Elektronische Toegangsdiensten: MUST contain the Digital signature of the MR for the enveloped message. |
Extensions | Elektronische Toegangsdiensten: MUST NOT be included |
Status | Elektronische Toegangsdiensten: MUST be filled conform SAML 2.0 specs when the request is successfully processed. MUST be filled according to Error handling in case of an error or when the request was cancelled. |
Assertion | Elektronische Toegangsdiensten: MUST contain an assertion about the authorization (see the next section). |
Rules for processing responses
A receiving HM:
- MUST verify the structure and contents of the response.
A responding MR MUST:
The MR MUST communicate the Level of Assurance of the registered authorization. A MR MUST NOT communicate a level for which it is not certified.
- In case of a chain of authorizations, the MR MUST communicatie the minimum of the LoA of all Representation authorizations in the applicable chain (so far).
- In case of a request for a portal service, a MR MUST communicate the Level of Assurance as the minimum Level of Assurance of all applicable service authorizations chosen by the user.
Authorization assertion
Assertion | @Version | SAML: Version of the SAML protocol. The value MUST be '2.0'. |
|---|---|---|
@ID | SAML: Unique reference to the assertion | |
@IssueInstant | SAML: Time at which the assertion was created | |
Issuer | Elektronische Toegangsdiensten: MUST contain the EntityID of the MR. The attributes NameQualifier, SPNameQualifier, Format and SPProvidedID MUST NOT be included. | |
Signature | Elektronische Toegangsdiensten: MUST contain the Digital signature of the MR for the enveloped assertion. | |
Subject | Elektronische Toegangsdiensten: MUST contain a different transient <NameID> from the AD Assertion as received in the Request or preceding MR assertion in case of chain authorization. Each assertion MUST contain a new transient identifier, that is unique for the issuer during at least the past 12 months. | |
Conditions | Elektronische Toegangsdiensten: MAY be included. The attributes NotBefore and NotOnOrAfter MAY be included but should be ignored by the receiver. Other conditions MUST NOT be included. | |
Advice | Elektronische Toegangsdiensten: MUST be included, containing an AssertionIDRef referencing the Assertion this declaration is directly linked to. | |
XACMLAuthz-Decision Statement | Elektronische Toegangsdiensten: MUST contain an SAML Statement of the type XACMLAuthzDecisionStatementType. See below. |
XACMLAuthzDecision Statement | Response | Result | @ResourceID | Elektronische Toegangsdiensten: MUST NOT be included |
|---|---|---|---|---|
Decision | XACML: One of the values allowed in XACML 2.0. In the event of a cancellation or error, the element MUST be populated with the value 'Deny'. See also Error handling. | |||
Status | XACML: must be filled with one of the values that are allowed according to the XACML 2.0 specifications | |||
Obligations | Obligation urn:etoegang:core:RequireConfirmationFromNextMR Elektronische Toegangsdiensten: In the event of chain authorization, such is established by the first MR, which then specifies, by means of an Obligation, that the second link MUST be verified or Decision = 'Permit' is otherwise invalid. | |||
Request | Subject | Elektronische Toegangsdiensten: Any received AuthenticationMeansID MUST be deleted and not returned in the response to the HM. If the Decision is ‘Permit’ THEN Depending on the Rules for processing request:
| ||
Resource | Elektronische Toegangsdiensten: MUST contain the attribute-elements contained in the resource element from the request. If the Decision is 'Permit'
NextAuthorizationRegistryID MAY be included. See EntityID. Other attributes MUST NOT be included. | |||
Action | Elektronische Toegangsdiensten: MUST be the same as the Action element in the request. See XACMLAuthzDecisionQuery (above). | |||
Environment | Elektronische Toegangsdiensten: MUST be empty. | |||
Example message
<?xml version="1.0" encoding="UTF-8"?>
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID=" " InResponseTo=" " Version="2.0" IssueInstant=" " Destination=" ">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"> </saml:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI=" ">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue> </ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue> </ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName> </ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"> </samlp:StatusCode>
</samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Version="2.0" ID=" " IssueInstant=" ">
<saml:Issuer> </saml:Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI=" ">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue> </ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue> </ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName> </ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient"> </saml:NameID>
</saml:Subject>
<saml:Conditions NotBefore=" " NotOnOrAfter=" "> </saml:Conditions>
<saml:Statement xmlns:xacml-saml="urn:oasis:xacml:2.0:saml:assertion:schema:os" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xacml-saml:XACMLAuthzDecisionStatementType">
<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:StatusCode>
</xacml-context:Status>
</xacml-context:Result>
</xacml-context:Response>
<xacml-context:Request xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os">
<xacml-context:Subject>
<xacml-context:Attribute AttributeId="urn:etoegang:core:ActingEntityID" DataType="http://www.w3.org/2001/XMLSchema#string" Issuer=" ">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
</xacml-context:Subject>
<xacml-context:Resource>
<xacml-context:Attribute AttributeId="urn:etoegang:core:ServiceID" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:ServiceUUID" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:LevelOfAssurance" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:core:LevelOfAssuranceUsed" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:Attribute AttributeId="urn:etoegang:1.9:EntityConcernedID:KvKnr" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue> </xacml-context:AttributeValue>
</xacml-context:Attribute>
<xacml-context:ResourceContent>
<saml:EncryptedAttribute>
<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" Id="_DE46C6F5E2E3111255D3A715C4760656">
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<xenc:EncryptedKey>
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"/>
<ds:KeyInfo xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
<ds:KeyName>62355fbd1f624503c5c9677402ecca00ef1f6277</ds:KeyName>
</ds:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>.....</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedKey>
</ds:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>.......</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData>
</saml:EncryptedAttribute>
</xacml-context:ResourceContent>
</xacml-context:Resource>
<xacml-context:Action>
<xacml-context:Attribute AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id" DataType="http://www.w3.org/2001/XMLSchema#string">
<xacml-context:AttributeValue>Authenticate</xacml-context:AttributeValue>
</xacml-context:Attribute>
</xacml-context:Action>
<xacml-context:Environment> </xacml-context:Environment>
</xacml-context:Request>
</saml:Statement>
</saml:Assertion>
</samlp:Response>