Beveiliging

Credentials

• door middel van het zetten van een authorization header.
• door middel van het aanroepen van de login method.

Het zetten van een authorization header heeft hierbij de voorkeur, zie voorbeeld hieronder:

using (HttpClient client = new HttpClient())
{ 
  // set Authorization header 
  client.DefaultRequestHeaders.Authorization = 
    new System.Net.Http.Headers.AuthenticationHeaderValue("Basic",
      Convert.ToBase64String(Encoding.ASCII.GetBytes($"{options.Username}:{options.Password}"))
  );
  
  // call any method(s) ...
}

Het gebruiken van de login method kan op de volgende manier:

using (HttpClient client = new HttpClient())
{
  string qs = $"username={options.Username}&password={options.Password}";
  string requestUrl = $"{options.Url}/login?{qs}";
  var response = await client.GetAsync(requestUrl);
  if (response.IsSuccessStatusCode)
  { 
    // call any method(s) ... 
  }
}

(Beide voorbeelden: C#, .NET 5.0, bijvoorbeeld vanuit een console application. In deze voorbeelden is options een configuratie class.)

Url toegang 

Standaard is de WebAPI alleen toegankelijk via een localhost adres, zodat deze voor (bijvoorbeeld) de webapi macro prima bereikbaar is (vanuit de rendering) maar van buitenaf niet zomaar aangeroepen kan worden. In sommige scenario's kan het echter wenselijk danwel noodzakelijk zijn om de WebAPI ook van buitenaf benaderbaar te maken.

Om dit mogelijk te maken kan de app setting webapi.localhostonly toegevoegd worden aan de appSettings in de web.config van de manager (WWWMgr\web.config dus) met de waarde false. Default is deze instelling dus true.

mgr-WebApiAccess privilege

Standaard moet het opgegeven account ook via één van zijn/haar rollen het privilege mgr-WebApiAccess gekoppeld hebben. Met uitzondering van (het aanroepen van) de cmsupdate methode, vanwege backwards compatibiliteit.

Indien gewenst kan deze privilege check uitgeschakeld worden via de app setting webapi.useprivilege. (Eveneens dus via de appSettings in de WWWMgr\web.config. App settting toevoegen met de waarde false.)

Overigens, één van zijn/haar rollen geldt ook voor andere beveiligings- en toegangchecks. Binnen de manager kan een gebruiker een specifieke rol selecteren, voor zover van toepassing. Binnen de WebAPI wordt voor dit soort checks altijd naar alle rollen gekeken, waaraan de gebruiker is gekoppeld. Als één van de rollen toegang heeft en/of "iets" mag, dan kan de onderliggende functionaliteit uitgevoerd worden door de WebAPI.

Methods

Hieronder een beknopt overzicht van welke methodes er beschikbaar zijn binnen de WebAPI.

In principe zullen alle methods een status code 200 teruggeven, tenzij er een fout optreedt. In dat geval wordt er een status code 500 (internal server error) teruggegeven en wordt de foutmelding als response content terug gestuurd. Afhankelijk van de instelling binnen IIS wat betreft custom errors afhandeling (customErrors element) is deze dan wel of niet beschikbaar op de client.

Een item aanmaken

Een item opvragen

Een item bijwerken