VERSIE: 19-05-2023 STATUS: definitief

Incrementele implementatie
Het iWlz-netwerkmodel wordt incrementeel geïmplementeerd aan de hand van het afsprakenstelsel iWlz-netwerkmodel. Het eerste deel dat wordt geïmplementeerd is het Indicatieregister.

De dienst Autoriseren wordt deels ingevoerd in de eerste implementatiestap. Autoriseren vindt namelijk plaats als onderdeel van notificeren. De ambitie is om deze twee diensten in de volgende implementatiestap van elkaar te scheiden om het vraaggestuurd raadplegen van gegevens mogelijk te maken.

De inhoud van dit artikel geeft de situatie weer voor de eerste implementatiestap.

Dit artikel beschrijft het autoriseren van systemen in het iWlz-netwerkmodel met behulp van het OAuth 2.0-framework. OAuth 2.0 is een algemeen geaccepteerd autorisatie framework. Het OAuth 2.0-framework is in hoge mate aanpasbaar en accepteert vele grant-types.

Het iWlz-netwerkmodel gebruikt de authorization code grant-type. Dit artikel beschrijft hoe een systeem kan worden geïdentificeerd om vervolgens met een authorization code een access token kan worden opgehaald dat vervolgens kan worden gebruikt als bearer token voor autorisatie bij de resource server.

1. Inleiding

In dit artikel bieden we een manier om service-API's (bijv. RESTful, GraphQL) te beschermen met behulp van een OAuth 2.0-access token. In tegenstelling tot een reguliere OAuth-flow waarbij een gebruiker wordt doorgestuurd naar een authenticatie server om in te loggen, ontvangt de client(applicatie) een authorisatie code. Dit document beschrijft de methode voor het verkrijgen van het access token met behulp van een OAuth2-flow en beschrijft het gebruik van het access token tijdens een API-request.

2. Terminologie

Client(applicatie): de toepassing die toegang aanvraagt.
JSON Web Token (JWT): Een string welke een set van claims in de vorm van JSON-objecten beschrijft. Deze kunnen digitaal worden ondertekend en/of MACed(soort van sleutel waarmee de authenticiteit van een bericht kan worden gecontroleerd) en/of versleuteld
Claim: Informatie over het subject (onderwerp), weergegeven in name/value paar.
Resource Server: de applicatie (een beschermde bron) die geautoriseerde toegang tot zijn API's vereist.
Access token: een OAuth 2-access token, geleverd door een autorisatie server. Dit access token wordt aan de Client(applicatie) overhandigd, zodat deze zichzelf kan autoriseren bij een resource server. De gebruikte JWT is in ontsleutelde vorm een door de mens leesbaar formaat (JSON), maar MAG NIET worden gebruikt voor functionaliteit in de client. Echter door het ontbreken van functionaliteit in de notificatie (in de implementatiestap Indicatieregister) is het noodzakelijk om hieruit het indicatieID te halen om een data verzoek te kunnen uitvoeren.
Autorisatie server: de autorisatie server controleert de identiteit en de overlegde AutorisatieCredentials van de gebruiker en maakt het access token aan. De autorisatieserver wordt vertrouwd door de resource server. Wanneer het de uitgifte van autorisaties betreft wordt de autorisatie server ook wel aangeduid met Lua Runner.
Request context: de context van een aanvraag die wordt geïdentificeerd door het access token. Het access token verwijst naar deze context. De context bestaat uit de autorisator (de bronhouder), aanvrager (de afnemer), service-endpoint: elk geregistreerd service-endpoint heeft een unieke referentie.

3. OAuth flow

Het mechanisme voor het ophalen van een access token wordt gedaan volgens de OAuth 2.0 Authorization Code Flow (gedefinieerd in OAuth 2.0 RFC 6749, section 4.1).

Diagram 1: Authorization Code Flow

Diagram 1 toont de referentie OAuth authorisation code flow welke bestaat uit 4 delen: het verkrijgen van de Authorization Code, het verkrijgen van een access token, het vernieuwen van het acces token en het gebruiken van het access token.

3.1 Verkrijg authorization code

Stap 1 t/m 4 van de Authorization Code Flow weergegeven in diagram 1 worden in het iWlz-netwerkmodel niet uitgevoerd. In het iWlz-netwerkmodel worden authorization codes niet opgevraagd, maar toegestuurd door de authorization server(stap 5), na initiatie vanuit de Lua Runner door het optreden van een event.

Na het ontvangen van de authorization code MOET de Client Application, wanneer deze goed is verwerkt een response code 202 retourneren aan de autorisatieserver.

De authorization code MOET verlopen kort nadat deze is uitgegeven door de autorisatie server om het risico van misbruik te verkleinen.

De autorisatiecode in het iWlz-netwerkmodel verloopt na 1 minuut.

Het is aan te bevelen om in dezelfde sessie waarin de autorisatiecode is ontvangen ook direct de access token op te halen. Dit voorkomt het verloren gaan van het recht om een JWT token op te halen.

3.2 Verkrijg access token

De client(applicatie) van de afnemer MOET een access token verkrijgen bij de autorisatieserver voordat toegang tot gegevens kan worden verkregen. Dit MOET worden gedaan binnen de geldigheidstermijn van de autorisatiecode of refresh token.

Bij het opvragen van de access token in het netwerkmodel gebruikte grant_type “authorization code” MOET een client zich identificeren met een “client_id en client_secret”. Dit is niet van toepassing bij het bevragen van de afgeschermde resource zelf.

Binnen het iWlz-netwerkmodel vereisen de TLS verbindingen een clientcertificaat(mTLS). De client(applicatie) MOET een geldig VECOZO-systeemcertificaat meesturen welke geregistreerd is bij de hiervoor genoemde client_id. Ook MOET het IP-adres van waaruit het verzoek wordt uitgevoerd zijn geregistreerd bij VECOZO .

Als het verzoek om een access token geldig en geautoriseerd is, geeft de autorisatieserver een access token en een refresh token uit. Als de aanvraag door de client(applicatie) mislukt of ongeldig is, stuurt de autorisatieserver een foutcode terug zoals beschreven in paragraaf 5.2.

De client(applicatie) van de afnemer MOET het access token vernieuwen als er opnieuw, meer of andere gegevens worden opgevraagd.

Een access token is maximaal 1 uur geldig (bepaald door de autorisatie server).

3.3 Access token gebruiken

Bij het opvragen van gegevens MOET de client(application) van de afnemer het access token toevoegen aan de Authorization-header als een Bearer-token, zoals vermeld in RFC7523. De resource server MOET het access token valideren bij de autorisatie server. De resource server en autorisatie server MOETEN samen beslissen of een access token geldig is voor de aangevraagde resource.

Een access token kan tot aan de expiration date/time meerdere keren worden gebruikt.

4. Autorisatie-client

4.1 Registratie van client

Bij reguliere OAuth2-flows moet een OAuth-client worden geregistreerd bij de autorisatie server met zijn client-ID en client-secret. Zo weet de autorisatie server welke verzoeken door welke partij worden gedaan. De registratie omvat nu handmatige stappen van registreren en goedkeuren.

5. Autorisatie server

5.1 Foutcodes

Fouten worden geretourneerd zoals beschreven in RFC 6749: The OAuth 2.0 Authorization Framework.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "error":"invalid_request"
}

5.2 Access token

Er is geen beperking op het type access token dat wordt uitgegeven door de autorisatie server. De volgende punten zijn echter van toepassing op alle vormen van access tokens:

De autorisatie server MOET ervoor zorgen dat de access token uniek is en niet opnieuw wordt gebruikt voor een andere context.
De autorisatieserver MOET de context opslaan die aan het access token is gekoppeld, zodat de resource server erom kan vragen.
Het access token MOET gemarkeerd zijn om alleen voor een specifieke afnemer te werken. Dus wanneer de client(applicatie) van een afnemer resources aanvraagt, kan het access token samen met het TLS-clientcertificaat van de afnemer worden gecontroleerd. Dit voorkomt dat het resulterende access token wordt gebruikt door andere partijen dan de beoogde afnemer.

Access tokens zijn maximaal 1 uur geldig.

5.3 Refresh Token

Met de refresh token die de autorisatieserver aan de client heeft uitgegeven, kan de client een vernieuwingsverzoek versturen aan het token endpoint van de autorisatieserver eindpunt door de volgende parameters met behulp van het "application/x-www-form-urlencoded" formaat.

HTTP request entity-body:

grant_type
- MOET. Waarde moet worden gezet op "refresh_token".
refresh_token
- MOET. De refresh token die eerder is uitgedeeld door de autorisatieserver.

Omdat refresh tokens doorgaans langdurige inloggegevens zijn die worden gebruikt om (aanvullende) access tokens aan te vragen, is de refresh token gebonden aan de client(applicatie) aan waaraan het is uitgegeven. De client(applicatie) MOET zich authenticeren met de autorisatieserver zoals beschreven bij het opvragen van de access token.

Een voorbeeld van een HTTP verzoek over TLS verbinding (Met extra regeleinden t.b.v. de leesbaarheid)

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

De autorisatieserver MOET:

De client(applicatie) autoriseren op basis van de uitgegeven client credentials (Client_Id en Client_secret)
Controleren of de Refresh token is afgegeven aan de betreffende client(applicatie).
Controleren van de geldigheid van de Refresh token

Als aan bovenstaande voorwaarden is voldaan wordt er zowel een nieuw access token als ook een nieuwe refresh token geretourneerd. Als het vernieuwingsverzoek fout gaat of wordt afgewezen zal de autorisatieserver een foutmelding retourneren.

The Client(application) MOET de oude refresh token verwijderen en vervangen door de nieuwe refresh token. De autorisatieserver MOET de oude refresh token revoken.

Een Refresh Token heeft een lifetime van 7 dagen.

5.3.1 Refresh Token Rotation

Refresh token rotation is een techniek om nieuwe access Tokens op te vragen waarbij de Refresh Token een nieuwe expiration date krijgt.

6. Resource Server

6.1. Access token

Het access token MOET aanwezig zijn in de Authorization-header als bearer token:

POST  /wlzindicaties/wlzindicatiespersoon HTTP/1.1
     Host: resources.example.com
     Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0.
     eyJpc3Mi[...omitted for brevity...].
     J9l-ZhwP[...omitted for brevity...]

Een access token KAN meerdere keren worden gebruikt, tenzij de geretourneerde foutcode dit verhindert. Een access token MAG NIET worden gebruikt als deze is verlopen.

6.2 Filtering op basis autorisatiegegevens

De resource server MOET de geldigheid van het access token valideren. Het KAN contact opnemen met de autorisatie server om het access token te valideren, of het KAN bestaande kennis gebruiken om het access token te valideren. Een JWT kan bijvoorbeeld worden gevalideerd door de geregistreerde publieke sleutel van de autorisatie server te gebruiken. De volgende stap is om te valideren of het access token mag worden gebruikt om toegang te krijgen tot de gevraagde resource. Er zijn drie verschillende gevallen die MOETEN worden ondersteund:

De gevraagde resource bevat geen persoonsgegevens. Bepaalde resource bevatten geen persoonsgegevens en kunnen zonder gebruikerscontext worden uitgewisseld. Resources die in deze categorie vallen, MOETEN als zodanig worden gemarkeerd in de specifieke use case-specificatie.
De aangevraagde resource bevat persoonsgegevens. In het iWlz-netwerkmodel wordt ervoor gekozen om ook in deze gevallen nog NIET te valideren dat de gebruikerscontext aanwezig is.
De aanvrager en autorisator zijn dezelfde. Het kan voorkomen dat een deelnemer gebruik maakt van meerdere dienstverleners. Elke dienstverlener handelt dan namens de deelnemer. Het is niet nodig om gebruikerscontext op te geven. Het is aan de dienstverleners om te zorgen voor de juiste handhaving van rollen en eventuele controletaken. Elk van de dienstverleners (aanvrager en autorisator) KAN verschillende identificatiemiddelen gebruiken voor dezelfde deelnemer.

In de eerste twee gevallen MOET de resource server controleren of het toegangsbeleid de aangevraagde resource dekt. Dit wordt ook wel aangeduid met filtering. Het toegangsbeleid wordt beschreven in het onderdeel access policy van ieder uitwisselprofiel. Wanneer in een volgende versie van het afsprakenstelsel meer dan 1 uitwisselprofiel wordt ondersteund, kan het zinnig zijn om ook een generiek access policy te formuleren.