Introduksjon

Det er identifisert flere situasjoner der det ønskes "sømløs overgang" fra Helsenorge til eksterne systemer uten at innbygger skal måtte logge seg på igjen. Dette kan i utgangspunktet løses dersom det eksterne systemet også benytter ID-porten for pålogging av innbygger.

Imidlertid er det stadig flere UseCaser der det eksterne systemet har behov for mere informasjon om innlogget innbygger enn det som ID-porten gir. Derfor har Helsenorge en egen OpenID Connect provider som tilbyr "verdiøket" informasjon. Helsenorge OpenID Connect provider gir det ekstrene systemet tilgang til følgende funksjonalitet:

• Informasjon om eventuell representasjon mellom innlogget innbygger og pasient som representeres (foreldre, fullmakt, vergemål).
• Dersom ekstrent system etterpå skal ha tilgang til API'er på Helsenorge i context av innlogget/representert innbygger, gis det ut et Aksesstoken som representerer det eksterne systemets rettigheter. Dette kan etterpå benyttes mot API'ene.

Ved slike behov skal det eksterne systemet benytte Helsenorge sikkerhetstjeneste som OpenID Connect provider i stedet for ID-porten. 

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. Dersom det ekstrene systemet også siden ønsker tilgang til API på Helsenorge, ber den om ønsket(ede) scope i forespørselen til STS.
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 autorisasjonstoken for å hente autorisert informasjon om innlogget innbygger fra Helsenorge sikkerhetstjeneste (IdToken) samt de autorisasjoner som kan gis til det eksterne systemet mt Helsenorge API'er (AksessToken) dersom dette er relevant.
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). Og, eventuelt et AksessToken som er låst til innlogget/representert innbygger og som representerer et antall autorisasjoner.

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, eventuelle andre scopes (for å benytte API'er) kan også angis.
• 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: