Integrasjonsguide - Ansattporten

Ansattporten er en egen innloggingtjeneste med funksjonalitet som skiller seg noe fra ID-porten, slik at den skal være mer hensiktmessig å bruke i ansattkontekst eller i andre situasjoner der det er ønskelig å opptre i et representasjonsforhold på vegne av andre virksomheter eller personer.

Nøkkelfunksjonalitet er:

• Er egen Oauth2 issuer
• Har ikke Single-Signon (SSO) mellom tjenester
• 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. 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

Ansattporten tilbyr per nå to brukerreiser:

Brukerreise 1: Innlogging uten SSO

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 eID gjennom Ansattporten. Det opprettes ikke en SSO-sesjon.
3. Bruker blir sendt tilbake til tjenesten.

Teknisk er dette løst som en helt standard OpenID Connect code flow, som vist i sekvensdiagrammet nedenfor:

Ulikt ID-porten så vil ikke brukeren få opprettet en SSO-sesjon i Ansattporten. Dersom brukeren forsøker å logge på samme eller en annen tjeneste rett etterpå, med samme browser, så må brukeren autentisere seg på nytt.

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 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:

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 ikke SSO-sesjon i Ansattporten.
3. Bruker vises 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

Dette er detaljert i sekvensdiagrammet under:

Metadata

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://demo-client.test.ansattporten.no/. Her kan man også studere protokoll-flyten i detalj. Dersom man ønsker å teste organisasjonsvelger, så kan man bruke [{"type":"ansattporten:altinn:service","resource": "urn:altinn:resource:2480:40"}] i authorization_details-feltet (denne tjenestekoden gir ut nøkkelroller).

Vi anbefaler å bruke Tenor testdata-søk 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.

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.

Representasjonsforhold og RAR

Ansattporten bruker Rich Authorization Requests (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:

Datamodell for ansattporten:altinn:service

Datamodell for request:

der resource må følgje desse reglane:

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.

Respons

Datamodellen for respons er lik datamodellen for request, men i tillegg vil det utleveres:

Protokoll-flyt

1: Autentiseringsforespørsel til autorisasjons-endepunktet

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

Se detaljert dokumentasjon for autorisasjonsendepunktet 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.

For tjenester med høye krav til sikkerhet bør en i tillegg vurdere å bruke PAR 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.

Eksempel på request:

https://login.test.ansattporten.no/authorize?
  scope=openid&
  client_id=9a99e96d-b56c-4f74-a689-f936f71c8819&
  acr_values=low&
  response_type=code&
  redirect_uri=https%3A%2F%2Ftest-client.test.ansattporten.no%2Fcallback&
  state=Hocd3Rs77Jw1BYOFJ_PP87XPza-MdrC0M9MeL33cmqE&
  nonce=KUXk5WlVwgz-YYf0UkhLuquqaJSRr7BcmwwPC22IC1o&
  code_challenge_method=S256&
  code_challenge=YhKJpC67w6qB2KupfDuKocVarvxL8vb9WSmSB6-p-Zc&
  authorization_details= [
    {
      "type": "ansattporten:altinn:service",
      "ressurs": "urn:altinn:resource:3906:141205",
      "allow_multiple_organizations": "true",   
      "organizationform": "business"
    }
]

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

Eksempel på respons:

https://test-client.test.ansattporten.no/callback?
 code=ERnHqwptnS9t3nGyad09Jw.og36LcOit1CaoxHSASE4_w&
 iss=https%253A%252F%252Ftest.ansattporten.no&
 state=Hocd3Rs77Jw1BYOFJ_PP87XPza-MdrC0M9MeL33cmqE

3: Utstedelse av token fra token-endepunktet

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 støttes:

• client_secret_basic / client_secret_post - Klientautentisering basert på client_secret
• private_key_jwt - Klientautentisering basert på JWT’er signert med virksomhetssertifikater

Sistnevnte metode er anbefalt for klienter med høye krav til sikkerhet.

Eksempel på forespørsel:

POST https://test.ansattporten.no/token
Authorization: Basic ***
Content-Type: application/x-www-form-urlencoded; charset=UTF-8

code=ERnHqwptnS9t3nGyad09Jw.og36LcOit1CaoxHSASE4_w&
grant_type=authorization_code&
redirect_uri=https://test-client.test.ansattporten.no/callback&
code_verifier=oQEG5SwL-dQlUL2ZkteJV8v0Fxz9z6j4Y1Q_86gEq78

Se detaljert dokumentasjon for token-endepunktet for alle valgmuligheter.

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

• id_token: Autentiseringsbevis, “hvem brukeren er”
• access_token: Tilgangs-token, forteller “hva brukeren kan få tilgang til”
• refresh_token: Brukes av klienten til å fornye access_token uten brukerinteraksjon (så lenge som autorisasjonen er gyldig)

{
  "access_token" : "eyJ4NWMiOlsiTUlJRktqQ0NC....",
  "refresh_token" : "eyJlbmMiOiJBMTI4Q0JDLUhTMjU....",
  "scope" : "openid",
  "id_token" : "eyJ4NWMiOlsiTUlJRktqQ0NCQktnQXdJQkFnSUxBbGx....",
  "token_type" : "Bearer",
  "expires_in" : 600
}

id_token

id_tokenet inneholder identiteten til den autentiserte brukeren - det forteller det hvem brukeren er, men ikke hvilke tilganger brukeren har.

Normal bruker tjenesten id_tokenet kun til å opprette en egen, lokal sesjon. id_tokenet har derfor en ganske kort gyldighetsperiode.

Eksempel:

{
  "sub" : "z9RuQiLefXmJOBnywa_c75YQMH05nDsHjw0RFzuJC8M",
  "amr" : [ "TestID" ],
  "iss" : "https://test.ansattporten.no",
  "pid" : "45840375084",
  "locale" : "en",
  "nonce" : "h3DeaRXe4pVXEdYAwR4hxeOtG2DHwF_zIDvjAAWf-x0",
  "sid" : "-EuMkNN8AuLgMhbXgID7ewtpC4Kuw-HS1dXWi7zo8Dc",
  "aud" : "ansattporten_demo_client_prod",
  "acr" : "high",
  "authorization_details" : [ {
    "resource" : "urn:altinn:resource:2480:40",
    "type" : "ansattporten:altinn:service",
    "resource_name" : "Produkter og tjenester fra Brønnøysundregistrene",
    "reportees" : [ {
      "Rights" : [ "Read", "ArchiveDelete", "ArchiveRead" ],
      "Authority" : "iso6523-actorid-upis",
      "ID" : "0192:987464291",
      "Name" : "DIGITALISERINGSDIREKTORATET AVD LEIKANGER"
    } ]
  } ],
  "auth_time" : 1671033189,
  "name" : "NAMNET TIL SLUTTBRUKER",
  "exp" : 1671033331,
  "iat" : 1671033211,
  "jti" : "raWcGKMobFU"
}

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.

I utgangspunktet er id_token frå Ansattporten identiske som id_token fra ID-porten, men det kan være verdt å merke seg følgende forskjeller:

access_token

Access_tokenet (tilgangstoken) gir klienten tilgang til APIer hos tredjepart 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 som er i tokenet.

Ansattporten sine access_token er svært like ID-porten sine access token, men med samme unntakene som i avsnittet over.

4: userinfo og utlogging

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.