API-documentatie

OpenAC 3 is volledig API-gebaseerd. Dat betekent dat de gebruikersinterface gebruikt maakt van API-endpoints die ook kan worden geconsumeerd door externe applicaties die aan OpenAC koppelen. OpenAC maakt gebruik van een methode waarmee API-documentatie automatisch wordt gegenereerd. Deze documentatie is daarom altijd up-to-date voor de versie die u gebruikt. De documentatie is te vinden via menu Beheer -> API-documentatie. Veel API-endpoints kunnen via deze pagina ook gelijk worden getest.

Authenticatie

Voor de meeste API-endpoints is authenticatie vereist. Authenticeren kan op twee manieren:

• Token based;
• Cookie based;

Token based (JWT-token)

Bij token based authenticatie genereert de OpenAC beheerder een JWT-token en verstrekt deze aan de partij die de OpenAC-API wil gebruiken. Het token heeft een geldigheidsduur. Zolang het token geldig is kan het worden gebruikt om toegang te krijgen tot de OpenAC-API. Omdat het token niet tussentijds kan worden ingetrokken is het belangrijk om de ACL goed in te richten voor het gebruik van de API.

ACL-inrichting

Als u JWT-tokens verstrekt aan een externe partij dan adviseren we de ACL als volgt in te richten:

• Maak een gebruikersgroep met de naam van de externe partij voorafgegaan door api- (api-drimpy);
• Geef deze groep de benodigde rechten in de ACL;
• Maak één of meerdere gebruikers en maak deze lid van de API-groep;
• Genereer voor elk van de gebruikers een JWT-token;

Als het nodig is om de externe partij toegang tot de API te ontzeggen dan kunt u de rechten voor de API-groep intrekken in de ACL. Als de rechten van één van de API-gebruikers moet worden ingetrokken dan kunt u het API-groep lidmaatschap intrekken.

Configuratie

Neem de volgende sectie op in appsettings.json:

  "Api": {
    "Token": {
      "Issuer": "https://www.fenac.nl",
      "Audience": "https://www.fenac.nl",
      "SigningKey": "41b3feb8-92cd-44bc-bac4-0a1d623e2f77"
    }
  },

Verander Issuer en Audience in de website van uw organisatie. Verander de SigningKey in een UUID, bijvoorbeeld gegenereerd met ​https://uuidgenerator.net.

In een testomgeving is het mogelijk tokens te genereren zonder dat bovenstaande sectie is geconfigureerd. OpenAC laat dan een waarschuwing zien dat een default signing key wordt gebruikt, zie onderstaande screenshot.

Token genereren

Met het formulier op Beheer -> Genereer API-token kan een token worden gegenereerd voor een gebruiker.

Selecteer een gebruiker en einddatum en klik op de knop "Genereer token" om een token te genereren. Deze actie levert een foutmelding op als:

• u onvoldoende rechten heeft om een token te mogen genereren;
• de geselecteerde gebruiker is niet in gebruik;
• de geselecteerde gebruiker is admin. Dat is om beveiligingsredenen niet toegestaan.

Als het gelukt is om een token te genereren kan deze naar het klembord worden gekopieerd. U kunt kiezen om alleen het token te kopiëren of ook de bijbehorende gebruiker en geldigheidsduur.

Token gebruiken

Roep elk API-endpoint aan met HTTP-header: Authorization: Bearer <token>

Cookie based (Login-API)

Met de login-API kan een sessie worden opgebouwd met de OpenAC 3 server. De API kan zowel met als zonder Two Factor Authentication gebruikt worden. De returnwaarde van de API is gelijk aan het model dat als payload moet worden meegegeven met de POST. Bij Two Factor Authentication moet het teruggekregen model opnieuw worden meegegeven met een tweede aanroep van de API, aangevuld met het beveiligingstoken.

Zonder Two Factor Authentication

“success” en “complete” zijn beide true bij een succesvolle login. “success” en “complete” zijn beide false bij een niet-succesvolle login.

Met Two Factor Authentication

Het inloggen gebeurt in twee fasen, de API moet twee keer worden aangeroepen, de tweede aanroep bevat het bevat het beveiligingstoken. “success” is true bij een succesvolle login. “success” is false bij een niet-succesvolle login.

Als “fase” 2 is dan bevat “message” een bericht aan de gebruiker met informatie over de manier waarop het beveiligingstoken is verstuurd. Hierna moet opnieuw de login API worden aangeroepen met het eerder teruggekregen login-model en “challenge” gevuld met het door de gebruiker ingevulde beveiligingstoken. Als “complete” true is dan is het inlogproces voltooid.

OpenAC geeft bij een succesvolle login een cookie terug die bij alle volgende API-aanroepen moet worden meegegeven.

Voorbeeld gebruik

            POST /api/login
           {
              "username": "mkaleb",
              "password": "Ackn0wledge!",
              "agbLocatie": "19009338",
              "agendaLocatie": "h",
              "challenge": "",
              "fase": 0,
              "session": "",
              "success": false,
              "message": "",
              "complete": false
            }