Dato | Hva ble endret? |
---|---|
2021.08.26 | Lagt til hvordan man bestiller Skatteetaten scopes. |
2021.08.26 | Lagt til seksjon for mange redirect-uri's Gyldig(e) redirect uri-er. |
For å autentisere med ID-porten må man implementere en Open ID Connect løsning mot ID-Porten. Det kan være utfordrende å implementere og sees på som det minst trivielle å løse med hensyn på innsending av mva-melding.
Det aller viktigste først: Skatteetaten har ressurser som kan hjelpe deg å forstå og finne en god løsning for din applikasjon.
Denne siden inneholder informasjon om hva som må gjøres, og hva som er spesifikt for Skatteetaten i en Open ID Connect-løsning.
Grovt sett er det følgende som må gjøres:
Det er utenfor denne dokumentasjonen å beskrive Open ID Connect og OAuth2, men de detaljene som er spesifikke for Integrasjonen og Skatteetaten blir beskrevet i det følgende.
Det anbefales å komme igang med ID-porten så tidlig som mulig da den antakeligvis vil ta kalendertid. For å komme i gang må man gå gjennom en prosessen hos Digitaliseringsdirektoratet (DigDir), og i den prosessen vil få tilgang til å opprette Integrasjoner i Samarbeidsportalen. For å sende inn mva-meldinger må man ha en Integrasjon som er konfigurert riktig for din applikasjon og for API'ene Integrasjonen skal brukes mot.
Hvordan man kommer i gang med ID-porten er beskrevet her: ID-Porten.
En annen fordel med å starte prosessen tidlig er at man kan teste Integrasjonen i test-miljøet som inkluderer både Altinn3 og Skatteetaten. Det må også opprettes egen integrasjon for produksjon.
Skatteetatens Integrasjon med Indentifikator client_id: 23cc2587-ea4e-4a5f-aa5c-dfce3d6c5f09
kan benyttes til ID-Porten er klar til å tas i bruk. Denne vil bli fjernet etter varsel. Se mer i avsnittet under
Når tilgangen til Samarbeidsportalen er beskaffet, kan det opprettes en Integrasjon som vil kunne benyttes av sluttbrukersystemet.
Man åpner https://minside-samarbeid.digdir.no/
Og velger Integrasjoner under Ver 2 som vist under.
Da blir man tatt videre til Integrasjonene i Ver 2.
Og ved å klikke på Ny integrasjon kan man begynne å konfigurere Integrasjonen mot Skatteetaten.
I denne guiden vil det konfigureres en Digdir-tjeneste at typen API-klient, som vist over.
En gjennomgang av de forskjellige feltene i konfigurasjonen følger
Når man velger en verdi fra dette rullegardinet
så vil det kanskje skje noe med:
Dette er forvirrende, så det anbefales å lage flere, det er helt ufarlig og man kan slette dem man ikke vil ta i bruk.
Som nevnt brukes API-klient. Det vil lage en Open ID Connect klient som ikke har noen forututfylte scopes som ikke det er behov for.
For å bruke validerings og innsendings-api'ene må følgende scopes legges til:
For å legge dem til bruk knappen "Legg til scopes".
Dersom skatteeten-scopene ikke finnes i søket er det fordi Skatteetaten ikke har gitt din organisasjon tilgang til disse scopene ennå. Din organisasjon kan nå bestille tilgang til scopene ved å følge prosedyren under.
Scopene må bestilles av din organisasjon ved å kontakte Skatteetaten via Skriv til oss - Skatteetaten og oppgi organisasjonsnummer for organisasjonen som administrerer integrasjonen.
Skatteetaten vil gi tilgang til scopene og de kan deretter legges til i integrasjonen. Scopene må også legges til i koden som integrerer med ID-Porten slik at scopene inkluderes i aksess-tokenet til ID-Porten.
Eksempelkoden hent_idporten_token.py
er oppdatert til å reflektere endringene som behøves i ID-Porten-integrasjonen når scopene er lagt til i integrasjonen i selvbetjeningsportalen.
Dette skal være organisasjonsnummeret til organisasjonen din.
Når integrasjonen blir opprettet dukker det opp en Guid her. Det er dette som er client_id
Valgfrie tekster. Navnet på integrasjonen vil vises i listen over integrasjonene, så det er fornuftig å gi dem fornuftige navn.
Her må det velges:
Her kan det velges:
I tilfeller hvor det ikke er helt sikkert at tokens eller hemmeligheter er beskyttet fra røvere, anbefales ikke bruken. Refresh-tokens kan derfor ikke brukes i for eksempel en SPA, hvor nettleseren ikke helt sikkert kan beskytte hemmeligheter eller tokens over lang tid. Det anbefales derfor å ikke bruke refresh_tokens
i JS/SPA-applikasjoner eller i frittstående applikasjoner som installeres på sluttbrukerens personlige datamaskin. ID-porten har derfor begrensninger på refresh_token
bruk utenfor web-applikasjoner, hvor tokens og hemmeligheter kan beskyttes på tjeneren.
Et refresh_token
kan ha veldig lang levetid og brukes til å utstede nye access_tokens
.
Bestemmer hvilken autentiseringsmetode integrasjonen bruker for å autentisere seg (ikke slutt-brukeren).
Velg none dersom det ikke brukes refresh_token
.
Det er i dette valget at omtalte refresh_token
vil kunne bli tilgjengelig dersom web velges.
Applikasjonstypen bestemmer om applikasjonen til integrasjonen er å anse som public eller private, som igjen bestemmer om man kan bruke refresh_tokens
.
public:
private:
Men dette betyr ikke at en web-applikasjon må være privat. Man kan trygt bruke browser for web-applikasjoner som ikke bruker refresh_tokens
.
Når autentiseringsprosessen starter skal brukeren føres fra applikasjonen til login-siden hos ID-Porten. Og når innloggingen er vellykket blir brukeren redirigert tilbake til applikasjonen.
Dette oppnås ved å inkludere redirect_uri
i parameterene som brukes for å åpne nettleservinduet hos ID-Porten. redirect_uri
som sendes som parameter MÅ være tilstede i listen over Gyldig(e) redirect uri-er i Integrasjonen.
Applikasjonen er avhengig av å ha et endepunkt som kan håndtere redirigeringen til redirect_uri
.
Dersom sluttbrukersystemet sin portefølje har veldig mange installasjoner som ikke deler domene kan de heller ikke dele redirect_uri
. Installasjonene kan være både on-premise eller i skyen. Siden det er et krav at hvert domene må ha sin egen redirect_uri
kan det bli utfordrende å administrere disse i selvbetjeningsportalen.
Digitaliseringsetaten har nylig publisert informasjon som kan være nyttig i dette tilfellet: https://docs.digdir.no/docs/idporten/oidc/oidc_api_admin Systemleverandøren vil være eieren av integrasjonen(e) knyttet til automatiske dynamiske løsninger.
Dersom løsningen ovenfor ikke kan brukes i systemporteføljen til systemleverandøren, er det også mulig å la sluttbrukersystemets kunder eie og administrere ID-porten integrasjonene. Hvis du velger en løsning der hver enkelt kunde administrerer og eier ID-porten-integrasjon, må systemleverandørene supportere kundenes integrasjoner. Skatteetaten supporterer bare henvendelser fra systemleverandører for deres integrasjoner, ikke henvendelser fra systemleverandørers kunder. Skatteetaten vil gi tilgang til de nødvendige scopene for de aktuelle organisasjonsnummerene i tilfeller der denne løsningen velges. Systemleverandører som ønsker å benytte denne alternative løsningen bør kontakte Skatteetaten med informasjon om hvor mange kunder som er involvert, før de starter med utviklingen av denne løsningen.
Liksom Gyldig(e) redirect uri-er, bortsett fra at denne redirigeringen vil intreffe dersom applikasjonen har bedt ID-porten å logge ut brukeren på samme måte som ved innlogging.
Dette er knyttet til single logout og utenfor denne guiden.
Dersom brukeren avbryter innloggingen i ID-Porten vil brukeren tas til denne adressen. Merk at dette bare er 1 uri.
Det er mulig å sette levetiden på
Kombinasjonen av disse vil bestemme hvor lang tid det går mellom hver gang brukeren må autentisere seg hos ID-Porten.
Levetiden vil bli begrenset av maksimal levetid for det tillagte scopet med kortest maksimal levetid. Skatteetatens scope vil ha maksimal levetid på 8 timer.
Det kan velges mellom
Gjenbrukbare refresh-tokens kan ikke benyttes igjen når levetiden utløper og brukeren må gjennomføre en ny autentisering for å få utstedt et nytt refresh token.
Under finnes en ferdig utfylt integrasjon. Denne kan benyttes av alle typer applikasjoner som kan lytte til http://localhost:8988
. Å lytte til localhost
vil for eksempel passe for systemer som er installert på sluttbrukeres personlige datamaskiner. Den vil også passe strålende under utvikling av applikasjonen som skal benytte en Integrasjon.
Det er verdt å merke seg at selv om det er mulig å ha flere redirect uri-er, så er det for eksempel kun mulig med én Tilbake-uri. Dette vil gjøre det vanskelig å dele Integrasjon mellom domener, applikasjonstyper og utvikling. Lag en ny så fort du ønsker å dele Integrasjonen.
ID-porten autentisering kan implementeres i alle typer sluttbrukersystemer
under forutsetning av at applikasjonen kan åpne en URL i en nettleser hvor login gjennomføres og samtidig lytte til requests.
Sluttbrukersystemet må gjøre følgende:
Vi benytter følgende testmiljø hos ID-porten:
For detaljer rundt hvilken HTTP parametere som må sendes med i kallene, se filen hent_idporten_token.py