Dit is een handleiding om Authentik te configureren als Identity Provider (IdP) in SURFconext.

Voor deze handleiding gaan we ervan uit dat je:

• Authentik geïnstalleerd hebt.

• Gebruikers in Authentik bestaan.

• Er een SAML-koppeling met SURFconext moet worden ingericht.

Inleiding

In deze handleiding configureren we:

1. Een SAML Provider in Authentik om met SURFconext te koppelen. 

2. De SAML endpoints en metadata van SURFconext in Authentik. 

3. Een Claim / Attribute Mapping zodat SURFconext de juiste attributen ontvangt. 

4. Het doorgeven van de IdP metadata link uit Authentik voor registratie in SURFconext. 

SURFconext is een Service Provider Proxy en daarom configureer je SURFconext als Service Provider (SP) in Authentik. 

SURFconext metadata

Authentik moet SURFconext kunnen vinden. De metadata die nodig is om de IdP te configureren staat hieronder. Gebruik hiervoor de SURFconext SP-proxy metadata van de opgegeven locaties. Bedenk voordat je verder gaat of je aan onze testomgeving of aan onze productieomgeving wilt koppelen. Neem contact met ons op als je niet zeker weet welke je moet gebruiken. 

Deze waarden heb je dadelijk nodig voor het configureren van de SAML provider in Authentik. Houd deze dus bij de hand. 

SAML Provider aanmaken in Authentik

Open de Authentik Admin Interface. Ga vervolgens naar:

• Applications → Providers → Create

En kies:

• Provider Type: SAML-provider
   

Vul vervolgens de gegevens van SURFconext in, zoals hieronder aangegeven. In het voorbeeld hieronder wordt dus aan onze testomgeving gekoppeld. 

Authentication Flow

De Authentication Flow bepaalt hoe Authentik een gebruiker authenticeert voordat er een SAML assertion wordt uitgegeven aan SURFconext. Een flow bestaat uit een reeks stappen zoals een gebruikersnaam en wachtwoord invoeren, multi-factor authenticatie (MFA) en controle op accountstatus of policies. 

Wanneer een gebruiker via SAML probeert in te loggen, doorloopt de gebruiker eerst deze flow. Pas nadat de authenticatie succesvol is afgerond, genereert Authentik een SAML assertion en stuurt deze naar de Service Provider. Je hebt de keuze uit een explicit en implicit consent authentication flow. 

Wij raden de default-provider-authentication-implicit-consent aan. Dit is een flow waarbij de gebruiker niet expliciet toestemming hoeft te geven voor het delen van attributen met SURFconext. Dit mechanisme kent SURFconext ook al en maakt dat gebruikers zodoende niet dubbel consent hoeven te geven om aan te melden.  Authenticatie gebeurt direct, waarop de SAML response verstuurd. 

ACS URL (Assertion Consumer Service URL)

De ACS URL is het endpoint van de Service Provider Proxy die SURFconext is, waar de SAML assertion naartoe wordt gestuurd nadat een gebruiker succesvol is geauthenticeerd. De Identity Provider stuurt de SAML response via de browser van de gebruiker naar deze URL, waar SURFconext de login verwerkt.

Issuer (EntityID IdP)

De Issuer (ook wel EntityID) is de unieke identifier van jouw Identity Provider in de federatie van SURFconext. Deze waarde is uniek in SURFconext en wordt gebruikt door SURFconext om te bepalen voor welke Identity Provider de SAML assertion bedoeld is.

Audience

De Audience geeft aan welke partij de SAML assertion mag gebruiken. Dit is dezelfde waarde als het EntityID van SURFconext. Wij zijn een Service Provider voor een IdP en controleren deze waarde om te zorgen dat we alleen assertions verwerken die voor SURFconext bedoeld zijn. 

Basis configuratie

Advanced SAML protocol instellingen

Vul onder advanced protocol settings in ieder geval het volgende in. 

SURFconext verwacht dat assertions ondertekend zijn. Het ondertekenen van SAML assertions zorgt ervoor dat SURFconext kan controleren dat de assertion daadwerkelijk van jouw Identity Provider komt en niet onderweg is aangepast. Daarom moet je sign assertions aan zetten. 

Application koppelen

Na het maken van de Provider moet daar een Application aan gekoppeld worden. Ga naar:

• Applications → Create
   

We gaan nu de SURFconext applicatie in Authentik maken. 

Afhankelijk van jouw configuratie kun je hier ook groepen definieren die gebruik mogen maken van de SURFconext Applicatie in Authentik. Als je dit hebt gedaan, kunnen gebruikers via Authentik gebruik kunnen maken van de applicatie 'SURFconext' en dus inloggen op gekoppelde applicaties in SURFconext.

Attribute / Claim Mapping maken

SURFconext verwacht SAML attributen in de assertion. Daarom moet er een Property Mapping worden gemaakt. Dit komt er op neer dat gebruikerskenmerken worden gemapped op attributen die SURFconext herkent. Kijk op onze attributenpagina voor een compleet overzicht.  

Ga naar:

• Customization → Property Mappings → Create 

Type:

• SAML Provider Property Mapping
   

Naam:

• Surname (bijvoorbeeld) 

Herhaal voor alle attributen aangegeven op onze attributen wiki en vul deze zo volledig mogelijk. We hebben een overizcht van minimaal vereiste attributen om SURFconext betrouwbaar te laten werken. Zonder uid en schacHomeOrganization werkt SURFconext in zijn geheel niet, deze zijn verplicht voor elke login. 

Stuur ons de metadata

Tot slot van deze handleiding: Stuur ons een mail (support@surfconext.nl) met daarin de metadata URL van jouw Authentik IdP. Ga daarvoor naar: 

• Applications → Providers → SURFconext
• Klik op 'Copy download URL' en stuur deze link naar support@surfconext.nl. Geef daarbij aan of je op onze test- of productieomgeving wilt koppelen.

Als je bevestiging hebt gehad dat wij de IdP hebben opgevoerd kun je de login en de attributen die je naar SURFconext stuurt testen op onze debugpagina (test, productie).