Endepunktet avvikles senest Mai 2022, og alle nye integrasjoner skal baseres på V3 av endepunktet: V3 - OpenID Connect /API-tilgang (IdToken og AccessToken)
(ref: Vilkår og betingelser for bruk av APIer)
...
Introduksjon
Versjon 1 av OpenID connect endepunktet til Helsenorge sikkerhetstjeneste støtter UseCase der innbygger allerede er innlogget på Helsenorge og ønsker sømløs overgang til et eksternt system uten ny innlogging. Det støttes kun overgang til eksterne systemer som er såkalt "Confidential clients", dvs. kan holde på en hemmelighet. Dermed støtter ikke endepunktet mobilapplikasjoner. Endepunktet støtter heller ikke at eksternt system får tilgang til API'er på Helsenorge.
Endepunktet avvikles og alle nye integrasjoner skal baseres på V3 av endepunktet: V3 - OpenID Connect /API-tilgang (IdToken og AccessToken)
OpenId Connect flyt
Figuren viser en overordnet funksjonell skisse. Detaljert flytdiagram vises etterpå.
...
| Gliffy | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Tekniske informasjon og endepunkter
Endepunkter
Metadata om Helsenorge OpenID provider er tilgjengelig på vårt .well-known-endepunkt ihht. OpenID Connect Discovery.
På endepunktet finnes lenke til vårt JWK-endepunkt der sikkerhetstjenestens signeringssertifikat publiseres.
...
For informasjon om URL i andre utvikling- og testmiljøer på Helsenorge henvises til avtale om miljø som skal benyttes i systemintegrasjonstest.
Autentisering av sluttbruker og initiell OpenID Connect flyt
For at eksternt system skal benytte tjenesten forutsettes det at brukeren allerede er innlogget på Helsenorge dvs. at det finnes et aksesstoken til Helsenorge lagret i vedkommendes browser-cookie. Hvis dette ikke er tilfelle sendes innbyggeren til ID-porten for ny pålogging. Er aksesstoken tilstede så gjøres det en validering av at parametre i query-stringen fra eksternt system er i overensstemmelse med OpenID Connect (OIC) standarden.
...
- code: Den genererte autentiseringskoden
- state: Initiell verdi sendt inn av bruker (se over)
Generering av token
Ved generering av token gjør bruker en "post-request" hvor følgende autentiseringsmetoder foreløpig støttes:
...
Attributt | Verdi |
|---|---|
| client_id | Klientens ID |
| grant_type | authorization_code |
| code | autorisasjonskode (code) motatt i autentiseringsresponsen |
| redirect_uri | ønsket redirect_uri, skal være identisk med verdi brukt i autentiseringsforespørsel |
Klientautentisering med statisk klienthemmelighet
Her benyttes tidligere utlevert statisk hemmelighet(client_secret) til autentisering ved å legge på en standard HTTP Basic autentiserings-header (base64-enkoda sammensatt streng av client_id, kolon og client_secret).
Eksempel på forespørsel
POST /token client_id=FA5356DF-45EB-42F2-A906-7B4E88CD5266&grant_type=authorization_code& |
|---|
...
ID-token (signert JWT struktur i henhold til OpenID Connect spesifikasjonen) generes så og med følgende verdier:
ID tokenets header:
claim | verdi |
|---|---|
alg | “algorithm” - signeringsalgoritme, Helsenorge støtter kun RS256 (RSA-SHA256) |
kid | “Key identifier” - unik identifikator for signeringsnøkkel brukt av provideren. Nøkkel og sertifikat hentes fra providerens JWK-endepunkt. |
| typ | JWT |
ID tokenets body:
claim | verdi |
|---|---|
| sub | “subject identifier” - unik identifikator for den aktuelle brukeren. Verdien er her pairwise - dvs en klient får alltid samme verdi for samme bruker. Men ulike klienter vil få ulik verdi for samme bruker. |
| aud | “audience” - client_id til klienten som er mottaker av dette tokenet. |
| acr | “Authentication Context Class Reference” - Angir sikkerhetsnivå for utført autentisering. Helsenorge støtter kun “Level4”. |
| auth_time | Tidspunktet for når autentiseringen ble utført. Dvs. tidspunktet når brukeren logget inn på Helsenorge. |
| amr | “Authentication Methods References” - Autentiseringsmetode; alltid "sikkerhet.helsenorge.no" |
| iss | Identifikator for provideren som har utstedt token’et. I prod: https://eksternapi.helsenorge.no/sts//helsenorge-oidc-provider/ |
| pid | Personidentifikator - Helsenorge spesifikt claim som gir den bruker innloggingen gjelder. Dette er enten innlogget bruker (dersom man er innlogget som seg selv) eller den man representerer dersom man er innlogget og representerer en annen. (Enten som foreldre eller ved fullmakt). |
| name | Fullt navn (hvis representert; ellers innlogget) |
| given_name | Fornavn (hvis representert; ellers innlogget) |
| family_name | Etternavn (hvis representert; ellers innlogget) |
| middle_name | Mellomnavn (hvis representert; ellers innlogget) |
| pid_act | Personidentifikator - Helsenorge spesifikt claim som alltid gir innlogget brukers fødselsnummer. |
| act_name | Fullt navn (innlogget) |
| act_given_name | Fornavn (innlogget) |
| act_family_name | Etternavn (innlogget) |
| act_middle_name | Mellomnavn (innlogget) |
| pid_act_type | Helsenorge spesifikt claim som gir type representasjon. Kan inneholde kun en av følgende verdier: Verdi Beskrivelse segselv Innbyggeren representerer seg selv fullmakt Innlogget bruker representerer en annen gjennom fullmakt vergemal Innlogget bruker representerer en annen gjennom Vergemål foreldrerepresentasjon Innlogget innbygger har foreldreansvar for barnet |
| nonce | Samme nonce som ble sendt inn av bruker i autentiseringsdelen nevnt over. |
| exp | Expire - Utløpstidspunktet for Id tokenet (UTC tid). Klienten skal ikke akseptere token’et etter dette tidspunktet. |
| iat | Tidspunkt for utstedelse av tokenet. |
| jti | jwt id - unik identifikator for det aktuelle Id tokenet. |
| sid | sesjonsid - en unik identifikator for brukerens sesjon med Helsenorge OIDC Provider. |
| nbf | Tokenet er ikke gyldig før dette tidspunkt. |
...
Openid-information endepunkt angitt over returnerer de forskjellige endepunkter definert i OpenId connect. Et av disse er endepunktet der sertifikatkjeden for signeringssertifikatet vårt kan hentes ut:
- Prod: https://eksternapi.helsenorge.no/sts/helsenorge-oidc-provider/v1/jwk
- Test: https://eksternapi.hn.test.nhn.no/sts/helsenorge-oidc-provider/v1/jwk
Versjon 1 over brukes av noen kunder, men støtter ikke fult ut OIDC spesifikasjonen. Det er derfor opprettet en v2 versjon hvor keys elementet er i rot.
NB! v2-versjon gjelder både well-known endepunktet (discover) og jwk.
Utlogging (SLO)
Når brukeren skal logges ut fra Helsenorge, må det sendes en redirect til endsession-endepunktet. Adressen til endepunktet er definert i konfigurasjonsendepunktet (well-known endepunkt).
Helsenorge sender en redirect til post_logout_redirect_uri, dersom denne er angitt og definert for klient, og id_token_hint er inkludert. Dersom disse mangler, vil brukeren ikke bli logget ut.
Attributt | Kardinalitet | Beskrivelse |
|---|---|---|
| id_token_hint | anbefalt | Settes lik mottatt id-token. Nødvendig for å kunne sende brukeren tilbake til tjenesteeiers post_logout_redirect_uri etter endt utlogging. |
| post_logout_redirect_uri | anbefalt | Må være forhåndsregistrert på klient som id_token er utstedt til. |
| state | valgfri | Verdi som klient kan bestemme selv. Helsenorge vil inkludere denne tilbake i redirecten tilbake til utloggings-urlen. |
Eksempel på utloggings-url:
...