Veel API's vereisen dat de caller authenticatie-informatie opgeeft om hun identiteit te verifiëren, en mogelijk de toegangsrechten van die caller. Authenticatie-informatie kan doorgegeven worden met behulp van HTTP headers (Basic/NTLM/Digest-authenticatie), door access tokens (OAuth) uit te wisselen, door te eisen dat de cliënt een cliëntcertificaat toevoegt aan de request, of een combinatie hiervan. 

In dit artikel worden de op HTTP header en token gebaseerde authenticatie-opties in Uptrends besproken. Meer informatie over het configureren van cliëntcertificaten vindt u in het artikel over authenticatie van cliëntcertificaten

Standaartypes authenticatie

Het gedeelte Authenticatie op het tabblad Request van een controleregel Multi-step API biedt verschillende authenticatietypen. Ze gebruiken allemaal een gebruikersnaam/wachtwoord-combinatie, maar de manier waarop deze inloggegevens worden verwerkt en naar de API worden verzonden, is voor elk type verschillend:

  • Basic Authentication: de gebruikersnaam en het wachtwoord zijn gecodeerd in een eenvoudig Base-64-gecodeerd formaat en worden verzonden naar de API-server.
  • NTLM (Windows) Authentication: wanneer u dit type opgeeft, worden er verschillende requests naar de API verzonden om te onderhandelen over de authenticatie die moet worden gebruikt, voordat de laatste HTTP-request met de juiste authenticatie wordt verzonden. Deze reeks requests telt als één enkele stap. Als een Windows-domein moet worden opgegeven, neemt u dit op in de gebruikersnaam: YOURDOMAIN\username
  • Digest Authentication: wanneer u dit type opgeeft, sturen we twee opeenvolgende requests naar de API. De eerste stuurt een request zonder enige authenticatie-informatie en verwacht van de server dat deze authenticatiespecifieke instructies retourneert in de WWW-Authenticate response header. De gebruikersnaam en het wachtwoord worden gehasht volgens deze instructies (inclusief nonce- en qop-waarden) en in de tweede request verzonden die vervolgens correct is geauthenticeerd. Deze reeks requests telt als één enkele stap.
  • None: kies None als u geen gebruik wilt maken van authenticatie voor uw HTTP request.

HTTP headers

Wanneer u een van deze authenticatietypen gebruikt, hoeft u geen andere authenticatie-specifieke HTTP-headers op te geven: we zullen de juiste Authorization-header voor u genereren.

Ondersteuning van variabelen

De velden gebruikersnaam en wachtwoord ondersteunen variabelen. U kunt voorgedefinieerde variabelen (bijvoorbeeld: {{username}} en {{password}}) met de juiste waarden creëren en deze variabelennamen vervolgens gebruiken in de authenticatievelden. Hier vindt u meer informatie over variabelen en voorgedefinieerde variabelen.

Aangepaste authenticatie (inclusief OAuth)

Wanneer uw API OAuth als authenticatieprotocol gebruikt, hebt u een meer uitgebreide set-up nodig. Afhankelijk van uw API hebt u wellicht iets nodig dat heel specifiek is voor uw situatie. OAuth 2.0 in het bijzonder gebruikt ten minste één afzonderlijk request voor alleen het authenticatieproces. Met deze request wordt toegang tot de API gevraagd (met behulp van een van de standaardauthenticatietypen, door in de URL inloggegevens op te geven of zelfs een webpagina log-in uit te voeren). Na succesvolle authenticatie wordt het OAuth access token vastgelegd en opgeslagen in een variabele, zodat het in volgende aanvragen kan worden gebruikt.

Als u geen gebruikmaakt van OAuth maar van een ander protocol, werkt het mogelijk nog steeds op dezelfde manier: u moet eerst inloggegevens opgeven die uw identiteit aan de API 'bewijzen'. De API-server reageert dan door u een inlogtoken te geven dat een bepaalde tijd geldig is. Door dat token vast te leggen en op te slaan in een variabele, kunt u een reeks requests uitvoeren die het inlogtoken gebruiken om toegang te krijgen.

OAuth 2.0-authentcatie instellen

In het volgende voorbeeld zullen we een eenvoudige vorm van OAuth 2.0-authenticatie opzetten. Ons doel is om een toegangstoken te verkrijgen van de API, die we vervolgens in latere requests kunnen gebruiken.

Hiervoor sturen we eerst een request die de juiste OAuth-velden bevat. In dit geval vragen we om toegang op basis van een autorisatiecode, een klant-id en een klantgeheim. De klant-id en het klantgeheim zijn vaste waarden die we kunnen definiëren als voorgedefinieerde variabelen. In onze eenvoudige configuratie zal de autorisatiecode ook een vaste waarde zijn, maar in uw configuratie kan het nodig zijn om die autorisatiecode eerst met een afzonderlijke stap op te halen.

Eerst voegen we die waarden toe aan de voorgedefinieerde variabelen:

Nu die variabelen gedefinieerd zijn, kunnen we nu een request voor onze API instellen door verwijzingen naar die variabelen erin op te nemen, samen met andere parameters die de API verwacht. Voeg in de eerste stap van onze multi-step-opzet deze URL toe:

GET https://myapi.com/oauth/token?grant_type=authorization_code&code={{authorizationcode}}&client_id={{clientid}}&client_secret={{clientsecret}}

We verwachten dat de API een datastructuur retourneert die het toegangstoken bevat dat we nodig hebben, maar hoe wordt die datastructuur geformatteerd? Om ervoor te zorgen dat we gegevens in JSON-indeling krijgen, vertellen we de server dat we alleen het application/json formaat accepteren door dat in een HTTP-header te specificeren:

Nu deze header is gespecificeerd kunnen we verwachten dat de respons er ongeveer zo uitziet:

{
  "access_token":"SGV5ISBZb3UgZm91bmQgdGhpcyB0ZXh0IQ==",
  "token_type":"Bearer",
  "expires_in":86400
}

Het enige wat we nu hoeven te doen, is het veld access_token vast te leggen in de JSON-respons. Om dit te doen maken we een nieuwe variabele op het tabblad Response van onze stap:

  • De respons zou JSON moeten bevatten, dus kies Response body as JSON als de bron voor onze variabele.
  • Aangezien het kenmerk access_token zich op het hoogste niveau in onze datastructuur bevindt, is onze access_token.
  • We kiezen accesstoken als onze variabelenaam. Dit is de naam waarnaar we in latere stappen zullen verwijzen.

Hoewel het hoofddoel van deze eerste stap is om het access token vast te leggen, voert het ook al enige controle uit: als de API op dit punt een fout retourneert of als de respons geen access token bevat, zal deze stap dit detecteren en een fout rapporteren.

Nu we een geldig access token hebben, kunnen we eindelijk toegang krijgen tot de feitelijke API-methode die we willen controleren (bijvoorbeeld voor het ophalen van een lijst met producten). Maak een nieuwe stap om deze API call te definiëren. Nadat we de methode en URL voor deze nieuwe request hebben opgegeven, gaan we het access token dat we zojuist hebben vastgelegd, doorgeven. OAuth 2.0-gebaseerde API's verwachten een HTTP header met de naam Authorization, met een waarde Bearer {{accesstoken}}

We kunnen dit herhalen voor elke extra stap die dezelfde access token vereist.