Skip to content

Commit

Permalink
Merge branch 'gh-pages' into gh-pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@joergenb
joergenb authored Feb 22, 2022
2 parents 6de6de0 + 0afbdb3 commit ac5abef
Showing 1 changed file with 76 additions and 105 deletions.
181 changes: 76 additions & 105 deletions _docs/idporten/oidc/ansattporten_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ Ansattporten er en egen innloggingtjeneste med funksjonalitet som skiller seg no
Nøkkelfunksjonalitet er:
- Er egen Oauth2 issuer
- Har ikke Single-Signon (SSO) mellom tjenester
- Valgfri *organisasjonsvelger* som lar sluttbruker bestemme representasjonsforhold (kommer 1 kvartal '22)
- Valgfri *organisasjonsvelger* som lar sluttbruker bestemme representasjonsforhold
- Integrasjoner må opprettes med `integration_type=ansattporten` i selvbetjening


Ansattporten er p.t. i en pilot-status med redusert SLA, og det er foreløpig ikke besluttes om den skal bli en varig nasjonal fellesløsning. Ta kontakt om du har lyst å delta i piloten!
Ansattporten er p.t. i en pilot-status med redusert SLA, og det er foreløpig ikke besluttes om den skal bli en varig nasjonal fellesløsning. Det er fritt fram for alle å teste løsningen i test-miljø, men ta kontakt med oss først for å delta med produksjonstjenester i piloten!


## Overordna beskrivelse av støtta brukerreiser
Expand All @@ -28,7 +28,7 @@ Ansattporten tilbyr per nå to brukerreiser:
Dette er den enkleste brukerreisen. I dette scenariet utfører brukeren en engangs punktautentisering til en tjeneste.

1. Bruker klikker login-knapp hos tjeneste.
2. Bruker autentiserer seg med sterk eID gjennom Ansattporten. Det opprettes ikke en SSO-sesjon.
2. Bruker autentiserer seg med eID gjennom Ansattporten. Det opprettes ikke en SSO-sesjon.
4. Bruker blir sendt tilbake til tjenesten.

Teknisk er dette løst som en helt standard [OpenID Connect code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth), som vist i sekvensdiagrammet nedenfor:
Expand All @@ -53,13 +53,13 @@ Ulikt ID-porten så vil ikke brukeren få opprettet en SSO-sesjon i Ansattporten



### Brukerreise 2: Innlogging på vegne av andre (1. kvartal 2022)
### Brukerreise 2: Innlogging på vegne av andre

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.

En tjeneste aktiverer støtte for beriket autentering ved å inkludere informasjon om påkrevd representasjonsforhold (="avgiver") i autentiseringforespørselen. Ansattporten vil da vise en organisasjonsvelger etter autentisering, der sluttbruker må velge hvilke(n) organisasjon hen vil representere:
En tjeneste aktiverer støtte for beriket autentisering ved å inkludere informasjon om påkrevd representasjonsforhold (="avgiver") i autentiseringforespørselen. Ansattporten vil da vise en organisasjonsvelger etter autentisering, der sluttbruker må velge hvilke(n) organisasjon hen vil representere:

![organsisasjonsvelger]({{site.baseurl}}/images/idporten/oidc/ansattporten_orgvelger.png)
![organsisasjonsvelger](images/idporten/oidc/ansattporten_orgvelger.png)

Brukerreise blir da som følger:

Expand Down Expand Up @@ -105,6 +105,49 @@ Følgende miljøer er tilgjengelige for kunder:



## Test

Man kan teste løsningen uten å lage en integrasjon ved å bruke vår demo-tjeneste [https://test-client.test.ansattporten.no/](https://test-client.test.ansattporten.no/). Her kan man også studere protokoll-flyten i detalj.

Vi anbefaler å bruke [Tenor testdata-søk](https://www.skatteetaten.no/skjema/testdata/) til å finne test-brukere. Ved å bruke **TestID** som innloggingsmetode slipper man å kontakte Digdir for å få opprettet og resatt testbrukere. En annen fordel med Tenor er at det kun er syntetiske testdata her, så man slipper å risikere å blande produksjons- og test-data.




## Representasjonsforhold og RAR

Ansattporten bruker [Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar) til å strukturere informasjon om representasjonsforhold, både i forespørsler og tokens. Dette er nærmere forklart under *protokollflyt* nedenfor.

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 |



#### Datamodell for `ansattporten:altinn:service`

I første omgang er datamodellen ganske enkel, det er gjort tanker om potensielle forbedringer på sikt [her](https://github.com/joergenb/oauth/edit/main/ansattporten_rar.md).

Datamodell:

| claim | beskrivelse |
|-|-|
|resource | Hvilken ressurs i Altinn som etterspørres. Se kodeverk nedenfor. |


der `resource` må følgje desse reglane:

|Ressurs-identifikator| Beskrivelse|Eksempel|
|-|-|-|
|urn:altinn:resource:{tjenestekode}:{tjenesteutgave} | Altinn 2 [tenestekode/utgåve](https://www.altinn.no/api/metadata?language=1044) | altinn:resource:3906:141205

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.




Expand All @@ -116,14 +159,14 @@ Følgende miljøer er tilgjengelige for kunder:

Klienten sender en autentiseringsforespørsel ved å redirecte sluttbrukeren til autorisasjonsendepunktet.

Se [detaljert dokumentasjon for autorisasjonsendepunktet]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_authorize) for valgmuligheter. Merk at i Ansattporten følger vi Oauth2.1, slik at bruk av PKCE, state og nonce er påkrevd for alle klienter.
Se [detaljert dokumentasjon for autorisasjonsendepunktet](oidc_protocol_authorize.html) for valgmuligheter. Merk at i Ansattporten følger vi Oauth2.1, slik at bruk av PKCE, state og nonce er påkrevd for alle klienter.

Klienten må være forhåndsregistrert i Ansattporten, se [klient-registrering]({{site.baseurl}}/docs/idporten/oidc/oidc_func_clientreg).
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]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_par) til å først POSTe autentiseringsparametrene direkte til ID-porten før en redirecter, slik at disse parametrene ikke blir eksponert i brukers browser.
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, se detaljer lenger nedenfor.
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.

Eksempel på request:
```
Expand All @@ -139,13 +182,27 @@ https://login.test.ansattporten.no/authorize?
code_challenge=YhKJpC67w6qB2KupfDuKocVarvxL8vb9WSmSB6-p-Zc&
authorization_details= [
{
"type": "ansattporten:altinnressurs",
"ressurs": "urn:altinn:resource:skd:sirius"
"type": "ansattporten:altinn:service",
"ressurs": "urn:altinn:resource:3906:141205"
}
```
(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

Expand Down Expand Up @@ -191,7 +248,7 @@ redirect_uri=https://test-client.test.ansattporten.no/callback&
code_verifier=oQEG5SwL-dQlUL2ZkteJV8v0Fxz9z6j4Y1Q_86gEq78
```

Se [detaljert dokumentasjon for token-endepunktet]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_token) for alle valgmuligheter.
Se [detaljert dokumentasjon for token-endepunktet](oidc_protocol_token.html) for alle valgmuligheter.

Dersom forespørselen blir validert som gyldig, vil det returneres et eller flere token:

Expand Down Expand Up @@ -238,7 +295,7 @@ Eksempel:
"jti" : "bWAcJLMpJfs"
"authorization_details": [
{
"type": "ansattporten:altinnressurs",
"type": "ansattporten:altinn:service",
"ressurs": "urn:altinn:resource:3906:141205"
"ressurs_name": "A01 a-melding",
"avgiver": [{
Expand All @@ -253,25 +310,25 @@ Eksempel:

**Korrekt validering av id_token** av klienten er kritisk for sikkerheten i løsningen. Tjenesteleverandører som tar i bruk tjenesten må utføre validering i henhold til kapittel [3.1.3.7 - ID Token Validation i OpenID Connect Core 1.0 spesifikasjonen](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation).

I utgangspunktet er id_token frå Ansattporten like med [id_token fra ID-porten]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_id_token), men det kan være verdt å merke seg følgende forskjeller:
I utgangspunktet er id_token frå Ansattporten identiske som [id_token fra ID-porten](oidc_protocol_id_token.html), men det kan være verdt å merke seg følgende forskjeller:

|claim|beskrivelse
|-|-|
|acr| Ansattporten bruker de nye verdiene: `substantial` og `high`|
|authorization_details| Informasjon om representasjonsforhold. Se detaljer nedenfor|
|authorization_details| Informasjon om representasjonsforhold. Se detaljer ovenfor.|




#### access_token

Access_tokenet (tilgangstoken) gir klienten [tilgang til APIer hos tredjepart]({{site.baseurl}}/docs/idporten/oidc/oidc_auth_oauth2) på vegne av den autentiserte brukeren.
Access_tokenet (tilgangstoken) gir klienten [tilgang til APIer hos tredjepart](oidc_auth_oauth2.html) på vegne av den autentiserte brukeren.

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]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_scope) som er i tokenet.
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]({{site.baseurl}}/docs/idporten/oidc/oidc_protocol_access_token), men med samme unntakene som i avsnittet over.
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.



Expand All @@ -281,89 +338,3 @@ Ansattporten tilbyr ikke et /userinfo-endepunkt.

Siden Ansattporten ikke tilbyr SSO, er det heller ikke behov for å logge brukeren ut, eller måtte håndtere utloggingsforsepørsler initiert fra andre tjenester i circle-of-trust.


## Representasjonsforhold og RAR

Ansattporten bruker [Rich Authorization Requests (RAR)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar) til å strukturere informasjon om representasjonsforhold, både i forespørsler og tokens.

RAR er ein ny Oauth2-utvidelse for transaksjonsspesifikke autorisasjonar. Der "basic" Oauth2 kun gir tilgang til eit såkalt "scope" (tekst-streng), opnar RAR for tilgang til meir utvida datamodeller i form av **autorisasjonstyper**. Autorisasjonstypen(e) blir utlevert i token som eit nytt hierarkisk claim kalla `authorization_details` som igjen er ein array av autorisasjonsobjekter, der kvart objekt består av:
- standardiserte felt:
- type (påkrevd felt, definerer den aktuelle autorisasjonstypen)
- action
- locations (tiltenkt mottakar =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


#### Etterspørre en autorisasjon

```
authorization_details= [
{
"type": "ansattporten:altinnressurs",
"ressurs": "urn:altinn:resource:skd:sirius"
}
```

På sikt vil det lages støtte for å etterspørre flere autorisasjonstyper i samme forespørsel.

#### Respons i token

Dersom den innlogga brukeren har valgt en organisasjon, vil token inneholde `authorization_details` slik:

```
"sub": "WE0DjFv9ygb2rjS7s_tXsg-fez2Co3Q8oxUmcvQ0mzQ=",
"iss": "https://ansattporten.no/",
"pid": "<fødselsnummer til sluttbruker>",
...
"authorization_details": [
{
"type": "ansattporten:altinnressurs",
"ressurs": "urn:altinn:resource:3906:141205"
"ressurs_name": "A01 a-melding",
"avgiver": [{
"Authority": "iso6523-actorid-upis",
"ID": "0192:999888777" // org.no til arbeidsgiveren som den innlogga brukeren har valgt i org.velger
}]
}
]
```




### Støtta representasjonsforhold i Ansattporten

Følgende `authorization_type` er støttet i Ansattporten:

| `authorization_type` | Skildring |
|-|-|
|ansattporten:altinnressurs| Bruker Altinn Autorisasjon som autorativ kilde for representasjonsforhold |



#### 1: Altinn Autorisasjon

I første omgang er datamodellen ganske enkel, det er gjort tanker om potensielle forbedringer på sikt [her](https://github.com/joergenb/oauth/edit/main/ansattporten_rar.md).



Datamodell:

| claim | beskrivelse |
|-|-|
|ressurs | Hvilken ressurs i Altinn som etterspørres. Se kodeverk nedenfor. |


der `ressurs` må følgje desse reglane:

|Ressurs-identifikator| Beskrivelse|Eksempel|
|-|-|-|
|urn:altinn:resource:{tjenestekode}:{tjenesteutgave} | Altinn 2 [tenestekode/utgåve](https://www.altinn.no/api/metadata?language=1044) | altinn:resource:3906:141205
|urn:altinn:resource:{org}:{appname} | Altinn 3 [org/app](https://www.altinn.no/api/metadata?language=1044) | altinn:resource:skd:sirius

De konkrete ressurs-definisjonene kan finnes på metadata-endepunktet til Altinn.

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

0 comments on commit ac5abef

Please sign in to comment.