Besvar en anmodning

HOP-integration - Digitalt Samtykke

Hvem og hvornår

Bruges af en borger. Borgeren er i gang med et selvbetjeningsforløb hos en anvender, og forløbet kan ikke fortsætte uden et samtykke. Selvbetjeningsløsningen sender borgeren til Digitalt Samtykke, hvor en anmodning automatisk oprettes og udfyldes af borgeren. Efter besvarelsen bliver borgeren sendt tilbage til anvendersystemet.

Hvis borgeren ikke færdiggør besvarelsen af anmodningen, vil den automatisk blive slettet igen, og borgeren skal starte forfra i den selvbetjeningsløsning, som de kom fra.

Kræver anmodningen to samtykkegivere, følger bekræftelsesforløbet bagefter for giver nummer to.

Forudsætninger

  • Myndigheden er tilsluttet Digitalt Samtykke.
  • Anvendersystemet har et OCES-systemcertifikat, og certifikatets subject serial number er registreret som aktivt anvendersystem hos myndigheden.
  • Den samtykkeerklæringsskabelon, der bruges, er på anvendersystemets liste over tilladte skabeloner.

Parametrene skal signeres og krypteres

Parametrene sendes som JWE omkring en JWS i ét formfelt ved navn Body. Opbygningen, certifikaternes roller og registreringen er beskrevet samlet i Signering og kryptering.

Forløbet

Trin 1. Systemet bygger og beskytter parametrene

  1. 1.1 Saml parametrene som JSON. Ét JSON-dokument med de parametre, anmodningen skal oprettes ud fra. Et trin kan angive, hvilke af trinnets valgfrie yderligere valg borgeren får vist. Udelades listen, kommer alle de valgfrie med, og en tom liste giver ingen. Trinnets obligatoriske yderligere valg er altid med.
  2. 1.2 Signér som JWS. Signér JSON-dokumentet med anvendersystemets eget OCES-systemcertifikat (RS256). Se Signering og kryptering for de nøjagtige krav.
  3. 1.3 Pak JWS og certifikat i en envelope. Et JSON-objekt med jws og certificate, hvor certifikatet er den offentlige del af det, der lige har signeret, i PEM-format.
  4. 1.4 Kryptér envelopen som JWE. Kryptér den til Digitalt Samtykkes systemcertifikat (RSA-OAEP + A256GCM). Headeren skal bære x5t#S256, som udpeger det certifikat, der er krypteret til.

Resultatet lægges i formfeltet Body og postes til /api/Integration/{tenantCvr}/SignedConsentResponseParameters. Se endpointet i Swagger UI.

Trin 2. Digitalt Samtykke pakker ud og validerer

Envelopen dekrypteres, signaturen kontrolleres mod det registrerede certifikat, og skabelonen holdes op mod anvendersystemets tilladte skabeloner. Derefter valideres parametrene som ved enhver anden anmodning.

Trin 3. Borgeren udfylder erklæringen

Efter login lander borgeren på besvarelsessiden og tager stilling til samtykkeanmodningen. Giver borgeren samtykke i et trin, tager borgeren også stilling til trinnets yderligere valg.

Trin 4. Svaret sendes tilbage

Svaret beskyttes som parametrene, men med to forskelle: certifikaternes roller er byttet om, og trin 3 springes over. Der er ingen envelope - JWS'en krypteres direkte.

  1. 4.1 Kontrollér at modtageren svarer. Digitalt Samtykke laver et HEAD-kald til RedirectionUrl fra sin egen server. Svarer den ikke, sendes borgeren ikke af sted, men får en "prøv igen" i stedet.
  2. 4.2 Signér og kryptér svaret. Svaret signeres som JWS med det af Digitalt Samtykkes systemcertifikater, anvendersystemet krypterede til og krypteres som JWE til det certifikat, anvendersystemet sendte med i envelopen i trin 1.3.
  3. 4.3 Browseren afleverer svaret. Der bliver lavet en form-post fra brugerens browser med svaret til RedirectionUrl. Felterne i den formular, og modellen inde i envelopen, står under Callbacks på besvar-endpointet: se retursvaret i Swagger UI.

Krav til integrationen

Samtykket kan være afgivet, selv om borgeren ikke kommer tilbage

Samtykket gemmes i Digitalt Samtykke i det øjeblik borgeren svarer, altså i trin 3 - før svaret sendes tilbage i trin 4. Går noget galt derefter, eller går borgeren i stå undervejs, findes samtykket alligevel.

Det forventes derfor at et integrerende anvendersystem kan håndtere følgende:

  • RedirectionUrl skal være en https-adresse. Den skal besvare HEAD uden bivirkninger og kunne modtage en POST på samme adresse. Både Head og POST kan blive forsøgt af flere omgange, og bør derfor kunne håndteres.
  • Før borgeren bliver sendt til Digitalt Samtykke skal man undersøge om borgeren allerede har afgivet det ønskede samtykke. Dette er for at undgå dubletter.
  • Et svar betyder ikke, at der er blevet afgivet samtykke. Borgeren kan have afvist at give de ønskede samtykker. Man bør derfor altid kontrollere, at der blev afgivet de ønskede samtykker.

Datamodel

Den fulde feltliste med typer, længder og svarkoder ligger i Swagger UI under POST /api/Integration/{tenantCvr}/SignedConsentResponseParameters.

Åbn kontrakten i Swagger UI

Prøv det

Testklienten bygger, signerer og krypterer parametrene i browseren og dekrypterer svaret igen. Det er den hurtigste vej til at se, hvordan envelopen skal se ud - kildekoden er læsbar direkte i browseren.

Åbn demoen af besvarelse (åbner i nyt vindue)