diff --git a/_docs/idporten/oidc/ansattporten_guide.md b/_docs/idporten/oidc/ansattporten_guide.md index fb477ae8..71daa49c 100644 --- a/_docs/idporten/oidc/ansattporten_guide.md +++ b/_docs/idporten/oidc/ansattporten_guide.md @@ -21,7 +21,13 @@ Ansattporten er p.t. i en pilot-status med redusert SLA, og det er foreløpig ik ## Overordna beskrivelse av støtta brukerreiser -Ansattporten tilbyr per nå to brukerreiser: +Ansattporten tilbyr per nå tre brukerreiser: + +* Innlogging med isolert SSO +* Innlogging på vegne av virksomhet +* Datadeling på vegne av virksomhet + +Disse er beskrevet i detalj nedenfor: ### Brukerreise 1: Innlogging med isolert SSO @@ -56,7 +62,7 @@ Denne SSO-oppførselen er realisert vha funksjonaliteten [isolert SSO-sesjon](oi Dette betyr også at kunder må støtte utlogging både fra egen tjeneste, men også håndtere utloggingsforespørsler (front_channel_logout) fra Ansattporten initiert av en annen tjeneste. -### Brukerreise 2: Innlogging på vegne av andre +### Brukerreise 2: Innlogging på vegne av virksomhet Ansattporten tilbyr *beriket* autentisering, altså at informasjon om innlogget bruker blir beriket med et representasjonsforhold/autorisasjonsinformasjon fra en ekstern autorativ kilde. I første versjon av løsningen er det Altinn Autorisasjon som tilbys som autorativ kilde. @@ -68,8 +74,8 @@ Brukerreise blir da som følger: 1. Bruker klikker login-knapp hos tjeneste. Kallet til ansattporten inneholder informasjon om hvilket representasjonsforhold som tjenesten trenger 2. Bruker autentiserer seg med sterk eID. Det opprettes en isolert SSO-sesjon i Ansattporten. -3. Dersom bruker har en eller flere representasjonsforhold av den forespurte typen, vil Ansattporten vise en organisasjonsvelger, der hen kan velge hvilken avgiver (organisasjon) som denne innloggingen skal være på vegne av -4. Bruker blir sendt tilbake til tjenesten, med informasjon om valgt avgiver +3. Dersom bruker har en eller flere representasjonsforhold av de forespurte typene, vil Ansattporten vise en organisasjonsvelger, der hen kan velge hvilken organisasjon (avgiver) som denne innloggingen skal være på vegne av +4. Bruker blir sendt tilbake til tjenesten, med informasjon om valgt organisasjon i id_tokenet Dette er detaljert i sekvensdiagrammet under: @@ -83,13 +89,13 @@ participant A as Ansattporten participant AA as Altinn Autorisasjon B->>C: Klikker "login" på tjeneste -C->>A: /authorize inkl forespurt representasjonstype (redirect) +C->>A: /authorize inkl forespurte representasjonstyper (redirect) note over B, A: sluttbruker autentiserer seg A->>AA: hente avgivere for bruker for ønska representasjon A->>A: vise organisasjonsvelger note over B, A: Bruker velger en organisasjon A->>C: redirect med code -C->>A: /token +C->>A: /token (id_token) note over B,C: innlogget i tjenesten @@ -97,6 +103,39 @@ note over B,C: innlogget i tjenesten **endring Q1-2024:** Dersom brukeren mangler det forespurte representasjonsforholdet, så vil brukeren likevel bli logga inn, men det vil ikke inkluderes noen representasjons-informasjon. +### Brukerreise 3: datadeling på vegne av virksomhet + +Denne brukerreisen er nært beslektet med #2, men med et ekstra steg: Tjenesten som brukeren har logget inn til, vil i tilegg utveksle data på vegne av valgt organisasjon mot et API hos en 3dje-part. + +
+sequenceDiagram + +participant B as Bruker +participant C as Tjeneste +participant A as Ansattporten +participant AA as Altinn Autorisasjon +participant D as API + +B->>C: Klikker "login" på tjeneste +C->>A: /authorize inkl forespurte representasjonstyper (redirect) +note over B, A: sluttbruker autentiserer seg + A->>AA: hente avgivere for bruker for ønska representasjon + A->>A: vise organisasjonsvelger + note over B, A: Bruker velger en organisasjon +A->>C: redirect med code +C->>A: /token +note over B,C: innlogget i tjenesten +C->>D: API-kall (access_token) +D->>C: data + +
+ +API-tilbydere bør merke seg at den organisasjonen som brukeren velger i organisasjonsvelgeren ikke trenger å samsvare med den organisasjonen som eier tjenesten. + +> Eksempel: Ola logger inn på vegne av Oslo Kommune til en tjeneste fra Visma som konsumerer et API hos Skatteetaten. + + +Teknisk sett benytter tjenesten (oauth2-klienten) Ansattporten sine access_token for å få denne API-tilgangen. ## Metadata @@ -115,9 +154,9 @@ Man kan teste løsningen uten å lage en integrasjon ved å bruke vår demo-tjen Vi anbefaler å bruke [Tenor testdata-søk](https://www.skatteetaten.no/skjema/testdata/) til å finne test-brukere. Tenor har mulighet til å filtrere slik at man får bare **daglig leder** fra test-Enhetsregisteret. En annen fordel med Tenor er at det kun er syntetiske testdata her, så man slipper å risikere å blande produksjons- og test-data. -> Ved å bruke **TestID** som innloggingsmetode slipper man å kontakte Digdir for å få opprettet og resatt testbrukere. +> Ved å bruke **TestID** som innloggingsmetode slipper man å kontakte Digdir for å få opprettet og resatt testbrukere. TestID har også integrasjon mot Tenor, så du kan hente tilfeldige test-personer derifra. -**MERK:** Dersom testbrukeren ikke finnes i Altinn sitt testmiljø (typisk for syntetiske fødselsnummer), vil ikke organisasjonsvelger fungere. Dette løses enkelt ved å logge inn i TT02 en gang. +**MERK:** Dersom testbrukeren ikke finnes fra før i Altinn sitt testmiljø (typisk for syntetiske fødselsnummer), vil ikke organisasjonsvelger fungere. Dette løses enkelt ved å logge inn i TT02 en gang. ## Representasjonsforhold og RAR @@ -128,9 +167,9 @@ Følgende `authorization_type` er støttet i Ansattporten: | `authorization_type` | Skildring | |-|-| -|ansattporten:altinn:service| Bruker tjenestekoder (ServiceCode) fra Altinn Autorisasjon som autorativ kilde for representasjonsforhold | - +|ansattporten:altinn:service| Bruker lenketjenester (ServiceCode) fra Altinn 2 som autorativ kilde for representasjonsforhold | +Det er mulig å be om flere representasjonsforhold i samme påloggingsforespørsel. Da vil organisasjonsvelger vise unionen av alle organisasjoner som brukeren har ett eller flere av de forespurte representasjonsforholdene for. Tokenet vil innehold en liste med de faktiske representasjonsforholdene brukere har for valgt(e) organisasjon(er). #### Datamodell for `ansattporten:altinn:service` @@ -152,7 +191,7 @@ der `resource` må følgje desse reglane: De konkrete ressurs-definisjonene kan finnes på [metadata-endepunktet til Altinn](https://tt02.altinn.no/api/metadata). -> **Mange av dagens standard Altinn-roller gir veldig breie tilganger ("Post/arkiv", "Utfyller/innsender").** Dette er problematisert med at de ikke følger gode dataminimeringsprinsipp, og vanskeliggjør det å skulle holde oversikt over hva en gitt rolle faktisk gir tilgang til. Derfor er ikke rolle tilbudt som mulig ressurs i Ansattporten i første runde. Vi vurderer dette løpende, inkludert å innføre støtte for nøkkelroller fra Enhetsregisteret. +> **Mange av dagens standard Altinn-roller gir veldig breie tilganger ("Post/arkiv", "Utfyller/innsender").** Dette er problematisert med at de ikke følger gode dataminimeringsprinsipp, og vanskeliggjør det å skulle holde oversikt over hva en gitt rolle faktisk gir tilgang til. Derfor er ikke rolle tilbudt som mulig ressurs i Ansattporten i første runde. ##### Respons @@ -162,14 +201,17 @@ Datamodellen for respons er lik datamodellen for request, men i tillegg vil det | claim | beskrivelse | |-|-|-| -| reportees | Array med valgte virksomheter. |Rights | Array med rettigheter som innlogget bruker har for aktuell tjenestekode. | -|Name| namnet på valgt organisasjon| +| reportees | Array med valgte virksomheter. | +| Rights | Array med rettigheter som innlogget bruker har for aktuell tjenestekode. | +| Name | Namnet på valgt organisasjon| +Dersom det er forespurt flere representasjonsforhold, så vil responsen være en liste, med ett respons-objekt per lenketjeneste som brukeren har rettighet til. ## Protokoll-flyt +Ansattporten følger en helt normal autorisasjons-kodeflyt ihht Oauth2/OIDC. ### 1: Autentiseringsforespørsel til autorisasjons-endepunktet @@ -179,10 +221,9 @@ Se [detaljert dokumentasjon for autorisasjonsendepunktet](oidc_protocol_authoriz Klienten må være forhåndsregistrert i Ansattporten, se [klient-registrering](oidc_func_clientreg.html). - For tjenester med høye krav til sikkerhet bør en i tillegg vurdere å bruke [PAR](oidc_protocol_par.html) til å først POSTe autentiseringsparametrene direkte til ID-porten før en redirecter, slik at disse parametrene ikke blir eksponert i brukers browser. -Dersom klienten ønsker å vise organisasjonsvelger, må forespørselen inkludere et RAR-element som ytterligere detaljerer forespørselen. På sikt vil det lages støtte for å etterspørre flere autorisasjonstyper i samme forespørsel. +Dersom klienten ønsker å vise organisasjonsvelger, må forespørselen inkludere et eller flere RAR-objekter som ytterligere detaljerer forespørselen. Eksempel på request: ``` @@ -202,26 +243,15 @@ https://login.test.ansattporten.no/authorize? "ressurs": "urn:altinn:resource:3906:141205", "allow_multiple_organizations": "true", "organizationform": "business" + }, + { + // eventuelt flere representasjonsforhold } ] ``` (merk at eksempelet er vist i klartekst for lesbarhet og ikke riktig enkoda) -#### Litt mer om RAR - -RAR er en ny Oauth2-utvidelse for transaksjonsspesifikke autorisasjoner. Der "basic" Oauth2 kun gir tilgang til et såkalt "scope" (tekst-streng), åpner RAR for tilgang til mer utvidede datamodeller i form av **autorisasjonstyper**. Autorisasjonstypen(e) blir utlevert i token som et nytt hierarkisk claim kalla `authorization_details` som igjen er ein array av autorisasjonsobjekter, der hvert objekt består av: -- standardiserte felt: - - type (påkrevd felt, definerer den aktuelle autorisasjonstypen) - - action - - locations (tiltenkt mottakar, aka =audience for tokenet) - - identifier (kan peike på ein konkret ressurs hjå APIet) - - datatypes (ein array med datatyper klient ønsker å få frå APIet) -- eigendefinerte felt, - - til ein gitt `type` vil det normalt vere definert og dokumentert ein tilhøyrande gyldig datamodell - - - ### 2: Redirect tilbake til tjenesten @@ -229,6 +259,7 @@ Etter at brukeren har logget inn vil det sendes en redirect tilbake til klienten Redirecten vil også inneholde `state`. Klienten MÅ validere at mottatt state-verdi stemmer med det den sendte i forespørsel, for å detektere replay attacks. Klienten MÅ også validere at `iss` stemmer med forventa utsteder. +Merk at Ansattporten vil redirecte tilbake selv om brukeren ikke hadde noe representasjonsforhold (evt. valgt selv å ikke representere noen organisasjon for akkurat denne innlogginga.) Eksempel på respons: @@ -250,7 +281,7 @@ Token-endepunktet brukes for utstedelse av tokens. Bruk av endepunktet varierer litt med hvilken klient-autentiseringsmetode som benyttes. Følgende autentiseringsmetoder fra [OIDC kap. 9](http://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) støttes: * **client_secret_basic** / **client_secret_post** - Klientautentisering basert på client_secret -* **private_key_jwt** - Klientautentisering basert på JWT'er signert med virksomhetssertifikater +* **private_key_jwt** - Klientautentisering basert på JWT'er signert med virksomhetssertifikater eller forhåndsregistrerte nøkkel-par. Sistnevnte metode er anbefalt for klienter med høye krav til sikkerhet. @@ -292,7 +323,7 @@ Dersom forespørselen blir validert som gyldig, vil det returneres et eller fler #### id_token -id_tokenet inneholder identiteten til den autentiserte brukeren - det forteller det hvem brukeren er, men ikke hvilke tilganger brukeren har. +id_tokenet inneholder identiteten til den autentiserte brukeren - det forteller det hvem brukeren er og hvilken organisasjon hen har valgt å representere. Normal bruker tjenesten id_tokenet kun til å opprette en egen, lokal sesjon. id_tokenet har derfor en ganske kort gyldighetsperiode. @@ -345,7 +376,7 @@ I utgangspunktet er id_token frå Ansattporten identiske som [id_token fra ID-po #### access_token -Access_tokenet (tilgangstoken) gir klienten [tilgang til APIer hos tredjepart](oidc_auth_oauth2.html) på vegne av den autentiserte brukeren. +Access_tokenet (tilgangstoken) gir klienten [tilgang til APIer hos tredjepart](oidc_auth_oauth2.html) på vegne av kombinasjonen av autentiserte brukeren og valgt organisasjon(er). Levetiden på aksess_tokenet er som oftest relativt kort (typisk 120 sekunder). Dersom tokenet er utløpt, kan klienten forespørre nytt acess_token ved å bruke refresh_tokenet. Det gjennomføres da en klient-autentisering, for å sikre at tokens ikke blir utlevert til feil part. @@ -353,6 +384,7 @@ Levetider kan også tilpasses per klient. Men merk at dette kan overstyres alt e Ansattporten sine access_token er svært like [ID-porten sine access token](oidc_protocol_access_token.html), men med samme unntakene som i avsnittet over. +API-tilbydere bør merke seg at sluttbruker kan velge en annen organisasjon enn den som har @@ -360,3 +392,19 @@ Ansattporten sine access_token er svært like [ID-porten sine access token](oidc Ansattporten tilbyr ikke et /userinfo-endepunkt. Siden Ansattporten er basert på [isolerte SSO-sesjoner](oidc_func_nosso.html), så må tjenesten kunne håndtere utlogging på samme måten som ID-porten. Dvs. både tilby brukeren å kunne logge ut, samt å måtte håndtere utloggingsforsepørsler initiert fra andre tjenester i Ansattporten. + + + + +### Litt mer om RAR + +RAR er en ny Oauth2-utvidelse for transaksjonsspesifikke autorisasjoner. Der "basic" Oauth2 kun gir tilgang til et såkalt "scope" (tekst-streng), åpner RAR for tilgang til mer utvidede datamodeller i form av **autorisasjonstyper**. Autorisasjonstypen(e) blir utlevert i token som et nytt hierarkisk claim kalla `authorization_details` som igjen er ein array av autorisasjonsobjekter, der hvert objekt består av: +- standardiserte felt: + - type (påkrevd felt, definerer den aktuelle autorisasjonstypen) + - action + - locations (tiltenkt mottakar, aka =audience for tokenet) + - identifier (kan peike på ein konkret ressurs hjå APIet) + - datatypes (ein array med datatyper klient ønsker å få frå APIet) +- eigendefinerte felt, + - til ein gitt `type` vil det normalt vere definert og dokumentert ein tilhøyrande gyldig datamodell +