Sådan virker HOP

HOP-integration - Digitalt Samtykke

Hvad HOP er

Betegnelsen HOP-integration dækker, at et eksternt system kan integrere et front channel-forløb med Digitalt Samtykke - altså et forløb, der går via brugerens browser og i kontekst af brugerens login-session.

En medarbejder i myndighedens IT-system hopper til en bestemt funktion eller side i Digitalt Samtykke og arbejder videre der. Men Digitalt Samtykke kan også indgå som et led i myndighedens eget selvbetjeningsforløb - og hoppe tilbage, så borgeren fortsætter forløbet i myndighedens selvbetjeningsløsning, når samtykket er indhentet.

Det, der adskiller et HOP fra et almindeligt link, er, at brugerfladen sættes i den ønskede tilstand defineret af parametrene fra HOP-kaldet.

Alle kald skal laves med HTTPS. For de borgervendte brugsscenarier kræves det, at parametrene er signeret og krypteret, for at sikre integriteten i kommunikationen mellem anvendersystemet og Digitalt Samtykke.

På denne side

  • Hvad HOP bruges til - De understøttede brugsscenarier.
  • Prøv det af - Testklienten, der demonstrerer hvert integrationspunkt og samtidig fungerer som reference-implementation.
  • Forløbet - Overblik over det generelle flow i HOP-integrationen.
  • Aktører - Hvad begreberne dækker: anvendersystem, bruger, browser og Digitalt Samtykke.
  • Signering og kryptering - Hvordan de beskyttede punkter sikres, hvilket certifikat der bruges hvor, hvordan et anvendersystem registreres og afgrænses til bestemte skabeloner, og hvor løsningens egne certifikater hentes pr. miljø.

Hvad HOP bruges til

Fire opgaver kan overdrages til Digitalt Samtykke. To udføres af en myndighedsmedarbejder, to af en borger. Hver har sin egen side med forudsætninger og forløb.

  • Opret en anmodning om samtykke

    Medarbejder. Hopper til opret‑anmodning‑siden med felter som skabelon, afsender og sagsnummer forudfyldt, så det samme ikke skrives to steder.

  • Vis samtykkeoversigt

    Medarbejder. Hopper til oversigten over samtykker, eventuelt afgrænset til et bestemt CPR-nummer eller sagsnummer. En JSON-variant kan desuden forudvælge fane, filtre og sortering.

  • Besvar en anmodning

    Borger. En selvbetjeningsløsning hopper til den side, hvor borgeren udfylder samtykkeerklæringen, og får borgeren tilbage bagefter - enten med svaret eller til en kvitteringsside i Digitalt Samtykke.

  • Bekræft en anmodning

    Borger. En selvbetjeningsløsning hopper til den side, hvor borgeren kan bekræfte en anmodning, der er besvaret af en anden borger.

Prøv det af

Testklienten demonstrerer alle fire integrationspunkter og er samtidig reference-implementation: brug browserens "vis kildekode" til at se, hvordan formularerne bygges, signeres og modtages. Linket fører til testklienten i et testmiljø.

Åbn testklienten (åbner i nyt vindue)

Forløbet

Alle integrationspunkter følger samme forløb. Det er kun indholdet af formularen og siden, brugeren lander på, der er forskellig.

HOP-forløbet mellem anvendersystem, browser og Digitalt Samtykke Sekvensdiagram i tre spor. Anvendersystemet kan indlede med en valgfri HEAD-forespørgsel direkte til Digitalt Samtykke for at kontrollere, at løsningen svarer. Derefter sender det en HTML-formular til brugerens browser, som afsender den som en POST til Digitalt Samtykke. Løsningen validerer og gemmer parametrene og svarer med en viderestilling. Browseren følger viderestillingen, brugeren logger ind og løser opgaven. Herefter kalder Digitalt Samtykke anvendersystemets RedirectionUrl direkte med en HEAD-forespørgsel for at kontrollere, at det svarer, og sender så en formular med svaret tilbage gennem browseren. De to HEAD-kald er de eneste, der ikke går gennem browseren. Trin 9 til 11 er omsluttet af en ramme mærket opt med betingelsen "kun når forløbet sender brugeren tilbage" - de udføres altså kun af de integrationspunkter, der sender brugeren tilbage med et svar. Anvendersystem Brugerens browser Digitalt Samtykke 1. HEAD på integrationspunktet - er Digitalt Samtykke oppe? Valgfrit. Serverkald uden om browseren, ingen bivirkninger 2. HTML-formular med parametre 3. POST - application/x-www-form-urlencoded 4. Parametrene valideres og gemmes 5. 302 Redirect med nøglen 6. Browseren følger viderestillingen 7. Login via NemLog-in eller Fælleskommunal Adgangsstyring 8. Brugeren løser opgaven opt [kun når forløbet sender brugeren tilbage] 9. HEAD på RedirectionUrl - er anvendersystemet oppe? 10. HTML-formular med svaret 11. POST til RedirectionUrl

Stabil overførsel af brugeren mellem systemerne

For at sikre, at en bruger ikke sendes til et system, der er nede, understøtter Digitalt Samtykke tilgængeligheds-tjek. For de flows, hvor brugeren sendes tilbage til anvendersystemet, forventes det også, at det understøtter tilgængeligheds-tjek.

Konkret skal den RedirectionUrl, anvendersystemet angav, besvare en HEAD-forespørgsel uden bivirkninger. Kontrollen sker fra Digitalt Samtykkes server og gælder kun de integrationspunkter, der sender brugeren tilbage - altså trin 9-11 i opt-rammen ovenfor. De øvrige punkter slutter i Digitalt Samtykke og stiller ingen krav til anvendersystemet efter selve overdragelsen.

Hvorfor FORM POST og ikke query-parametre

Parametrene sendes som en HTTP FORM POST (trin 2-3) og ikke i URL'en. Dermed fremgår CPR-numre og sagsnumre ikke af browserens adresselinje - og dermed heller ikke af browserhistorik, proxy-logs eller Referer-headere.

Det samme hensyn gælder i anvendersystemets egen ende. Den RedirectionUrl, der angives, bør ikke selv bære CPR-nummer eller sagsnummer som query-parameter, og svaret tilbage modtages som POST. Lægges oplysningerne i en URL, brugerens browser navigerer til, er de tilbage i historik og logs - uanset hvordan de kom frem til jer.

Aktører

Aktører i en HOP-integration
Aktør Beskrivelse
Anvendersystem Det eksterne system, der starter et HOP - enten myndighedens fagsystem, hvor en medarbejder arbejder, eller en selvbetjeningsløsning, myndigheden udbyder til borgere.
Bruger Personen foran browseren - enten en myndighedsmedarbejder, der løser en opgave som led i sit arbejde, eller en borger, der tager stilling til et samtykke.
Browser Brugerens browser. Brugerens login-session benyttes til adgangskontrol.
Digitalt Samtykke Løsningen, brugeren overdrages til, og som sender brugeren tilbage igen.

Signering og kryptering

Digitalt Samtykke benytter JWS/JWE til signering og kryptering i de brugsscenarier, der kræver det.

De fire trin

Forsendelsen bygges i fire trin. Resultatet er én ugennemsigtig streng, der sendes i det angivne formfelt for integrationen. Rækkefølgen er bindende: der signeres først og krypteres derefter, så signaturen ligger inde i krypteringen.

  1. Byg JSON-objektet. Parametrene som ét almindeligt objekt.
    Eksempel: parametrene
    {
      "TenantCvr": "64942212",
      "ConsentDeclarationTemplateId": "3f1b0c4e-8a2d-4d7e-9c11-6b5a2e7f0d31",
      "RequesterId": "a17c9d52-4e88-4b0a-9f3c-2d6e81b4c7a9",
      "SubjectCpr": "0000000000",
      "Consenter1Cpr": "0000000000",
      "RedirectionUrl": "https://selvbetjening.myndighed.dk/samtykke/retur"
    }
  2. Signér som JWS (RFC 7515) med afsenderens eget systemcertifikat, algoritme RS256. Beviser, hvem parametrene kommer fra, og at de ikke er ændret undervejs. Ud over parametrene skal JWS'en bære tre claims: aud, iat og jti. Detaljer om dem står i tabellen nedenfor.
    Eksempel: JWS'en, før og efter signering

    Først lægges de tre claims oveni parametrene fra trin 1. Det er dette objekt, der signeres:

    {
      "TenantCvr": "64942212",
      "ConsentDeclarationTemplateId": "3f1b0c4e-8a2d-4d7e-9c11-6b5a2e7f0d31",
      "RequesterId": "a17c9d52-4e88-4b0a-9f3c-2d6e81b4c7a9",
      "SubjectCpr": "0000000000",
      "Consenter1Cpr": "0000000000",
      "RedirectionUrl": "https://selvbetjening.myndighed.dk/samtykke/retur",
      "aud": "https://digst.dk/digitalt-samtykke",
      "iat": 1756713600,
      "jti": "9c2f5b31-7d40-4e6a-8f12-05b3ac91e7d8"
    }

    Headeren angiver algoritmen:

    { "alg": "RS256" }

    Signeret og kodet bliver de to til compact-formen: tre base64url-segmenter adskilt af punktummer, hvor det sidste er selve signaturen. Forkortet her:

    eyJhbGciOiJSUzI1NiJ9.eyJUZW5hbnRDdnIiOiI2NDk0MjIxMiIsIkNvbnNlbnREZW….NEQm7fJ1xVb…s8Xw
  3. Pak JWS og certifikat i en envelope. Et JSON-objekt med to felter: jws med den signerede streng, og certificate med den offentlige del af netop det certifikat, der signerede, i PEM-format.
    Eksempel: envelopen
    {
      "jws": "eyJhbGciOiJSUzI1NiJ9.eyJUZW5hbnRDdnIiOiI2NDk0MjIxMiIs….NEQm7fJ1xVb…s8Xw",
      "certificate": "-----BEGIN CERTIFICATE-----\nMIIFqTCCA5GgAwIBAgIUY2…\n-----END CERTIFICATE-----"
    }
  4. Kryptér hele envelopen som JWE (RFC 7516) til modtagerens systemcertifikat, med RSA-OAEP og A256GCM. JWE-headeren skal bære x5t#S256, som udpeger det certifikat, der er krypteret til. x5t#S256 er base64url-encoding af certifikatets SHA-256-digest.
    Eksempel: den færdige JWE

    Compact-formen er fem base64url-segmenter. Forkortet her:

    eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00iLCJ4NXQjUzI1NiI6…fQ.Qk9pT2…xZ.9rLm4tGvQpXs2Wd1.7YbN3kHc…tJvA.pS6uZ0nR…mQ

    Kun første segment kan læses uden privatnøglen. Afkodet er det headeren:

    {
      "alg": "RSA-OAEP",
      "enc": "A256GCM",
      "x5t#S256": "71ASDHCgmQc8EA2AOLTzgC1TqaEsmF1aiAu7qtveuzg"
    }
    

Envelopen i trin 3 er vores egen, ikke en standard

JWS og JWE følger deres RFC'er, men { jws, certificate }-envelopen mellem dem er specifik for Digitalt Samtykke.

Certifikatet er med for at Digitalt Samtykke kan kryptere svaret, når man sendes tilbage til anvendersystemet.

Svaret tilbage springer trin 3 over

De fire trin gælder vejen ind til Digitalt Samtykke. På vejen tilbage bygges svaret efter trin 1, 2 og 4: der er ingen envelope - JWS'en fra trin 2 krypteres direkte. Efter dekryptering har anvendersystemet altså en JWS i compact-form, ikke et JSON-objekt med jws og certificate.

Envelopen findes, fordi Digitalt Samtykke skal kunne afgøre, hvem afsenderen er. Den anden vej er der kun én mulig afsender, og det forventes at anvendersystemet i forvejen har løsningens certifikat.

JWS'en retur bærer x5t#S256 i headeren, så det fremgår hvilket af løsningens certifikater der har signeret.

Claims på JWS'en

Påkrævede claims
Claim Værdi og krav
aud Skal være https://digst.dk/digitalt-samtykke.
iat Udstedelsestidspunkt i sekunder siden epoch.
jti Unikt id pr. kald. Genbruges et jti inden for vinduet, afvises kaldet som replay.

Hvilket certifikat bruges hvor

Certifikatets rolle pr. retning
Retning Signeres med Krypteres til
Til Digitalt Samtykke Anvendersystemets eget OCES-systemcertifikat Digitalt Samtykkes systemcertifikat
Fra Digitalt Samtykke Det af Digitalt Samtykkes systemcertifikater, forløbet blev krypteret til Anvendersystemets eget OCES-systemcertifikat

Digitalt Samtykkes egne certifikater offentliggøres pr. miljø - se Miljøer nedenfor.

Registrering af anvendersystemets certifikat

Før et anvendersystem kan bruge de signerede integrationspunkter, skal systemet registreres på myndigheden i Digitalt Samtykke. Dette gøres ved at kontakte Digitaliseringsstyrelsen på digitaltsamtykke@digst.dk. Registreringen kræver den offentlige del af et validt OCES-certifikat, som anvendersystemet benytter ved kommunikation med Digitalt Samtykke.

Forny frem for at udstede nyt

Et OCES-certifikat beholder sit subject serial number ved fornyelse. Fornyer man certifikatet inden udløb, kræver det derfor ingen ændringer i registreringen i Digitalt Samtykke.

Tilladte skabeloner pr. anvendersystem

Certifikatet fastslår, hvem anvendersystemet er. Registreringen fastlægger derudover, hvad systemet må: hvilke af myndighedens samtykkeerklæringsskabeloner netop det anvendersystem må bruge. Listen aftales ved registreringen og kan udvides senere.

De signerede integrationspunkter afviser kaldet, hvis det peger på en skabelon, anvendersystemet ikke er registreret til. Tages en ny skabelon i brug, skal den derfor tilføjes til listen først.

Digitalt Samtykkes certifikater pr. miljø

Løsningens egne systemcertifikater offentliggøres pr. miljø.

Offentliggjorte systemcertifikater
Miljø Certifikater
Produktion samtykke.borger.dk/certifikater
Præproduktion web-pp-digitaltsamtykke.digst2.govcloud.dk/certifikater

Når et certifikat nærmer sig udløb, offentliggøres afløseren i god tid. I den periode er begge gyldige, og et anvendersystem kan frit vælge, hvilket det benytter.
Rækken "Thumbprint (SHA-256)" indeholder den forventede værdi til x5t#S256-headeren for certifikatet.