Datadefinities

Datadefinities voor authenticatiecontext

Author: Sergei Maertens | Status: Draft

Introductie

In de (gemeentelijke) dienstverlening worden producten en diensten geleverd aan klanten. Wanneer het externe klanten betreft, zoals burgers en bedrijven, dan is inloggen (authenticatie) vaak mogelijk of zelfs een vereiste.

De klant heeft er baat bij om op een later moment ook nog de voortgang van de behandeling in te kijken, of moet zelfs in staat zijn om extra gegevens aan te leveren gedurende het behandelproces. Om dit mogelijk te maken, dienen een aantal details van de authenticatie vastgelegd te worden bij de dienstverleningsaanvraag.

Er bestaan een aantal variaties over hoe en in welke mate authenticatie plaats kan vinden, bijvoorbeeld via DigiD, eHerkenning, maar ook machtigingsvormen waarbij een andere partij dan de begunstigde zelf "aan de knoppen zit", bijvoorbeeld DigiD Machtigen en eHerkenning Bewindvoering.

Deze pagina beschrijft een gegevensmodel waarmee de vorm van de authenticatiecontext beschreven wordt. Het schema is te vinden onder de kop

JsonSchema definitie.

Doelen van het gegevensmodel

1. Het aanbieden van een ondubbelzinnige definitie van de gegevens die relevant zijn om een authenticatie te beschrijven, zodat (spraak)verwarring voorkomen kan worden tijdens implementatietrajecten.

2. Een referentie/naslagwerk zijn voor applicaties die (delen van) de authenticatiecontext vastleggen.

3. Machine-leesbaar zijn zodat invoervalidatie zo strikt mogelijk kan toegepast worden door verwerkende applicaties.

4. Het model moet voldoende flexibel zijn om toekomstige ontwikkelingen (bijvoorbeeld bij Logius) op te kunnen nemen met minimale impact, bij voorkeur op een "backwards-compatible" wijze.

Status van dit gegevensmodel

Het gegevensmodel is ontworpen als onderdeel van een opdracht rondom Machtigen door Gemeente Rotterdam en Gemeente Den Haag. Dit ontwerp is tot stand gekomen door Maykin, in overleg en afstemming met Anoigo, Gemeente Rotterdam en Gemeente Den Haag.

De wens is om dit gegevensmodel te beproeven, standaardiseren en onderhouden door een onafhankelijke groep verantwoordelijk voor de governance.

Terminologie

De begrippenlijst zorgt ervoor dat we éénduidig dezelfde betekenis toekennen aan de gebruikte termen.

Authenticatie (authN)

Het (elektronisch) identficeren van een partij (persoon/bedrijf) zodat bekend is wie bepaalde handelingen uitvoert. Niet te verwarren met autorisatie, wat bepaalt of die partij toestemming heeft om de handeling uit te voeren.

Dienst

Een dienst of product, typisch verleend of verstrekt door een gemeente of ander overheidsorgaan. Individuele personen (burgers) of bedrijven hebben typisch behoefte aan producten en/of diensten van de gemeente en moeten zichzelf authenticeren bij het aanvragen hiervan.

Applicatie

Een webapplicatie, portaal of platform waar een persoon/partij zich kan digitaal kan authenticeren om diensten aan te vragen en beheren.

Keten

Een aanvraag doorloopt vaak meerdere applicaties - van aanvraag naar behandeling en eventuele tussenstappen waar interactie tussen de klant (burger/bedrijf) en gemeente kan plaatsvinden. De "aaneenschakeling" van applicaties wordt typisch "de keten" genoemd.

Authenticatiecontext

De verzameling gegevens die beschrijving op welke wijze en in welke hoedanigheid iemand ge-authenticeerd is/was voor een bepaalde dienst of in een applicatie.

Vertegenwoordigde (machtiger, representee)

De partij (persoon/bedrijf) die uiteindelijk de begunstigde/ontvanger is van de dienst(en). De vertegenwoordigde kan vrijwillig of niet-vrijwillige vertegenwoordigd zijn. Dit laatste gebeurt bijvoorbeeld wanneer de Raad van State "bewindvoering" oplegt.

Vertegenwoordiger (gemachtigde, authorizee)

De partij (persoon/bedrijf) die gemachtigd is om namens de vertegenwoordigde te handelen. Deze machtiging kan op vrijwillige basis zijn, of opgelegd via juridische processen.

De vertegenwoordiger kent twee aspecten:

• de juridisch verantwoordelijke (legalSubject)

• de uitvoerende/handelende persoon (actingSubject): de "persoon aan de knoppen". Dit kan bijvoorbeeld een medewerker van een bedrijf zijn.

Voorbeelden: gemachtigde (DigiD), bewindvoerder (eHerkenning), curator (eHerkenning)...

Gegevensmodel

Het gegevensmodel is formeel gedefinieerd in JSON Schema zodat het programmatisch getoetst kan worden.

In de map schemas zijn twee schema's te vinden:

• base.json beschrijft de algemene, minimale structuur waar het schema van een middel aan moet voldoen

• schema.json bevat alle mogelijke sub-schema's en dwingt af dat de gegevens aan één van deze sub-schema's dient te voldoen. De sub-schema's zijn ingericht op de diverse varianten, zoals DigiD met/zonder machtiging, eHerkenning met machtiging, eHerkenning ketenmachtiging etc...

Het gegevensmodel is bewust strikt gedefinieerd:

• enkel bekende attributen mogen opgegeven worden (dit voorkomt toekomstige uitbreidingsproblemen)

• binnen de attributen zijn waar mogelijk vaste-waardenlijsten of patronen vastgelegd, zoals:

  • enum voor mogelijke middelen. Het uitbreiden van deze enum is eenvoudig

  • patronen voor RSIN, BSN, KVK-nummer... Deze zijn beschreven aan de hand van overheidsreferenties.

Optioneel kan een beperking tot een bepaalde vestiging (via het vestigingsnummer) van toepassing zijn. Dit betekent dat de handelende persoon enkel geautoriseerd is op deze vestiging en geen acties mag uitvoeren voor andere vestigingen.

Machtiging voor een bedrijf

In dit geval wordt er gesproken van "ketenmachtiging". Een bedrijf kan gemachtigd zijn om voor een ander bedrijf producten en diensten af te nemen. Bij ketenmachtiging is er geen restrictie op vestigingsnummer mogelijk. In deze situatie is de handelende persoon werkzaam voor het gemachtigde bedrijf, en de begunstigde is het bedrijf dat de machtiging verstrekt heeft. Ketenmachtiging is in principe altijd KVK-naar-KVK.

Het is op dit moment onbekend of ketenmachtiging op basis van RSIN mogelijk is. Binnen de ketenmachtiging is in principe ook een machtiging voor een natuurlijk persoon mogelijk - dit is nog niet gemodelleerd en komt in de toekomst.

Bij een dergelijke machtiging handelt medewerker X voor bedrijf B. Bedrijf B is gemachtigd door bedrijf A om werkzaamheden uit te voeren. Bedrijf A heeft dan weer een machtiging om diensten/producten af te nemen voor natuurlijk persoon Y.

TODO: wat met bewindvoering - dit zou op persoonlijke titel van een bepaalde medewerker zijn, maar is dat met ketenmachtiging ook zo?

Voorbeelden

In de map testdata zijn (fictieve) voorbeelden van authenticatiecontexten opgenomen, die voldoen aan de opgestelde json-schema definities.

Deze dienen ook als representatieve voorbeelden om de schema's beter te begrijpen.

Klik om het schema weer te geven

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "http://localhost/schema.json",
  "title": "JSON schema definition for authentication context data in Dutch government landscapes",
  "type": "object",
  "oneOf": [
    {
      "$ref": "#/$defs/digid/schemas/withoutMandate"
    },
    {
      "$ref": "#/$defs/digid/schemas/withMandate"
    },
    {
      "$ref": "#/$defs/eherkenning/schemas/withoutMandate"
    },
    {
      "$ref": "#/$defs/eherkenning/schemas/withMandate"
    }
  ],
  "$defs": {
    "naturalPerson": {
      "title": "Natural Person",
      "description": "JSON schema to describe a reference to a natural person.",
      "type": "object",
      "required": [
        "identifierType",
        "identifier"
      ],
      "properties": {
        "identifierType": {
          "title": "Identifier type",
          "description": "A natural person is always identified by their BSN (social security number).",
          "const": "bsn"
        },
        "identifier": {
          "title": "Identifier value",
          "description": "BSN which uniquely identifies the authenticated person. Note that the value must follow the format rules for Dutch social security numbers.",
          "type": "string",
          "pattern": "^[0-9]{9}$",
          "format": "nl-bsn"
        }
      },
      "additionalProperties": false
    },
    "_company:kvk": {
      "title": "Identifying attributes for a company by KVK number",
      "type": "object",
      "required": [
        "identifierType",
        "identifier"
      ],
      "properties": {
        "identifierType": {
          "title": "Identifier type",
          "description": "A company can be identified by its chamber of commerce number.",
          "const": "kvkNummer"
        },
        "identifier": {
          "title": "Identifier value",
          "description": "Chamber of commerce number (KVK-nummer) that uniquely identifies the company.",
          "type": "string",
          "pattern": "^[0-9]{8}$",
          "format": "urn:etoegang:1.9:EntityConcernedID:KvKnr"
        }
      }
    },
    "_company:rsin": {
      "title": "Identifying attributes for a company by RSIN",
      "type": "object",
      "required": [
        "identifierType",
        "identifier"
      ],
      "properties": {
        "identifierType": {
          "title": "Identifier type",
          "description": "A company can be identified by its RSIN.",
          "const": "rsin"
        },
        "identifier": {
          "title": "Identifier value",
          "description": "RSIN that uniquely identifies the legal entity.",
          "type": "string",
          "pattern": "^[0-9]{9}$",
          "format": "urn:etoegang:1.9:EntityConcernedID:RSIN"
        }
      }
    },
    "company:actingSubject": {
      "title": "Person acting for an authenticated company",
      "description": "The actual person who authenticated to represent the given company in their actions.",
      "type": "object",
      "required": [
        "identifierType",
        "identifier"
      ],
      "properties": {
        "identifierType": {
          "description": "The identifier is always some encrypted form, specific to the service provider. I.e. the same physical person gets different identifier values when authenting with different service providers.",
          "const": "opaque"
        },
        "identifier": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "company:withoutBranchRestriction": {
      "title": "A company without branch restriction",
      "description": "A 'company', registered in the Chamber of Commerce (KVK). Can be identified by the COC-number or RSIN. No branch restriction implies this refers to the whole company and all its branches.",
      "type": "object",
      "required": [
        "identifierType",
        "identifier"
      ],
      "oneOf": [
        {
          "$ref": "#/$defs/_company:kvk"
        },
        {
          "$ref": "#/$defs/_company:rsin"
        }
      ],
      "unevaluatedProperties": false
    },
    "company:withBranchRestriction": {
      "title": "A company with branch restriction",
      "description": "A 'company', registered in the Chamber of Commerce (KVK). Can be identified by the COC-number or RSIN. A branch restriction only allows 'access' to one of the main company branches. Branch restrictions can only be applied in certain contexts.",
      "type": "object",
      "required": [
        "identifierType",
        "identifier",
        "branchNumber"
      ],
      "allOf": [
        {
          "oneOf": [
            {
              "$ref": "#/$defs/_company:kvk"
            },
            {
              "$ref": "#/$defs/_company:rsin"
            }
          ]
        }
      ],
      "properties": {
        "branchNumber": {
          "title": "Branch number",
          "description": "The branch number imposes a restriction on the acting subject - it is limited to act only on this particular branch of the legal subject.",
          "type": "string",
          "pattern": "^[0-9]{12}$",
          "format": "urn:etoegang:1.9:ServiceRestriction:Vestigingsnr"
        }
      },
      "unevaluatedProperties": false
    },
    "digid": {
      "source": {
        "title": "Means used for authentication",
        "description": "Fixed value to indicate DigiD authentication.",
        "const": "digid"
      },
      "loa": {
        "title": "Level of assurance (betrouwbaarheidsniveaus)",
        "description": "Logius defines the available levels of assurance *and* prescribes what the minimum level must be.",
        "type": "string",
        "enum": [
          "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport",
          "urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract",
          "urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard",
          "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI"
        ]
      },
      "service": {
        "title": "A service reference",
        "description": "DigiD mandates are bound to either a single service or serviceSet (a collection of services). A service is identified by its ID.",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
      "serviceSet": {
        "title": "A set of services (aka theme)",
        "description": "A group of related services for which a mandate can be extended. TODO!",
        "type": "object",
        "required": [
          "id",
          "services"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "services": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/$defs/digid/service"
            }
          }
        },
        "additionalProperties": false
      },
      "schemas": {
        "withoutMandate": {
          "title": "Authentication context data schema for DigiD without mandate",
          "type": "object",
          "required": [
            "source",
            "levelOfAssurance",
            "authorizee"
          ],
          "properties": {
            "source": {
              "$ref": "#/$defs/digid/source"
            },
            "levelOfAssurance": {
              "$ref": "#/$defs/digid/loa"
            },
            "authorizee": {
              "title": "Authorizee (ge-autoriseerde)",
              "description": "The person who is authorized. Because no mandate is involved, the representee and the authorizee are the same person.",
              "type": "object",
              "required": [
                "legalSubject"
              ],
              "properties": {
                "legalSubject": {
                  "$ref": "#/$defs/naturalPerson",
                  "title": "Legal subject",
                  "description": "The legal beneficiary of the service(s). Because no mandata is involved, the acting subject and legal subject are the same person."
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "withMandate": {
          "title": "Authentication context data schema for DigiD with mandate.",
          "description": "DigiD Machtigen (or also known as CombiConnect) is a form of voluntary mandate. A natural person represents another natural person.",
          "type": "object",
          "required": [
            "source",
            "levelOfAssurance",
            "representee",
            "authorizee",
            "mandate"
          ],
          "properties": {
            "source": {
              "$ref": "#/$defs/digid/source"
            },
            "levelOfAssurance": {
              "$ref": "#/$defs/digid/loa"
            },
            "representee": {
              "$ref": "#/$defs/naturalPerson"
            },
            "authorizee": {
              "title": "Authorizee (gemachtigde)",
              "description": "The person who is authorized. Because no mandate is involved, the representee and the authorizee are the same person.",
              "type": "object",
              "required": [
                "legalSubject"
              ],
              "properties": {
                "legalSubject": {
                  "$ref": "#/$defs/naturalPerson",
                  "title": "Legal subject",
                  "description": "The legal, natural person, mandated to act on behalf of the representee."
                }
              },
              "additionalProperties": false
            },
            "mandate": {
              "title": "Mandate context",
              "description": "Additional context describing the extent of the mandate. At least one dimension/property must be provided.",
              "type": "object",
              "required": [],
              "properties": {
                "services": {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "$ref": "#/$defs/digid/service"
                  }
                },
                "serviceSet": {
                  "$ref": "#/$defs/digid/serviceSet"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        }
      }
    },
    "eherkenning": {
      "source": {
        "title": "Means used for authentication",
        "description": "Fixed value to indicate eHerkenning authentication.",
        "const": "eherkenning"
      },
      "loa": {
        "title": "Level of assurance (betrouwbaarheidsniveaus)",
        "description": "afsprakenstelsel.etoegang.nl defines the available levels of assurance *and* prescribes what the minimum level must be. Note that a minimum of loa2plus is required these days.",
        "type": "string",
        "enum": [
          "urn:etoegang:core:assurance-class:loa1",
          "urn:etoegang:core:assurance-class:loa2",
          "urn:etoegang:core:assurance-class:loa2plus",
          "urn:etoegang:core:assurance-class:loa3",
          "urn:etoegang:core:assurance-class:loa4"
        ]
      },
      "role": {
        "title": "Role of the mandate, which determines the level of access to services",
        "description": "The role of a mandate, typically assigned through judicial procedures.",
        "type": "string",
        "enum": [
          "bewindvoerder",
          "curator",
          "mentor"
        ]
      },
      "service": {
        "title": "A service reference",
        "description": "Identifying properties of a service present in the service catalog.",
        "type": "object",
        "required": [
          "id",
          "uuid"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uri",
            "description": "The ServiceID from the service catalog, for example: 'urn:etoegang:DV:00000001002308836000:services:9113'."
          },
          "uuid": {
            "type": "string",
            "format": "uuid",
            "description": "The ServiceUUID from the service catalog."
          }
        },
        "additionalProperties": false
      },
      "mandate": {
        "title": "Mandate context",
        "description": "Additional context describing the extent of the mandate. At least one dimension/property must be provided.",
        "type": "object",
        "required": [],
        "properties": {
          "services": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/$defs/eherkenning/service"
            }
          },
          "role": {
            "$ref": "#/$defs/eherkenning/role"
          }
        },
        "additionalProperties": false
      },
      "mandate:common": {
        "title": "Common properties for eHerkenning auth with mandate",
        "type": "object",
        "required": [
          "source",
          "levelOfAssurance",
          "mandate"
        ],
        "properties": {
          "source": {
            "$ref": "#/$defs/eherkenning/source"
          },
          "levelOfAssurance": {
            "$ref": "#/$defs/eherkenning/loa"
          },
          "mandate": {
            "$ref": "#/$defs/eherkenning/mandate"
          }
        }
      },
      "mandate:naturalPerson": {
        "title": "Authentication context data schema for eHerkenning representing a natural person",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/$defs/eherkenning/mandate:common"
          },
          {
            "type": "object",
            "required": [
              "representee",
              "authorizee"
            ],
            "properties": {
              "representee": {
                "$ref": "#/$defs/naturalPerson"
              },
              "authorizee": {
                "title": "Authorizee (ge-autoriseerde)",
                "description": "The company that is authorized to act on behalf of the representee.",
                "type": "object",
                "required": [
                  "legalSubject",
                  "actingSubject"
                ],
                "properties": {
                  "legalSubject": {
                    "oneOf": [
                      {
                        "$ref": "#/$defs/company:withoutBranchRestriction"
                      },
                      {
                        "$ref": "#/$defs/company:withBranchRestriction"
                      }
                    ]
                  },
                  "actingSubject": {
                    "$ref": "#/$defs/company:actingSubject"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        ],
        "unevaluatedProperties": false
      },
      "mandate:company": {
        "title": "Authentication context data schema for eHerkenning representing a company (ketenmachtiging). There cannot be a branch restriction here.",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/$defs/eherkenning/mandate:common"
          },
          {
            "type": "object",
            "required": [
              "representee",
              "authorizee"
            ],
            "properties": {
              "representee": {
                "$ref": "#/$defs/company:withoutBranchRestriction"
              },
              "authorizee": {
                "title": "Authorizee (ge-autoriseerde)",
                "description": "The company that is authorized to act on behalf of the representee.",
                "type": "object",
                "required": [
                  "legalSubject",
                  "actingSubject"
                ],
                "properties": {
                  "legalSubject": {
                    "$ref": "#/$defs/company:withoutBranchRestriction"
                  },
                  "actingSubject": {
                    "$ref": "#/$defs/company:actingSubject"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        ],
        "unevaluatedProperties": false
      },
      "schemas": {
        "withoutMandate": {
          "title": "Authentication context data schema for eHerkenning without mandate",
          "type": "object",
          "required": [
            "source",
            "levelOfAssurance",
            "authorizee"
          ],
          "properties": {
            "source": {
              "$ref": "#/$defs/eherkenning/source"
            },
            "levelOfAssurance": {
              "$ref": "#/$defs/eherkenning/loa"
            },
            "authorizee": {
              "title": "Authorizee (ge-autoriseerde)",
              "description": "The company that is authorized. Because no mandate is involved, the representee and the authorizee are the same company.",
              "type": "object",
              "required": [
                "legalSubject",
                "actingSubject"
              ],
              "properties": {
                "legalSubject": {
                  "type": "object",
                  "oneOf": [
                    {
                      "$ref": "#/$defs/company:withoutBranchRestriction"
                    },
                    {
                      "$ref": "#/$defs/company:withBranchRestriction"
                    }
                  ]
                },
                "actingSubject": {
                  "$ref": "#/$defs/company:actingSubject"
                }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        "withMandate": {
          "title": "Authentication context data schema for eHerkenning with mandate",
          "type": "object",
          "required": [
            "source",
            "levelOfAssurance",
            "representee",
            "authorizee",
            "mandate"
          ],
          "oneOf": [
            {
              "$ref": "#/$defs/eherkenning/mandate:naturalPerson"
            },
            {
              "$ref": "#/$defs/eherkenning/mandate:company"
            }
          ],
          "unevaluatedProperties": false
        }
      }
    }
  }
}

Toekomst

In de toekomst worden nog een aantal bekende cases concreet uitgewerkt:

• "Custom" authenticatiemiddelen die applicatiespecifiek zijn, zoals een medewerker die met hun organisatieaccount een aanvraag doet voor een klant aan de balie/telefoon/...

• ketenmachtiging / urn:etoegang:1.9:IntermediateEntityID:KvKnr opnemen

• ketenmachtiging + bewindvoering is technisch mogelijk

Referenties

Lijst van gebruikte referenties/naslagwerken.

• Logius begrippenlijst: https://www.logius.nl/begrippenlijst

• Functionele beschrijving DigiD machtigen: https://www.logius.nl/domeinen/toegang/digid-machtigen/documentatie/digid-machtigen-functionele-beschrijving

afsprakenstelsel.etoegang.nl

• Identificerende attributen: https://afsprakenstelsel.etoegang.nl/display/as/Identificerende+kenmerken

• Dienstcatalogus: https://afsprakenstelsel.etoegang.nl/display/as/Service+catalog

• Dienstafnemer: https://afsprakenstelsel.etoegang.nl/display/as/Vertegenwoordigde+dienstafnemer

• Ketenmachtiging:

  • https://afsprakenstelsel.etoegang.nl/display/as/Ketenmachtiging

  • https://afsprakenstelsel.etoegang.nl/display/as/Interface+specifications+HM-MR+chain+authorization

• Achtergrond opake identificatiewaarden: https://afsprakenstelsel.etoegang.nl/display/as/urn%3Aetoegang%3A1.12%3AEntityConcernedID%3ABSN

ketenmachtigingen

• https://www.kpn.com/zakelijk/eherkenning/ketenmachtiging.htm

• https://www.eherkenning.nl/nl/machtigen/ketenmachtiging