ADFS inrichten

De beheer omgeving (het dashboard) van de Formulierenserver ondersteunt ook inloggen via Microsoft ADFS, mits geconfigureerd voor een specifieke klant. De benodigde configuratie en een korte uitleg over de authenticatie flow wordt in dit artikel uiteengezet.

ADFS

In plaats van "gewoon" in te loggen met gebruikersnaam en wachtwoord, biedt de Formulierenserver ook de mogelijkheid om in te loggen via ADFS. Hierbij wordt de term ADFS min of meer als verzamelnaam gebruikt, want de basis van deze inlog-voorziening maakt gebruik van WS-Federation. Dit is compatibel met o.a. Microsoft Active Directory Federation Services en Azure Active Directory.

Omdat de formulierenserver een multi-tenant omgeving is, zal de gebruiker op een tussenscherm eerst z'n email adres moeten ingeven. Op basis van het domein van het opgegeven email adres en de ADFS configuratie(s) (waarover later meer) kan bepaald worden voor welke tenant (klant) de gebruiker wil inloggen via ADFS.

Vanuit de klant configuratie kan vervolgens bepaald worden naar welke omgeving de gebruiker geredirect moet worden om in te loggen. Na inloggen wordt de gebruiker terug geredirect naar het dashboard van de Formulierenserver. De OWIN middleware laag die we gebruiken construeert op basis van de response data die wordt meegestuurd een Claims Identity, wat gezien kan worden als een verzameling claims. Deze set van claims zijn vervolgens bepalend voor het voltooien van de inlog procedure.

Configuratie

Om via ADFS te kunnen inloggen voor een specifieke klant, dient de configuratie xml voor deze klant aangepast te worden en moet er een adfs element toegevoegd worden.

XML CopyCode image Copy Code
<adfs enabled="true">
  <tenantid>{tenantid}</tenantid>
  <domain>seneca.nl</domain>
  <metadata>https://login.microsoftonline.com/{tenantid}/federationmetadata/2007-06/federationmetadata.xml</metadata>
  <wtrealm>{identifier}</wtrealm>
  <identifierclaim>http://schemas.microsoft.com/identity/claims/objectidentifier</identifierclaim>
  <fallbackidentifierclaim>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</fallbackidentifierclaim>
  <tenantidclaim>http://schemas.microsoft.com/identity/claims/tenantid</tenantidclaim>
  <verifyclaims>
    <claim name="http://schemas.microsoft.com/identity/claims/tenantid">{tenantid}</claim>
  </verifyclaims>
  <addnonexistingusers>true</addnonexistingusers>
  <user.mappings>
    <property name="username" claimtype="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
    <property name="email" claimtype="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" />
    <property name="fullname" claimtype="http://schemas.microsoft.com/identity/claims/displayname" />
    <property name="externalid" claimtype="http://schemas.microsoft.com/identity/claims/objectidentifier" />
  </user.mappings>
  <sfsroles.mappings claimtype="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
    <sfsrole guid="" claimvalue="" />
    <!-- guid is een verwijzing naar de guid van een SfsRole, claimvalue is de waarde van een claim -->
  </sfsroles.mappings>
</adfs>

De elementen binnen deze configuratie worden hieronder besproken. In principe zijn alle genoemde elementen verplicht en moeten dus opgenomen worden in de xml.

tenantid

In dit element moet de tenant id (identifier) gespecificeerd worden. Deze waarde wordt gebruikt om de juiste klant te koppelen na inloggen van de gebruiker, door de klant op te zoeken waarvan de tenantid overeenkomt met de waarde van de tenantidclaim.

domain

Hier moet het domein gespecificeerd worden waarvoor de inlog koppeling moet gelden. Gebruikers moeten dus wel een email adres hebben op dit domein. In het inlog proces wordt het domein element gebruikt om de klant configuratie op te sporen die hoort bij het door de gebruiker opgegeven email adres.

metadata

In dit element moet een url gespecificeerd worden waarop de (federation) metadata configuratie voor de inlog koppeling beschikbaar is.

wtrealm

Dit element wordt gebruikt om de (relying party trust) identifier / application id / client id van de koppeling te specificeren.

identifierclaim

Hierin kan gespecificeerd worden welke claim als identificatie van de gebruiker gebruikt moet worden. Nadat een gebruiker via de externe login koppeling is ingelogd en er een Claims Identity is opgebouwd, wordt de hier gespecificeerde claim gebruikt om de bijbehorende gebruiker binnen de Formulierenserver op te zoeken door een match op basis van de waarde van deze claim en het External id (AdfsId) veld.
Default waarde: http://schemas.microsoft.com/identity/claims/objectidentifier.

Als er geen match gevonden wordt, wordt de fallbackidentifierclaim gebruikt om alsnog een bijbehorende gebruiker te vinden. Mocht er dan nog geen gebruiker gevonden zijn en de optie addnonexistingusers staat aan, wordt er binnen de Formulierenserver een nieuwe gebruiker aangemaakt.

Vervolgens worden de gegevens van deze gebruiker bijgewerkt op basis van de claim/property mappings in het user.mappings element. Bij een volgende keer inloggen zal dan wel direct een match gevonden worden op basis van de identifierclaim.

fallbackidentifierclaim

Het fallbackidentifierclaim element wordt (dus) gebruikt om een claim te specificeren welke gebruikt dient te worden om een bijbehorende gebruiker binnen de Formulierenserver te vinden, als dit niet is gelukt op basis van de identifierclaim. Hiervoor wordt het email adres gebruikt, dus de gespecificeerde claim moet ook een email adres bevatten.
Default waarde: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress.

tenantidclaim

De tenantidclaim wordt gebruikt om een gebruiker te koppelen aan één of meerdere klant(en) / tenant(s) binnen de Formulierenserver. Dit speelt voornamelijk een rol wanneer een gebruiker nog niet bestaat. Anderzijds, als de Claims Identity meerdere tenantid claims bevat, zal de gebruiker zonodig ook gekoppeld worden aan de klant(en) / tenant(s) die een overeenkomstige waarde hebben in het tenantid element.
Default waarde: http://schemas.microsoft.com/identity/claims/tenantid.

verifyclaims

In dit element kunnen één of meerdere claim verificatie rules worden opgenomen. Na inloggen zal de Claims Identity geverifieerd worden op basis van deze rules. Als één van de gespecificeerde claims niet voorkomt of de waarde ervan niet overeenkomt met de gespecificeerde waarde, zal de inlog falen en wordt de gebruiker geredirect naar een LoginFailed pagina.

Ieder rule bestaat uit een claim element met een name attribuut, die de naam/claimtype van de claim die gecontroleerd moet worden specificeert. De waarde van het element is dan de waarde die de claim ook zou moeten bevatten.

addnonexistingusers

Als na het inloggen van een gebruiker via de externe koppeling er geen match gevonden kan worden met een bestaande gebruiker binnen de Formulierenserver (op basis van de identifierclaim of de fallbackidentifierclaim), wordt voorzien in de optie om op dat moment een nieuwe gebruiker aan te maken. Voeg dit element met de waarde true toe aan de configuratie om deze optie in te schakelen. De gebruikersnaam, volledige naam, email adres en de external id voor de nieuw aan te maken gebruiker worden bepaald op basis van de claim mappings in het user.mappings element.

user.mappings

Het user.mappings element is een verplicht element, waarin de mapping van claims naar eigenschappen van de gebruiker wordt vastgelegd. Voor de volgende vier eigenschappen dient er een property element toegevoegd te worden: username, fullname, email, externalid. De bijbehorende claim die moet worden gebruikt dient gespecificeerd te worden middels een claimtype attribuut.

sfsroles.mappings

Via het optionele sfsroles.mappings element kan een mapping vastgelegd worden tussen één of meerdere claims en de gebruikersrollen binnen de Formulierenserver waaraan een gebruiker gekoppeld moet worden. Indien dit element bestaat, worden de gebruikersrollen waaraan een gebruiker is gekoppeld altijd overschreven op basis van de mappings in dit element en de claims die vanuit de externe login provider worden doorgegeven.

Het claimtype attribuut op het sfsroles.mappings element bepaald welke claim gebruikt dient te worden. Vervolgens worden de gebruikersrollen mappings vastgelegd door een set van sfsrole elementen.
Elk sfsrole element dient twee attributen te hebben, namelijk guid en claimvalue. Het guid attribuut dient te verwijzen naar de guid van een gebruikersrol. Het claimvalue attribuut legt de waarde vast van een claim die moet voorkomen, om de gebruiker aan deze gebruikersrol te koppelen.

De volgende vooraf gedefinieerde gebruikersrollen zijn beschikbaar:

Guid  Naam 
 B864EB70-9873-40AE-8B3B-770B30E7A43B  Formulieren beheer
 AAFFCB5A-6D30-4262-B29C-F9BC1365BF56  Producten beheer
 BBA14DD5-CFA4-43D4-AB39-9E40150C1B60  Systeem admin
 A39A6E54-7721-4BB2-952E-07CD15F05457  UDC beheer
 FAA5E7E1-1885-4E73-8C96-DFF8CA32B033  Webservices admin
 9957D0C7-6402-41EC-AE16-09EA05671919  Webservices editor

 In het geval van Azure AD zouden vervolgens binnen Aure AD groepen aangemaakt kunnen worden:

 De mappings voor de gebruikersrollen zou er dan als volgt uit zien:

XML CopyCode image Copy Code
<sfsroles.mappings claimtype="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"><sfsroles.mappings claimtype="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups">
 <sfsrole guid="B864EB70-9873-40AE-8B3B-770B30E7A43B" claimvalue="db83e2bc-33de-43dc-bfe4-ffc6c4300a67" name="Formulieren Beheer" />
 <sfsrole guid="AAFFCB5A-6D30-4262-B29C-F9BC1365BF56" claimvalue="482233ef-388a-4d6a-97d9-dd4cdd0ffaa9" name="Producten Beheer" /> 
 <sfsrole guid="FAA5E7E1-1885-4E73-8C96-DFF8CA32B033" claimvalue="82d189fa-8b17-4b09-9b6f-ef225920f633" name="Webservices administrator" />
 <!-- mappings voor overige gebruikersrollen ...  -->
</sfsroles.mappings>

(Het name attribuut wordt niet gebruikt, maar is toegevoegd in dit voorbeeld om duidelijk te maken welke mapping voor welke rol geldt.)

 In Azure AD dienen de gebruikers vervolgens aan de juiste groepen gekoppeld te worden.