Multi-step monitoring authenticatie

Veel API’s vereisen dat de client inloggegevens verstrekt die de identiteit verifiëren en toegang verlenen. Veelgebruikte benaderingen zijn HTTP-authenticatieschema’s die in headers worden verzonden (Basic, NTLM of Digest), token-gebaseerde toegang (zoals OAuth 2.0, waarbij een access token wordt verkregen en vervolgens doorgaans in een Authorization header wordt verzonden), mutual TLS met een clientcertificaat of een combinatie van deze methoden.

In dit artikel worden de HTTP header- en token-gebaseerde authenticatie-opties in Uptrends besproken. Zie Clientcertificaatauthenticatie om te authenticeren met clientcertificaten.

Standaardtypes authenticatie

De sectie Authenticatie op het tabblad Request biedt verschillende manieren om inloggegevens te verzenden:

• Basic authentication
• NTLM (Windows) authentication
• Digest authentication
• Bearer authentication
• None — selecteer deze optie als de stap geen authenticatie vereist.

Basic authentication

Gebruikt een gebruikersnaam en wachtwoord voor authenticatie. Uptrends genereert automatisch de Authorization header. U hoeft deze header niet handmatig toe te voegen.

Uptrends kan eerst de API aanroepen zonder uw gebruikersnaam en wachtwoord te verzenden. Als authenticatie vereist is, weigert de server toegang en vraagt om Basic authentication. Dit scenario wordt een challenge genoemd: de server reageert met 401 Unauthorized en een WWW-Authenticate: Basic header.

Uptrends probeert de API call vervolgens opnieuw met uw gebruikersnaam en wachtwoord. Het combineert uw inloggegevens als username:password, codeert het resultaat met Base64 en verzendt dit in de Authorization header. Zelfs als Uptrends meerdere API calls uitvoert, telt dit nog steeds als één controleregelstap.

Opmerking

Als de server 403 Forbidden retourneert of een WWW-Authenticate: Basic header ontbreekt, retourneert de controleregel een fout. Voeg de header Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= handmatig toe aan de controleregelstap, zodat de inloggegevens zelfs zonder een correcte challenge worden doorgegeven. Zie het Basic authentication scheme (RFC 7617) voor het headerformaat.

NTLM (Windows) authentication

Gebruikt een Windows- of Active Directory-gebruikersnaam en wachtwoord voor authenticatie. Uptrends genereert automatisch de Authorization header. U hoeft deze header niet handmatig toe te voegen.

Uptrends kan eerst de API aanroepen zonder uw inloggegevens te verzenden. Als authenticatie vereist is, weigert de server toegang en vraagt om NTLM authentication. Dit scenario wordt een challenge genoemd: de server reageert met 401 Unauthorized en een WWW-Authenticate: NTLM header.

Uptrends kan vervolgens verschillende HTTP-requests verzenden om uw identiteit te verifiëren voordat de API call slaagt. Zelfs als Uptrends meerdere API calls uitvoert, telt dit nog steeds als één controleregelstap.

Opmerking

Als de server 403 Forbidden retourneert of een WWW-Authenticate: NTLM header ontbreekt, retourneert de controleregel een fout. In tegenstelling tot Basic authentication is er geen eenvoudige handmatige headeroplossing. Als uw account zich in een Windows-domein bevindt, voert u de gebruikersnaam in als YOURDOMAIN\username (bijvoorbeeld ACME\john).

Digest authentication

Gebruikt een gebruikersnaam en wachtwoord voor authenticatie. Uptrends genereert automatisch de Authorization header. U hoeft deze header niet handmatig toe te voegen.

Uptrends kan eerst de API aanroepen zonder uw inloggegevens te verzenden. Als authenticatie vereist is, weigert de server toegang en vraagt om Digest authentication. Dit scenario wordt een challenge genoemd: de server reageert met 401 Unauthorized en een WWW-Authenticate: Digest header.

Uptrends probeert de API call vervolgens opnieuw. Het berekent een op MD5 gebaseerde response op basis van de gebruikersnaam, het wachtwoord, de server challenge, requestmethode en URL, en verzendt deze in de Authorization header. Het wachtwoord zelf wordt nooit verzonden. Zelfs als Uptrends meerdere API calls uitvoert, telt dit nog steeds als één controleregelstap.

Opmerking

Als de server 403 Forbidden retourneert of een WWW-Authenticate: Digest header ontbreekt, retourneert de controleregel een fout. In tegenstelling tot Basic authentication is er geen eenvoudige handmatige headeroplossing.

Bearer authentication

Gebruikt een bearer token in plaats van een gebruikersnaam en wachtwoord. Uptrends voegt automatisch Authorization: Bearer <token> toe aan de API-request van die stap. U hoeft deze header niet handmatig toe te voegen. In tegenstelling tot andere authenticatietypes is er geen server challenge vereist.

Opmerking

Gebruik Bearer authentication wanneer u al een token heeft. Gebruik Custom authentication (OAuth) wanneer u eerst een token moet verkrijgen, of wanneer het token afkomstig is uit de response van een vorige stap.

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.

U kunt ook vault-items gebruiken voor inloggegevens.

Zie Multi-step API-variabelen voor instructies over het gebruik van voorgedefinieerde variabelen.

Aangepaste authenticatie (inclusief OAuth)

Opmerking

Gebruik Bearer authentication wanneer u al een token heeft. Gebruik custom authentication (OAuth) wanneer u eerst een token moet verkrijgen of wanneer een token afkomstig is uit de response van een vorige stap.

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

Als u geen OAuth gebruikt, maar een ander protocol, werkt het mogelijk nog steeds op een vergelijkbare manier: u moet eerst logininformatie opgeven die uw identiteit aan de API “bewijst”. De API-server reageert dan door u een logintoken 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 logintoken gebruiken om toegang te krijgen.

OAuth 2.0-authenticatie instellen

In het volgende voorbeeld stellen we een eenvoudige vorm van OAuth 2.0-authenticatie in. Ons doel is om een access token te verkrijgen van de API, dat we vervolgens in latere requests kunnen gebruiken.

Hiervoor sturen we eerst een request die de juiste OAuth-velden bevat. In dit geval vragen we toegang op basis van een autorisatiecode, een client id en een client secret. De client id en client secret zijn vaste waarden die we als voorgedefinieerde variabelen kunnen definiëren. In onze eenvoudige set-up is de autorisatiecode ook een vaste waarde, maar in uw set-up 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 een request naar onze API instellen door verwijzingen naar die variabelen op te nemen, samen met andere parameters die de API verwacht. Voeg in de eerste stap van onze multi-step set-up 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 access token bevat dat we nodig hebben, maar hoe wordt die datastructuur geformatteerd? Om ervoor te zorgen dat we data 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 response 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 vastleggen in de JSON response. Om dit te doen maken we een nieuwe variabele op het tabblad Response van onze stap:

• De response 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 JSON-expressie simpelweg 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 deze ook al enige monitoring uit: als de API op dit punt een fout retourneert, of als de response geen access token bevat, detecteert deze stap dit en rapporteert een fout.

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 doorgeven dat we zojuist hebben vastgelegd. Op OAuth 2.0 gebaseerde API’s verwachten een HTTP header met de naam Authorization, met de waarde Bearer {{accesstoken}}

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