Wat JSON:API NIET doet

JSON:API is volledig entiteitsgebaseerd. Dat wil zeggen dat het geen bedrijfsregels kan verwerken of dingen kan doen die niet als “CRUD” kunnen worden beschouwd. Bedrijfslogica, zoals het registreren van een nieuw account, het inloggen van een gebruiker of het aanvragen van een nieuw wachtwoord, maken geen deel uit van JSON:API. Veel hiervan wordt al door Drupal core geleverd.

Hieronder volgt een niet-uitputtende lijst met veelvoorkomende behoeften en oplossingen.

Relevante paden zijn:

• /session/token
• /user/register
• /user/login
• /user/login_status
• /user/logout

Een session-token verkrijgen

Token ophalen

curl \
  --request GET http://drupal.d8/session/token

Een token wordt als platte tekst (niet JSON) in de response body teruggegeven.

Tokens gebruiken

Naast een session-token krijg je bij het inloggen een csrf_token en een logout_token. Je hebt het logout_token nodig om een gebruiker uit te loggen (zie hieronder). Het csrf_token of het session-token is noodzakelijk voor muterende requests (bijv. POST, PATCH en DELETE).

Gebruikersregistratie

Hoewel JSON:API zoals geleverd door core geen nieuwe gebruikersregistraties ondersteunt, kun je de module JSON:API User Resources installeren om user-gerelateerde JSON:API-endpoints toe te voegen, waaronder endpoints voor registratie, wachtwoord resetten en wachtwoord bijwerken.

Als alternatief kun je de core REST-module gebruiken. Om gebruikers via REST toe te staan een account te registreren, moet de REST-resource user_registration ingeschakeld zijn (zie het REST UI-voorbeeld hieronder).

curl \
--header "Content-Type: application/json" \
--header "X-CSRF-Token: 57sTS-KS7UoYAWAPyzt0iJmo300CFct3jdKyWM-UiiQ" \
--request POST "https://drupal.d9/user/register?_format=json" \
--data '{"name": {"value": "thename123"}, "pass": {"value": "thepass"}, "mail": {"value": "someone@example.com"}}'

Gebruik de waarde van het session-token met de header X-CSRF-Token. Een succesvolle response zou enkele user-veldwaarden moeten bevatten, waaronder de UUID van de nieuw aangemaakte gebruiker:

{
   "uuid" : [ { "value" : "3e75b757-831e-4bf7-bbb6-25b8c50c7ac0" } ]
}

Let er ook op dat de response geen “Set-Cookie”-headers bevat, zelfs niet als bezoekers zelf een account mogen aanmaken. Dus als er geen goedkeuring of bevestiging vereist is, kun je een gebruiker na een succesvolle registratie direct inloggen met dezelfde name- en pass-waarden.

Gebruiker inloggen

curl \
  --header "Content-type: application/json" \
  -c cookie.txt \
  --request POST "http://drupal.d8/user/login?_format=json" \
  --data '{"name":"admin", "pass":"admin"}'

De optie -c cookie.txt vertelt curl om een cookie op te slaan. Je response zou er ongeveer zo uit moeten zien:

{
   "csrf_token" : "57sTS-KS7UoYAWAPyzt0iJmo300CFct3jdKyWM-UiiQ",
   "logout_token" : "zzRaD8ZgLT1TkG804mYpVVTyM-pgoDm4h9XZ9JHSoCw",
   "current_user" : {
      "roles" : [
         "authenticated",
         "administrator"
      ],
      "name" : "admin",
      "uid" : "1"
   }
}

Gebruikersstatus

curl \
  --header "Content-type: application/json" \
  -b cookie.txt \
  --request GET "http://drupal.d8/user/login_status?_format=json"

-b cookie.txt vertelt curl om de cookie van het vorige verzoek te versturen (niet op te slaan). Als je bent ingelogd, retourneert dit 1 in de response body in platte-tekstformaat (niet JSON), anders 0.

Gebruiker uitloggen

curl \
  --header "Content-type: application/json" \
  -b cookie.txt \
  --request POST "http://drupal.d8/user/logout?_format=json&token=zzRaD8ZgLT1TkG804mYpVVTyM-pgoDm4h9XZ9JHSoCw"

Dit zal de gebruiker die is geauthenticeerd via cookie.txt uitloggen. Gebruik de waarde van logout_token met de queryparameter token.

Authenticatiemechanismen

Het bovenstaande voorbeeld is slechts één van de vele beschikbare authenticatiemechanismen. Onderzoek welk mechanisme het beste past bij jouw behoeften.

Er is een Drupal OAuth-module beschikbaar als simple_oauth.

Referenties

Zie deze change records voor meer informatie:

• https://www.drupal.org/node/2720655 (login, login_status en logout)
• https://www.drupal.org/node/2752071 (register)

Voor authenticatie kun je ook overwegen andere authenticatieprotocollen te gebruiken.

Als je voor je JavaScript-app aan de frontend en Drupal aan de backend de “cookie”-aanpak kiest, kan de browser al het werk voor het opslaan van cookies voor je doen. Vergeet alleen niet dat, als je JS-app en je Drupal-site verschillende domeinnamen hebben, je browsers moet toestaan om sessiecookies van gebruikers op te slaan door de SameSite-cookieparameter op “None” te zetten. Bewerk hiervoor je services.yml-bestand en voeg de volgende parameter toe:

parameters:
  session.storage.options:
    cookie_samesite: None

REST UI

De contribmodule REST UI maakt het mogelijk om resources van de core REST-module te configureren. Laten we bekijken hoe we gebruikersregistratie met deze module kunnen inschakelen.

1. Ga, na het installeren en inschakelen van de REST UI-module, naar de configuratiepagina op /admin/config/services/rest en schakel de resource “User registration” in. Bewerk de resource en schakel bijvoorbeeld de methode POST, het JSON-formaat en de Cookie-provider in. Door de granulariteit op “method” te zetten, kun je ook formaten en providers per requestmethode scheiden.
2. Geef vervolgens anonieme gebruikers de permissie “Access POST on User registration resource” op /admin/people/permissions/module/rest.
3. Controleer ten slotte op /admin/config/people/accounts of bezoekers een account mogen aanmaken.

Artikel uit Drupal-documentatie.