Account beheer en aanmelden

 Ik probeer uit te leggen hoe account beheer moet gaan werken op Aliconnect en way al mogelijk is. 

Doelstelling

Ik maak onderscheid in

1. De rechten die mogelijk zijn
2. Het proces van aanmelden

De rechten die mogelijk zijn

Eerst zal ik wat meer uitleggen over het regelen van rechten. Deze worden vastgelegd in een scope. 

Rechten op de API server

Rechten op de API server zijn geregeld door deze scope. Iedere aanvraag die een applicatie doet aan de API server is een URL, dus een opdracht zoals https://aliconnect.nl/api/Item(1) verwijst naar item nummer 1. Deze URL's zijn gebaseerd op de standaard OData (zie OData URL conventies voor meer informatie over de opbouw van een URL). Iedere URL kan worden aangeroepen met een method zoals GET, POST, PATCH of DELETE. 

De API wordt geconfigureerd en gespecificeerd. Hierbij is iedere mogelijke URL vastgelegd in de eigenschap paths ofwel URL paden van de Open API Specificatie (OAS, zie deze specificatie voor meer informatie).

Schemas

Binnen Aliconnect bouwen we geen database, we specificeren ieder data object als een schema. We configureren de database exact hetzelfde als de OAS. We beschrijven de properties van een schema en de API doet de rest.  

Opdracht scope

Iedere opdracht die de API kan uitvoeren leggen we vast als path ofwel pad. En om de opdracht te beveiligen geven we een security ofwel beveiliging op die bestaat uit een lijst van scope namen ofwel rechten die nodig zijn om de opdracht uit te voeren.

Om bijvoorbeeld een contact toe te voegen maken we gebruik van het pad: '/Contact' en de methode 'post'. Hier geven we bij security op de scope: 'contact.readwrite'. Om een specifiek contact te bekijken of te wijzigen maken we gebruik van het pad '/Contact({id})'. Met de methode 'patch' kunnen we gegevens wijzigen en dus koppelen we daaraan de scope 'contact.readwrite'. Om contact gegevens te lezen maken we gebruik van de methode 'get', ook deze krijgt de scope 'contact.readwrite'. We voegen echter een extra scope 'contact.read' toe. Nu kunnen we gebruikers alleen lees rechten geven door bij hen de scope 'contact.read' aan te geven.

Opdracht generatie

Om nu niet ieder pad te moeten specificeren worden deze paden gegenereerd gebaseerd op de schema configuratie. Voor ieder schema heb je standaard het pad '/schemanaam' met de methode get voor zoeken en de methode post voor toevoegen. En voor een specifiek item het pad '/schemanaam({id})' en de methode patch voor aanpassen en delete voor verwijderen. Ieder pad krijgt standaard de scope 'schemanaam.read' bij de methoden 'get' en de scope 'schemanaam.readwrite' bij de methode post, patch en delete. Deze rechten kunnen desgewenst uitgebreid worden met een verzamelgroep zoals bijvoorbeeld de groep 'crm.readwrite' voor contacten, organisaties en andere aan CRM gerelateerde schema's.

Beveiliging door een toegangssleutel

Om de toegang tot gegevens te beveiligen ontvangt ieder gebruiker een sleutel van de login(authentication) server. In deze toegangs-sleutel(access_token) zijn de rechten(scope) van de gebruiker vastgelegd. Deze toegangssleutel is voorzien van een handtekening(signature) die versleuteld(encrypted) is met een geheime klant code(client_secret) die alleen bekend is bij de authenticatie server en klant data servers. Niemand kan de sleutel dus aanpassen want dan klopt de versleutelde handtekening niet meer.

Bij iedere opdracht aan de gegevens server moet de toegangs-sleutel worden meegestuurd waarvan de handtekening op de server wordt gecontroleerd. Is deze handtekening goed dan bekijkt de server de scope en, indien de security dit toelaat, wordt de opdracht uitgevoerd.

Het proces van aanmelden

We houden zo goed mogelijk vast aan oauth. Maar om alles werkend te krijgen heb ik zo mijn eigen invullingen gedaan. Samen probeer ik een oplossing te bouwen waar iedereen gebruik van kan maken. 

de rechten van een gebruiker authenticatie

Ontwerp keuzes

1. Zijn schemas en paden wel/niet hoofdletter gevoelig