Skip to content

Commit

Permalink
støtte for flere representasjonsforhold
Browse files Browse the repository at this point in the history
  • Loading branch information
@joergenb
joergenb committed Mar 9, 2024
1 parent 3562010 commit bdbff03
Showing 1 changed file with 80 additions and 32 deletions.
112 changes: 80 additions & 32 deletions _docs/idporten/oidc/ansattporten_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand All @@ -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:

Expand All @@ -83,20 +89,53 @@ 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

</div>


**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.

<div class="mermaid">
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

</div>

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

Expand All @@ -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
Expand All @@ -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`

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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:
```
Expand All @@ -202,33 +243,23 @@ 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

Etter at brukeren har logget inn vil det sendes en redirect tilbake til klienten til den forhåndsregistrerte `redirect_uri`. Redirecten vil vil inneholde et autorisasjonskode-parameter `code` som brukes til oppslag for å hente tokens. Koden er base64-enkoda og URL-safe.

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:

Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -345,18 +376,35 @@ 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.

Levetider kan også tilpasses per klient. Men merk at dette kan overstyres alt etter [hvilke oauth2 scopes](oidc_protocol_scope.html) som er i tokenet.

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



### 4: userinfo og utlogging
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

0 comments on commit bdbff03

Please sign in to comment.