Här finns information om E-hälsomyndighetens tjänst för intygsväxling.

Termer och begrepp

Inledning

Intygsväxling från identitetsintyg till åtkomstintyg och tillhörande förnyelseintyg syftar i grunden på att skapa en lösare koppling mellan autentisering och auktorisation. Förnyelseintyget ger även möjlighet till längre sessioner genom att åtkomstintyget förnyas regelbundet, samtidigt som giltighetstiden för åtkomstintyget och identitetsintyget kan hållas kortare.

Den intygsväxling som E-hälsomyndigheten erbjuder utgår från RFC 7522 (datatracker.ietf.org) (Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants) och ger därmed möjlighet att växla från identitetsintyg enligt SAML 2.0 (docs.oasis-open.org) till åtkomst- och förnyelseintyg enligt OAuth 2.0.

Följande stödjs av tjänsten för intygsväxling eller användande av OAuth-åtkomstintyg:

• Alla roller (vård, apotek samt privatperson) kan växla ett giltigt SAML-intyg till ett åtkomstintyg (access token) för vidare åtkomst.

• Alla bastjänster från E-hälsomyndigheten kan anropas med en OAuth2-åtkomstintyg.

• Åtkomstintyget har en giltighetstid på 60 minuter.

• Via förnyelseintyget (refresh token) växla till sig ett nytt åtkomstintyg. (Se även Giltighetstid intyg).

• Stöd för flödet Assertion Flow/Implicit flow.

• Åtkomstintyget (access token) som är av typen JSON Web Token (JWT), skyddas mot insyn med hjälp av JSON Web Encryption (JWE). Åtkomstintyget är därmed inte läsbart för annan part än E-hälsomyndigheten.

• HTTP Basic som autentiseringsmetod för klienter. [RFC 6749, 2.3.1].

Följande stödjs inte:

• Inget stöd för att invalidera eller avsluta ett giltigt åtkomstintyg innan dess giltighetstid är slut.
• Inget stöd för "prompt", det vill säga påkalla slutanvändarens uppmärksamhet.
• Inget stöd för introspection.

Anropsflöde

För att genomföra en intygsväxling behöver användaren vara autentiserad och ett giltigt identitetsintyg behöver vara utfärdat och tillgängligt för E-tjänsten att intygsväxla.

Figur 1. Förenklat exempel på ett autentisering- och auktorisationsflöde, utfärdande av identitetsintyg.

1.0 Användaren begär åtkomst till E-tjänsten, eftersom användaren inte är autentiserad/auktoriserad så sker anvisning vald identitetsintygsutfärdare.

1.1 Användaren autentiserar sig mot identitetsintygsutfärdaren med sin personliga e-legitimation som sedan utfärdar ett identitetsintyg.

1.2 Användare begär åtkomst till E-tjänsten och bifogar identitetsintyget. Efter att E-tjänsten auktoriserat användaren ges åtkomst.

När E-tjänsten har ett identitetsintyg utfärdat för användaren kan intygsväxling ske, antingen genom direkt växling eller efter att ha kompletterat med behörighetsattribut.

• Intygsväxling med identitetsintyg
• Intygsväxling med identitetsintyg och kompletterande behörighetsattribut från E-tjänsten

Efter genomförd intygsväxling finns möjlighet att förnya åtkomstintyg genom att använda det förnyelseintyg som utfärdades som en del av den initiala växlingen från identitetsintyget. Efter att förnyelseintyget gått ut behöver ett nytt identitetsintyg utfärdas av identitetsintygsutfärdaren och en ny intygsväxling behöver genomföras.

• Åtkomstintyg genom förnyelse

Efter att intygsväxling eller förnyelse genomförts kan åtkomstintyget användas för åtkomst till E-hälsomyndighetens bastjänster.

• Anropsinformation WebService (SOAP)
• Anropsinformation REST (HTTP/JSON)

Intygsväxling med identitetsintyg

Intygsväxling sker med identitetsintyg som utfärdats av identitetsintygsutfärdaren och innehåller användarens identitet och de behörighetsattribut som ligger till grund för den tänkta åtkomsten.

Figur 2. Intygsväxling med identitetsintyg

1.0  E-tjänsten begär att växla in identitetsintyget och bifogar även användarnamn (client identifier) och lösenord (client secret).

1.1  Authorization Server returnerar ett åtkomstintyg (access token) ihop med ett förnyelseintyg (refresh token).

Om en klient väljer att använda sig av förnyelseintyg behöver klienten spara detta på ett säkert sätt i sin applikation. När klienten växlar sitt förnyelseintyg mot ett nytt åtkomstintyg returneras inget nytt förnyelseintyg, utan klienten förväntas använda det förnyelseintyg som returnerades vid den initiala växlingen vid varje förnyelse.

Parametrar som stöds

En mer detaljerad beskrivning av respektive parameter återfinns i gränssnittsbeskrivningen.

grant_type

urn:ietf:params:oauth:grant-type:saml2-bearer

assertion

I svar ges följande parametrar i en JSON-struktur:

access_token

expires_in

token_type

Bearer

refresh_token

Exempel på anrop

POST [host]/oauth2/api/oauth/token HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RUhNLVVTRVI6RUhNLVBTVw==
Content-Length: 6819
Host: [host]:[port]
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.2 (Java/1.8.0_152)

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&assertion=[SAML2:Assertion]

{
"access_token" : "[access_token]",
"expires_in" : 3600,
"token_type" : "Bearer",
"refresh_token" : "[refresh_token]"
}

Intygsväxling med identitetsintyg och kompletterande behörighetsattribut från E-tjänsten

Intygsväxling sker från identitetsintyget som innehåller användarens identitet och kan innehålla behörighetsattribut. E-tjänsten kompletterar sedan med behörighetsattribut på sidan av identitetsintyget som en del av intygsväxlingen. Se även Riktlinje för tillhandahållare av behörighetsstyrande attribut för krav kopplat till E-tjänsten för att få tillhandahålla kompletterande behörighetsattribut.

Resultatet blir detsamma som om identitetsintyget skulle ha innehållet samtliga behörighetsattribut, det vill säga att det utfärdade åtkomstintyget innehåller kombinationen av de båda. I de fall som ett behörighetsattribut återfinns i både identitetsintyget och som kompletterande behörighetsattribut från E-tjänsten är det den från E-tjänsten som anses vara mer aktuell och därmed kommer att användas. 

Figur 3 - Intygsväxling med identitetsintyg och kompletterande behörighetsattribut från E-tjänsten.

1.0  E-tjänsten paketerar och signerar relevanta behörighetsattribut enligt strukturen för parametern authorization_data. 

1.1  E-tjänsten begär att växla in identitetsintyget och bifogar även användarnamn (client identifier), lösenord (client secret) och de kompletterande behörighetsattributen (authorization_data)

1.2  Authorisation Server returnerar ett åtkomstintyg (access token) ihop med ett förnyelseintyg (refresh token).

Parametrar som stöds

En mer detaljerad beskrivningen av respektive parameter återfinns i gränssnittsbeskrivningen.

grant_type

urn:ietf:params:oauth:grant-type:saml2-bearer

assertion

authorization_data

I svar ges följande parametrar i en JSON-struktur:

access_token

expires_in

token_type

Bearer

refresh_token

Exempel på anrop

Ett exempel på förmedling av behörighetsattribut för en farmaceut på ett öppenvårdsapotek. Formatet på exemplet är enligt JWT/JWS och tre delar. Där grön text motsvarar huvudet och blå själva meddelandet och den rosa den omslutande signeringen.

Anropet till intygsväxlingen skulle då se ut enligt

Åtkomstintyg genom förnyelse

Förnyelse av åtkomstintyget kan ske inom ramen för förnyelseintygets giltighetstid (Se Giltighetstid intyg). Förnyelse kan ske innan eller i samband med att ett befintligt åtkomstintyg är på väg att bli ogiltigt och påverkar inte befintliga åtkomstintyg, det vill säga det är möjligt att ha flera giltiga samtidigt.

Figur 4 . Åtkomstintyg genom förnyelse. 

1.0  E-tjänsten begär att förnya åtkomstintyget och bifogar användarnamn (client identifier), lösenord (client secret) och förnyelseintyget (refresh_token)

1.1  Authorisation Server returnerar ett nytt åtkomstintyg (access token).

Parametrar som stöds

En mer detaljerad beskrivningen av respektive parameter återfinns i gränssnittsbeskrivningen.

grant_type

refresh_token

refresh_token

I svar ges följande parametrar i en JSON-struktur:

access_token

expires_in

token_type

Bearer

Exempel på anrop

POST [host]/oauth2/api/oauth/token HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RUhNLVVTRVI6RUhNLVBTVw==
Content-Length: 916
Host: [host]
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.5.2 (Java/12.0.1)

grant_type=refresh_token&refresh_token=[Förnyelseintyg]

{
"access_token" : "[Åtkomstintyg]",
"expires_in" : 3600,
"token_type" : "Bearer"
}

Gränssnittsspecifikation

Meddelandehuvud

Authorization

Authorization: Basic RUhNLVVTRVI6RUhNLVBTVw==

Content-Type

Content-Type: application/x-www-form-urlencoded

In- och utparametrar

Vid intygsväxling anges följande parametrar i HTTP-body (enligt format application/x-www-form-urlencoded):

grant_type

assertion

authorization_data

I svar ges följande parametrar i en JSON-struktur:

access_token

expires_in

token_type

refresh_token

Authorization_data 

För att komplettera med behörighetsattribut från E-tjänst förmedlas dessa enligt formatet JSON Web Token (JWT) (tools.ietf.org) och signeras i enlighet med JSON Web Signature (JWS) (tools.ietf.org).

typ

JWT

alg

HS256

jti

UUID

iss

<client_id>

iat

<tidpunkt, numeriskt värde>

Attribut/claims som förmedlas ska följa namnsättningen och övriga krav från Kompletterande säkerhetsattribut – Sweden Connect, läs mer på sidan Behörighetsstyrning. 

Signering av intyget sker med särskilt lösenord avsett för detta.

Versionshistorik