Be om samtykke

Hvordan sende sluttbruker til samtykkesiden i Altinn.

På denne siden:

Overordnet om løsningen

Samtykkeløsningen tilbyr to mekanismer for å innehente et samtykke fra en sluttbruker. I begge tilfellene skal brukeren videresendes til en adresse i Altinn, hvor samtykke blir innfridd.

Den foretrukne mekanismen er forhåndsregistrerte samtykkeforespørsler, som er beskrevet under. Den andre mekanismen er lenkebaserte samtykker, som er å regne som legacy og ikke vil bli videreutviklet. Alle nye integrasjoner mot samtykkeløsningen anbefales å bruke forhåndregistrerte samtykkeforespørsler.

Forhåndsregistrerte samtykkeforespørsler har en rekke fordeler over lenkebaserte samtykkeforespørsler:

  • Mulighet for offline flyter som ikke er avhengige av at brukeren alltid er tilstede (f.eks. visning av innkommende samtykkeforespørsler i portal)
  • Bruk av maler – høy fleksibilitet i hvordan dialogen presenteres
  • Datakonsument kan sjekke status på en gitt samtykkeforespørsel (er den åpnet/innfridd/nektet/feilet?), uavhengig av redirect-URL-flyt
  • Mulighet for server-til-server notifikasjon ved innfrielse/trekking av samtykke (kommer i Q1 2021!)

Forhåndsregistrerte samtykkeforespørsler

For å be om et samtykke kreves det at datakonsument først oppretter en samtykkeforespørsel via REST, for så å sende sluttbrukeren til samtykkesiden.

Merk at dette API-et krever virksomhetsautentisering med virksomhetssertifikat eller Maskinporten-token. Hvis du skal administrere samtykker på vegne av en kunde, se leverandør-integrasjoner.
For mer informasjon om ConsentRequest-modellen, se våre anbefalinger rundt bruken av samtykkeforespørsler

Eksempel på forespørsel:

POST /api/consentRequests HTTP/1.1
Host: www.altinn.no
ApiKey: {ApiKey}
Accept: application/hal+json
Content-Type: application/hal+json
{
    "coveredBy": "910514458",               --Orgnr til datakonsument
    "offeredBy": "27042000537",             --Fnr/orgnr til den som gir samtykke
    "offeredByName": "NORDMANN",            --Etternavn/orgnavn til samme
    "validTo": "2019-09-30T10:30:00.000",   --Gyldighetsdato for samtykke 
    "redirectUrl": "https://www.altinn.no", --URL som bruker sendes til
    "requestResources": [                   --Tjenestene med eventuelle metadata
        {
            "ServiceCode": "4629",
            "ServiceEditionCode": 2,
            "Metadata": {
                "inntektsaar": "2016"
            }
        },
        {
            "ServiceCode": "4630",
            "ServiceEditionCode": 2,
            "Metadata": {
                "fraOgMed": "2017-06",
                "tilOgMed": "2017-08"
            }
        }
    ],
    "requestMessage": {     --Tidligere omtalt som DelegationContext
        "no-nb": "Ved å samtykke, gir du Skatteetaten rett til å utlevere...",
        "no-nn": "Ved å samtykka, gir du Skatteetaten rett til å utlevera...",
        "en": "By accepting the consent, you grant the Tax Authority the..."
    },
    "portalViewMode": "Hide",               --Om den skal synes i portalen¹
    
}
¹ portalViewMode bestemmer om en samtykkeforespørsel skal være synlig i portalen for sluttbruker eller ikke. Dette er funksjonalitet som vil komme i 21.3. Forespørsler som besvares via portal vil ikke medføre at sluttbrukeren blir sendt til endepunkt oppgitt i redirectUrl.

Eksempel på svar:

{
    "AuthorizationCode": "c44f284f-b43b-4355-925a-2add17439659",
    "CoveredBy": "910514458",
    "OfferedBy": "27042000537",
    "validTo": "2019-09-30T10:30:00.000",
    "redirectUrl": "https://www.altinn.no",
    "requestResources": [
        {
            "ServiceCode": "4629",
            "ServiceEditionCode": 2,
            "Metadata": {
                "inntektsaar": "2016"
            }
        },
        {
            "ServiceCode": "4630",
            "ServiceEditionCode": 2,
            "Metadata": {
                "fraOgMed": "2017-06",
                "tilOgMed": "2017-08"
            }
        }
    ],
    "requestMessage": {
        "no-nb": "Ved å samtykke, gir du Skatteetaten rett til å utlevere...",
        "no-nn": "Ved å samtykka, gir du Skatteetaten rett til å utlevera...",
        "en": "By accepting the consent, you grant the Tax Authority the..."
    },
    "portalViewMode": "Hide",    
    "_links": {
        "self": {
            "href": "https://altinn.no/api/consentRequest/c44f284f-b43b-4355-925a-2add17439659"
        },
        "gui": {
            "href": "https://altinn.no/ui/AccessConsent/request?id=c44f284f-b43b-4355-925a-2add17439659"
        }
    }
}

Sende brukeren til samtykkesiden med AuthorizationCode som input

Etter at en samtykkeforespørsel er registrert og man har fått tilbake en list med _links som inneholder gui-link.

Merk at det må oppgis Accept: application/hal+json som en header i requesten for at HAL-lenker som _links skal komme med i svaret.

Videre benytter man denne for å sende brukeren til samtykkesiden:

https://altinn.no/ui/AccessConsent/request?id=c44f284f-b43b-4355-925a-2add17439659

Det eksisterer også en valgfri parameter (languageCode) som kan benyttes for å laste samtykkesiden på et forhåndsbestemt språk (en, nb-NO, nn-NO):

https://altinn.no/ui/AccessConsent/request?id=c44f284f-b43b-4355-925a-2add17439659?languageCode=en

Dersom man ikke spesifiserer languageCode vil samtykkesiden bli lastet på det språket som brukeren har valgt i altinn. I eksempelet over vil samtykkesiden lastes på engelsk.

I seksjonen lengre nede ser man eksempel på hvordan samtykkesiden vil se ut for en sluttbruker.

Lenkebaserte samtykker (legacy)

Lenkebaserte samtykker anbefales ikke for nye integrasjoner. Les mer om lenkebaserte samtykker.

Eksempel på en samtykkeside

I figuren nedenfor kan man se sammenhengen mellom det som ligger i url/json og det som presenteres for sluttbrukeren på samtykkesiden. Denne siden vil kunne lastes både gjennom en GUID dersom det foreligger en forhåndsregistrert samtykkeforespørsel, og via URL-parameter som definert i seksjonen over.

Sammenheng mellom opplysninger i url/json og samtykkesiden

Sammenheng mellom opplysninger i url/json og samtykkesiden

Autorisasjonskode

Når sluttbruker har fått opp samtykkesiden og gitt samtykke vil han sendes tilbake til siden som er angitt i RedirectUrl.
I denne url vil det sendes med autorisasjonskode og status. Ved bruk av forhåndsregistrerte samtykkeforespørsler er dette samme autorisasjonskode som ble returnert ved opprettelse av forespørselen.

Eksempel på url hvor status er OK:

https://www.eksempel.no/?AuthorizationCode=0435d832-193b-4a13-a6d1-d172c18e18c7&Status=OK

Eksempel på url hvor sluttbruker har valgt å trykke på knappen for “Nei, jeg vil ikke gi samtykke”:

https://www.eksempel.no/?Status=Failed&ErrorMessage=User%2520did%2520not%2520give%2520consent&FailedAuthorizationCode=435d832-193b-4a13-a6d1-d172c18e18c7

Dersom samtykkesiden ble lastet ved hjelp av AuthorizationCode, vil autorisasjonskode være den samme som sluttbrukeren lastet samtykkesiden med.

Merk at FailedAuthorizationCode ikke blir sendt med ved bruk av lenke-baserte samtykkeforespørsler, kun forhåndsregistrerte forespørsler. Fra 20.12 vil det i tillegg bli sendt med en feilkode her, som indikerer hva som gikk galt hos brukeren.