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.
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ø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.
-
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" } -
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,iatogjti. 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 -
Pak JWS og certifikat i en envelope. Et JSON-objekt med to felter:
jwsmed den signerede streng, ogcertificatemed 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-----" } -
Kryptér hele envelopen som JWE
(RFC 7516) til modtagerens
systemcertifikat, med
RSA-OAEPogA256GCM. JWE-headeren skal bærex5t#S256, som udpeger det certifikat, der er krypteret til.x5t#S256er 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…mQKun 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
| 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
| 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ø.
| 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.