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 ønskes avviklet 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

• PROD: https://eksternapi.helsenorge.no/sts/helsenorge-oidc-provider/v1/.well-known/openid-configuration
• TEST: https://eksternapi.hn.test.nhn.no/sts/helsenorge-oidc-provider/v1/.well-known/openid-configuration

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

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

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

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:

ID tokenets body:

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:

Eksempel på respons fra token-endepunktet:

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.

Eksempel på utloggings-url: