V1 - Avviklet - OpenID Connect provider (IdToken)


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

  1. Innbygger er allerede pålogget Helsenorge
  2. Innbygger velger funksjon på Helsenorge som gir overgang/oppstart av eksternt system. Lenken som benyttes går til påloggingsside for "dette formål" i det eksterne systemet. Med "dette formål" menes: En påloggingsside som redirecter til Helsenorge sikkerhetstjeneste som OpenId connect provider. 
  3. Helsenorge sikkerhetstjeneste "ser" at innbygger allerede er innlogget, og redirecter innbygger tilbake til det eksterne systemet med en autorisasjonskode. 
  4. Det eksterne systemet benytter den mottatte autorisasjonskode for å hente autorisert informasjon om innlogget innbygger fra Helsenorge sikkerhetstjeneste (IdToken).
  5. Sluttresultatet er at det eksterne systemet har fått et ID-token utstedt av Helsenorge sikkerhetstjeneste. Dette inneholder innlogget brukers identitet (fødselsnummer og navn, samt eventuelle representasjonsforhold). 


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.

  • HTTP metode: POST

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.

Dette er: 

  • response_type: Ifbm. autentisering skal denne være "code".
  • client_id: Klientens tildelte id.
  • redirect_uri: URI som sluttbruker skal redirectes tilbake til etter fullført authentisering. 
  • scope: Scope som forespørres. For autentiseringer må "openid" brukes.
  • state: Verdi som settes av klient og returneres i callback-responsen etter fullført autentisering. Bør benyttes til å implementere CSRF-beskyttelse
  • nonce: Verdi som settes av klient og returneres som en del av ID token. Bør brukes til å binde en klient-sesjon til et gitt ID-token, og hindre replay attacks.
  • ui_locales: Ønsket språk brukt i Helsenorge. Støtter nb eller nn.

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:

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

  • client_secret_basic / client_secret_post: Klientautentisering basert på client_secret


Følgende header-parametere må brukes på request:

Parameter
Verdi
Http-metodePOST
Content-typeapplication/x-www-form-urlencoded
AuthorizationBasic <ClientSecret>

Samt at følgende attributter må sendes inn i requesten:

Attributt
Verdi
client_idKlientens ID
grant_typeauthorization_code
codeautorisasjonskode (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
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dGVzdF9ycF95dDI6cGFzc3dvcmQ=

client_id=FA5356DF-45EB-42F2-A906-7B4E88CD5266&grant_type=authorization_code&
redirect_uri=https%3A%2F%2Feid-exttest.helsenorge.no%2Fhelsenorge-oidc-client%2Fauthorize%2Fresponse&
code=1JzjKYcPh4MIPP9YWxRfL-IivWblfKdiRLJkZtJFMT0%3D


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:

  • AuthorizationCode: autorisasjonskode (code) motatt i autentiseringsresponsen
  • ClientId: Verdi fra  Authorization-header
  • ClientSecret: Verdi fra  Authorization-header
  • RedirectUri: Skal være samme som i autentiseringsforespørsel

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_timeTidspunktet 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"
issIdentifikator for provideren som har utstedt token’et. I prod: https://eksternapi.helsenorge.no/sts//helsenorge-oidc-provider/
pidPersonidentifikator - 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).
nameFullt navn (hvis representert; ellers innlogget)
given_nameFornavn (hvis representert; ellers innlogget)
family_nameEtternavn (hvis representert; ellers innlogget)
middle_nameMellomnavn (hvis representert; ellers innlogget)
pid_actPersonidentifikator - Helsenorge spesifikt claim som alltid gir innlogget brukers fødselsnummer.
act_nameFullt navn (innlogget)
act_given_nameFornavn (innlogget)
act_family_nameEtternavn (innlogget)
act_middle_nameMellomnavn (innlogget)
pid_act_typeHelsenorge 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

nonceSamme nonce som ble sendt inn av bruker i autentiseringsdelen nevnt over.
expExpire - Utløpstidspunktet for Id tokenet (UTC tid). Klienten skal ikke akseptere token’et etter dette tidspunktet.
iatTidspunkt for utstedelse av tokenet.
jtijwt id - unik identifikator for det aktuelle Id tokenet.
sidsesjonsid - 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_tokenID-token nevnt over
token_type"Bearer"
expires_inNår tokenet utløper
scope"openid"

Eksempel på respons fra token-endepunktet:

{"access_token":"","id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IkY0NkVDQjI5RjhCOTk5NEQyMjg2QjA3M0MxQ0VBNkE1MkJCNz
Q2RkMiLCJ0eXAiOiJKV1QifQ.eyJzdWIiOiJOR1EwT0RJMU9HTXRNV0l6TnkwMFltSmlMVGs1TVdNdE9UTTVOamN4T0dVNFpETmt
NakF3TXprME1EazBOakk9IiwiYXVkIjoiNGQ0ODI1OGMtMWIzNy00YmJiLTk5MWMtOTM5NjcxOGU4ZDNkIiwiYWNyIjoiTGV2ZWw
0IiwiYXV0aF90aW1lIjoiMTU5MzA3MjQ5MyIsImFtciI6InNpa2tlcmhldC5oZWxzZW5vcmdlLm5vIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9
zdDo1NzkyOS9oZWxzZW5vcmdlLW9pZGMtcHJvdmlkZXIvIiwicGlkIjoiMjAwMzk0MDk0NjIiLCJuYW1lIjoiVG9yaWxsIERhaGwgSm
FtYSIsImdpdmVuX25hbWUiOiJUb3JpbGwiLCJmYW1pbHlfbmFtZSI6IkphbWEiLCJtaWRkbGVfbmFtZSI6IkRhaGwiLCJwaWRfYWN
0IjoiMjAwMzk0MDk0NjIiLCJhY3RfbmFtZSI6IlRvcmlsbCBEYWhsIEphbWEiLCJhY3RfZ2l2ZW5fbmFtZSI6IlRvcmlsbCIsImFjdF9mYW1
pbHlfbmFtZSI6IkphbWEiLCJhY3RfbWlkZGxlX25hbWUiOiJEYWhsIiwicGlkX2FjdF90eXBlIjoic2Vnc2VsdiIsIm5vbmNlIjoiYTJkMTNlZ
WEtNTQyZS00OWFhLWJlODEtMTZkZThkMDk1YmUwIiwiZXhwIjoxNTkzMDc5NjkzLCJpYXQiOjE1OTMwNzI1MDgsImp0aSI6IjUy
OTUyM2RkLWQwYmItNDY2NS1hZjdlLWE5MTc1MjEyODcxMCIsInNpZCI6IllDWUJrRDM5ZG5HeDF3MEY0RXBMWUU0TnlBbGtrem
NUQUI2czdLeHBJbEpKckVSdWpHYnp1bkI4QUJGUlR6bnBCZ3ciLCJuYmYiOjE1OTMwNzI1MDh9.Dp3-BeVxTVg3jOopSsXvR4iibu
5DPtmPkOlVZJ1VylSMRvEOMizslLrhf38-JzwrKOGlBH36FeR5TRz2zPqVdi45LtrEoULK4617VQLdcrC-DCfwoOQikdweoH6Si8VY
ogc6sfaOSzjWWqPfnZkjSdXzlaIbg4VgydoHcgM5oANi1j6TrBpZZ5t8rNtl31dW9Z59biBZFvxmNQ__kKHJE7dSjtargvfvepxfG5p
XtIQU_YkrO2n2mbPakhOw5yc4-iGyb7qqc3Q3DaZxx124PmewnS8WnUd2AS_s0E0WGDrXRtnmLOZg2HtJQrsjTmTfE1FqZiFlI9j4HS_ktVNkxw",

"token_type":"BEARER","expires_in":7200,"scope":"openid"}

Validering av signatur på ID-token: 

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_hintanbefaltSettes lik mottatt id-token. Nødvendig for å kunne sende brukeren tilbake til tjenesteeiers post_logout_redirect_uri etter endt utlogging.
post_logout_redirect_urianbefaltMå være forhåndsregistrert på klient som id_token er utstedt til.
statevalgfri

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'