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)
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)
Figuren viser en overordnet funksjonell skisse. Detaljert flytdiagram vises etterpå.
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.
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.
Dette er:
Disse må være med og være fyllt ut i overensstemmelse med det nevnt over.
Ved korrekt validering gjøres det et kall mot token-tjenesten hvor accesstoken, client_id, redirect_uri, state, nonce sendes med.
Nonce og redirect_uri bl.a lagres så i Helsenorge sikkerhetstjeneste og autentiseringskode genereres og returneres.
Det gjøres så en redirect tilbake til bruke med følgende verdier:
Ved generering av token gjør bruker en "post-request" hvor følgende autentiseringsmetoder foreløpig støttes:
Følgende header-parametere må brukes på request:
Parameter | Verdi |
---|---|
Http-metode | POST |
Content-type | application/x-www-form-urlencoded |
Authorization | Basic <ClientSecret> |
Samt at følgende attributter må sendes inn i requesten:
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 |
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).
POST /token client_id=FA5356DF-45EB-42F2-A906-7B4E88CD5266&grant_type=authorization_code& |
---|
Det gjøres så en validering av forespørselen hvor det bl.a. sjekkes på at grant_type = "authorization_code" og client_id/client_secret hentes ut av Authorization-header.
token-tjenesten kalles så med følgende verdier:
ID-token (signert JWT struktur i henhold til OpenID Connect spesifikasjonen) generes så og med følgende verdier:
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 |
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. |
Eks på ID-token:
{
"sub": "NGQ0ODI1OGMtMWIzNy00YmJiLTk5MWMtOTM5NjcxOGU4ZDNkMjAwMzk0MDk0NjI=",
"aud": "4d48258c-1b37-4bbb-991c-9396718e8d3d",
"acr": "Level4",
"auth_time": "1593072493",
"amr": "sikkerhet.helsenorge.no",
"iss": "http://tjenester.helsenorge.utvikling/helsenorge-oidc-provider/",
"pid": "20039409462",
"name": "Torill Dahl Jama",
"given_name": "Torill",
"family_name": "Jama",
"middle_name": "Dahl",
"pid_act": "20039409462",
"act_name": "Torill Dahl Jama",
"act_given_name": "Torill",
"act_family_name": "Jama",
"act_middle_name": "Dahl",
"pid_act_type": "segselv",
"nonce": "a2d13eea-542e-49aa-be81-16de8d095be0",
"exp": 1593079693,
"iat": 1593072508,
"jti": "529523dd-d0bb-4665-af7e-a91752128710",
"sid": "YCYBkD39dnGx1w0F4EpLYE4NyAlkkzcTAB6s7KxpIlJJrERujGbzunB8ABFRTznpBgw",
"nbf": 1593072508
}
Ved retur fra token-tjenesten sendes følgende i responsen til bruker:
Parameter | Verdi |
---|---|
id_token | ID-token nevnt over |
token_type | "Bearer" |
expires_in | Når tokenet utløper |
scope | "openid" |
Eksempel på respons fra token-endepunktet:
{"access_token":"","id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IkY0NkVDQjI5RjhCOTk5NEQyMjg2QjA3M0MxQ0VBNkE1MkJCNz "token_type":"BEARER","expires_in":7200,"scope":"openid"} |
---|
Validering av signatur på ID-token:
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:
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.
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:
https://eksternapi.helsenorge.no/sts/helsenorge-oidc-provider/v1/endsession?id_token_hint='eyJraWQiOiJpZ2I1Q3lGT...'&post_logout_redirect_uri='<min registrerte post-logout uri>'&state='fe93c125-4d69-4ee3-8ca5-299ac6e3e499' |
---|