Met jouw hulp kunnen we onze documentatie verder verbeteren. Kom je zaken tegen in deze handleiding die niet kloppen of verduidelijking behoeven? Laat het ons weten via support@surfconext.nl |
Via de SURFconext-infrastructuur voor online samenwerking beschikken gebruikers over diensten van verschillende leveranciers, die ze in één omgeving kunnen toepassen. Dit biedt nieuwe samenwerkingsmogelijkheden, binnen instellingen en over instellingsgrenzen heen. Deze handleiding beschrijft hoe een instelling die op SURFnet is aangesloten, met behulp van NetIQ Access Manager (NAM) kan aansluiten op SURFconext. Voor het lezen van deze handleiding is enige kennis van federatief identity management een pre. Een lijst van nuttige documenten:
We beschrijven in deze handleiding twee gevallen:
Houd er rekening mee dat de metadata en de metadata locaties die gebruikt worden voor de test- en productieomgevingen van SURFconext verschillen. Gebruik ze als volgt: |
NetIQ Access Manager levert gebruikers veilige toegang tot interne en externe (web) applicaties. Algemene informatie over dit product vindt u hier. Technische informatie is hier te vinden.
Access Manager levert de functionaliteiten die te zijn is in de onderstaande figuur:
De Identity Servers biedt centrale authenticatie- en identity informatie voor alle applicaties. Dit gebeurt op basis van één of meerdere directories (NetIQ eDirectory, Active Directory of een LDAP server) waarin deze informatie is opgeslagen. Verder kunnen aan een Identity Server IdPs en SPs worden gekoppeld. Voor SURFconext zijn dit een SAML 2.0 IdP en SP. Hierbij dienen ook attribute sets te worden aangemaakt, waarin gedefinieerd wordt welke gegevens (attributen) van de IdP naar de SP (of van SP naar IdP) worden overgestuurd in de SAML communicatie. Het gaat dan onder meer om naam en e-mailadres van de betreffende gebruiker die wil inloggen. De attributen moeten conform de afspraken binnen SURFconext worden aangeleverd, dat wil zeggen met de juiste attribuutnaam en de juiste afspraken voor de waarde. Deze zijn voor SURFconext gedefinieerd op deze pagina. De hier gedefinieerde informatie moet passen op de attributen die NetIQ Access Manager kent. Dat is vaak niet vanzelf zo en daarom dient er voor de attribute sets ook een attribute mapping te worden gemaakt. Bij het aanmaken gebeurt dit tegelijk.
De Access Gateway is een zogenaamde 'reverse proxy', die tussen de gebruiker en de web applicatie staat en levert dan single sign-on en/of gedifferentieerde toegang (autorisatie). Toegang wordt geweigerd of verleend op basis van policies die gekoppeld zijn aan de web applicaties. Toegang kan worden verleend op basis van de rol die een gebruiker binnen de organisatie heeft. Bijvoorbeeld op basis van groepslidmaatschap of bepaalde attributen, die de Identity Server aanlevert.
De Access Gateway heeft als voordeel boven andere single sign-on en autorisatie-oplossingen dat er geen additionele software op de webserver hoeft te worden geïnstalleerd. Technisch gezien vertaalt de Access Gateway de authenticatie en autorisaties uit Identity Server naar standaard HTTP headers, waarmee de meeste web applicaties overweg kunnen. Het is tevens mogelijk om authenticatie naar achterliggende systemen op basis van web formulieren (naam en wachtwoord op de web pagina) te automatiseren.
SSL VPN biedt beveiligde toegang tot wel of niet webgebaseerde diensten op basis van HTTPS. Hierbij kan ook met een user certificaat worden gewerkt als extra authenticatiemiddel.
Access Manager biedt IBM WebSphere, BEA WebLogic en JBoss agents die autorisatie en toegang bieden tot servlets en Enterprise JavaBeans (EJBs). Deze agents gebruiken Java Authentication and Authorization Service (JAAS), Java Authorization Contract voor Containers (JACC) en interne Web-server APIs voor authenticatie. Tezamen leveren zij granulaire, policy- gebaseerde autorisatie en toegang tot servlets en EJBs.
Policies worden gebruikt om de autorisaties voor gebruikers te bepalen. Ze bepalen bijvoorbeeld of iemand een web server mag bereiken op basis van IP-adres, de methode van authenticatie of de rol van de betreffende persoon.
In dit document beschrijven we hoe NetIQ Access Manager 3.2 als IdP of SP kan dienen voor SURFconext. Daarvoor hebben we de SSL-VPN en JAVA agent functionaliteiten niet nodig. De Acess Gateway en Policies hebben we alleen nodig voor de configuratie van NetIQ Access Manager als SP, omdat we daarbij ook een achterliggende web service ontsluiten.
Om als IdP te koppelen moet in NetIQ Access Manager het volgende gebeuren:
Om een applicatie te koppelen waarvoor NetIQ Access Manager als SP kan fungeren, zetten we eerst een test webapplicatie op.
Daarna zijn de volgende stappen nodig:
Ga naar ‘Devices/Identity Servers/IDP-cluster’ en ga naar de tab ‘Local’ en klik onder ‘User Stores’ op ‘new’. Dat ziet er uit als in de onderstaande afbeelding:
Vul de juiste gegevens in (in ons geval een eDirectory server van de organisatie ‘m7’) en klik op ‘Finish’. Merk op dat we een eDirectory replica en een search context (de plek in de directory information tree waaronder iedereen zich bevindt die SURFconext moet kunnen gebruiken; hier kunnen er meerdere van worden opgegeven) hebben gedefinieerd.
Een belangrijke stap die niet vergeten mag worden is nu het updaten van de configuratie onder ‘Devices/Identity Servers’. Zie de onderstaande afbeelding. Deze actie onderbreekt de services van Access Manager niet. Maar hij kan ook pas uitgevoerd worden nadat alle wijzigingen zijn aangebracht.
Ga naar ‘Devices/Identity Servers/IDP-cluster’. Zorg dat in de tab ‘General’ onder ‘Configuration’ onderaan het vinkje bij SAML 2.0 is aangezet. Ga nu naar de tab ‘SAML 2.0’. Kies nu ‘new’ en dan ‘Service Provider’ (zie onderstaande figuur).
Hiermee gaan we SURFconext als SP toevoegen door de metadata URL op te geven. Zie de figuur hieronder. De metadata URL is https://metadata.surfconext.nl/idp-metadata.xml.
Let op: controleer de URL eerst in een browser en controleer ook het SSL certificaat bij de URL (de browser geeft dit aan als u op het slotje klikt). Dit is belangrijk omdat in een later stadium u de metadata van SURFconext gaat gebruiken om een trust-relatie met SURFconext op te zetten.
Klik nu op ‘Next’. Dan krijgen we (als het goed is) het volgende te zien:
Neem contact op met SURFnet als deze stap mislukt. Als het gelukt is, klik dan op ‘Finish’.
Daarna ziet u het volgende scherm:
Update wederom de clusterconfiguratie zoals hierboven beschreven, of wacht daarmee tot de attributen geconfigureerd zijn (zie onder).
SURFnet gebruikt bij SURFconext zogenaamde self signed certificates voor het ondertekenen van de SAML 2.0 berichten. Self signed certificates bieden voldoende garantie omdat SURFconext geen publieke dienst is.
Ga naar ‘Devices/Identity Servers/IDP-cluster’. Ga naar de tab ‘SAML 2.0’. Klik op de zojuist aangemaakte SP (SURFconext genoemd in ons voorbeeld). Klik nu op de tab ‘Metadata’ en zoek het signing certificate. Zie de figuur hieronder.
Selecteer en kopieer het singing certificate (zoals in de figuur). Ga nu naar ‘Security/Trusted Roots’ en klik op ‘import’. U krijgt dan het onderstaande scherm te zien (dat in ons voorbeeld reeds is ingevuld):
Geef het certificaat een beschrijvende naam (hier dus ‘SURFconext token signing’) en selecteer ‘Certificate data text’ en plak hierin het gekopieerde certificaat. Let op: U bent niet klaar, want in de regel boven het certificaat moet staan '--BEGIN CERTIFICATE--' en in de regel onder het certificaat (niet in beeld in de figuur) '--END CERTIFICATE----'. Hiermee creëren we een geldig PEM certificaat, zoals NetIQ Access Manager het graag ziet.
Klik op ‘OK’. Als alles goed is gegaan ziet u het onderstaande scherm:
Controleer of op de volgende URL inderdaad een geldige XML laat zien:
https://<servernaam>/nidp/saml2/metadata |
Dit is metadata van de IdP en bevat alle informatie die nodig is om de IdP aan SURFconext toe te voegen.
Deze URL dient ook voor SURFnet benaderbaar te zijn. |
Geef deze URL aan SURFnet door (mail naar support@surfconext.nl) en wacht op bericht waarin SURFnet aangeeft dat de metadata is geconfigureerd. U kunt intussen wel verder met de overige stappen, behalve de laatste controle.
Ga naar ‘Devices/Identity Servers/IDP-cluster’. Ga naar de tab ‘SAML 2.0’. Klik op de zojuist aangemaakte SP (SURFconext in ons voorbeeld). Klik onder de tab ‘Configuration’ op ‘attributes’ en kies bij het uitrolmenu ‘attribute set’ voor ‘<New Attribute Set>’. Zie hieronder in de figuur:
Vervolgens gaan we een nieuwe attribute set aanmaken. Zie de volgende figuur:
Klik op ‘Next’ en vervolgens in het volgende scherm op ‘New’.
Voor SURFconext zijn conform de metadata de volgende attributen verplicht:
urn:mace:dir:attribute-def:mail
urn:mace:dir:attribute-def:displayName
urn:mace:dir:attribute-def:sn
urn:mace:dir:attribute-def:givenName
urn:mace:terena.org:attribute-def:schacHomeOrganization
urn:mace:dir:attribute-def:uid
De betekenis van deze attributen is te vinden op de attributenschema pagina van SURFnet: https://wiki.surfnetlabs.nl/display/surfconextdev/Attributes+in+SURFconext
We zullen in deze handleiding alleen de eerste mapping maken.
In het scherm dat we nu te zien krijgen (zie hieronder) kiezen we de local attribute waarde. Let op dat voor de meeste attributen een naam die in LDAP voorkomt gekozen moet worden (aangegeven met ‘LDAP Attribute:’).
Vul voor ‘remote attribute’ de volledige urn in zoals gespecificeerd op de SURFnet attributenschema pagina.
Klik op ‘OK’ en herhaal dit voor de overige attributen. Let erop dat u de attributen mapping zorgvuldig en correct kiest. Dus het locale attribuut bij ‘urn:mace:dir:attribute-def:mail’ moet voor iedereen daadwerkelijk wijzen naar een geldig e-mailadres. Verder merken we nog op dat voor schacHomeOrganization we een ‘Constant’ moeten kiezen met als waarde de domeinnaam van de IdP. In ons geval ‘m-7.nl’.
Let er verder op dat bij een standaard installatie van eDirectory die wordt gebruikt als User Store meestal niet ‘uid’ wordt gebruikt als inlognaam maar ‘cn’. Wij mappen dan ook het LDAP attribuut ‘cn’ op urn:mace:dir:attribute-def:uid.
In onze situatie krijgen we uiteindelijk het volgende te zien:
Als we nu op ‘Next’ klikken, kunnen we kiezen welke attributen uit de set we willen gebruiken voor deze SURFconext SP. Zie de figuur hieronder:
In bovenstaand voorbeeld moeten alle attributen links komen te staan (bij ‘Send with authentication’).
Uiteindelijk updaten we de clusterconfiguratie onder ‘Devices/Identity Servers’. Vergeet deze stap niet!
Er is bekend dat er compatibiliteitsproblemen zijn tussen NetIQ AM als IdP en SPs welke werken met Microsoft (.Net). Deze problemen worden veroorzaakt door het anders interpreteren van de SAML2.0 specificatie. Volgens Microsoft kan een URI alleen een absolutie URI (zie wikipedia voor uitleg over URIs) zijn terwijl NetIQ AM ook gebruik maakt van URI verwijzingen (zoals ook mogelijk is volgens de SAML2.0 en XSD specificatie). Om deze problemen voor te zijn adviseren wij om het authenticatie contract van de NetIQ AM IdP aan te passen.
Het aanpassen van authenticatie contract voor het aanpassen van een URI-verwijzing naar een absolute URI kunnen de volgende stappen uitgevoerd worden:
Ga naar ‘Devices/Identity Servers/IDP-cluster’ en ga naar de tab ‘Local’ en klik onder 'Contracts’ op ‘new’.
Vul de gegevens in als onderstaand plaatje:
Vergeet niet de Method 'Name/Password - Form' aan te klikken en vervolgens op de 
te klikken.
Klik op 'Next'
Vul bij Text in: Name/Password - Form URI
Selecteer image: Form Auth Username Password
Klik op 'Finish'
Stel nu deze nieuwe Authenticatie Contract in als de Default Authenticatie Contract.
Ga naar tab: 'Defaults'
Selecteer bij Authentication Contract de nieuwe 'Name/Password - Form URI' contract.
Klik op 'OK'
Uiteindelijk updaten we de clusterconfiguratie onder ‘Devices/Identity Servers’. Vergeet deze stap niet!
Nadat u van SURFnet bevestiging heeft ontvangen dat uw metadata is toegevoegd, kunt u uw nieuwe IdP gaan testen op een test SP. Hiervoor heeft SURFnet de volgende URLs beschikbaar:
https://engine.surfconext.nl/authentication/sp/debug
U heeft een test-koppeling zolang u de bijlage bij het SURFnet contract voor SURFconext nog niet ondertekend terug gestuurd heeft naar SURFnet. Daarna heeft u automatisch een productiekoppeling.
Om als SP te kunnen koppelen hebben we een applicatie nodig die we gaan aanbieden op SURFconext. Deze applicatie moet vanaf NetIQ Access Manager via een URL bereikbaar zijn. In ons voorbeeld heeft de applicatie de URL http://namsp/ en is bereikbaar op (private) IP-adres 192.168.168.5.
Let op dat de hier vermelde instructies zeer specifiek zijn voor een bepaalde (test)situatie. U zult dus zelf moeten nagaan waar uw situatie afwijkt. We raden u aan een expert in te schakelen als u denkt zelf onvoldoende ervaring te hebben.
We gaan nu SURFconext als IdP toevoegen. Ga naar ‘Devices/Identity Servers/IDP-cluster’. Ga naar de tab ‘SAML 2.0’. Klik nu op ‘New’ en kies voor ‘Identity Provider’. Zie de figuur hieronder:
Vervolgens vullen we een naam en de volgende metadata URL in:
https://metadata.surfconext.nl/idp-metadata.xml
Klik nu op ‘Next’. U krijgt het volgende te zien als alles is goed gegaan:
Klik nu op ‘Next’. Nu gaan we een inlog ‘card’ aanmaken. In het volgende scherm vullen we bij ID ‘SURFconext’ in en kiezen we een afbeelding bij ‘Image’. Er zijn er een aantal standaard aanwezig en we kunnen er ook zelf één uploaden. We voegen geen ‘Authentication contracts’ aan ‘Satisfies contract’ toe vanuit de ‘Available contracts’.
Nu klikken we op ‘Finish’.
Klik nu op SURFconext onder Identity Provider in het IDP overzichtsscherm (‘Devices/Identity Servers/IDP-cluster’). Klik op de tab ‘Authentication Card’ en kies vervolgens ‘Authentication Request’. Selecteer hier onder ‘Name Identifier Format’ voor ‘Transient’.
Ga nu terug naar de tab ‘Configuration’ en selecteer ‘Attributes’. Kies de SURFconext attribute set die eerder is aangemaakt bij het toevoegen van NetIQ Access Manager als IdP hierboven. En kies daarna alle attributen om ze als beschikbaar toe te voegen (zie hierboven).
Ga nu naar ‘User Identification’ en zorg dat daar ‘Attribute matching’ niet is aangeklikt. Dit zorgt ervoor dat de federatief geauthenticeerde gebruiker niet tegen de lokale directory gematched zal worden.
Ga naar ‘Devices/Access Gateways/AG-Cluster/NAM-RP’. Dan komen we op het volgende scherm:
Klik op ‘New’ en vul de gegevens in zoals hieronder:
Geef de reverse proxy een naam (hier ‘Test-SP’). Deze naam is alleen maar een beschrijving in de configuratie. Hier kiezen we voor een ‘Path-Based’ reverse proxy. Dat betekent dat de dienst onder dezelfde hostnaam als de NetIQ Access Manager beschikbaar is op internet. Als dat anders moet, dan kunt u hier ook voor ‘Domain Based’ kiezen.
De ‘Published DNS Name’ is hier de hostnaam van de NetIQ Access Manager en al voor ons ingevuld en kan niet aangepast worden.
Het ‘Web Server IP Address’ is het IP-adres waarop de NetIQ Access Manager reverse proxy de dienst die we gaan beschikbaar stellen kan bereiken.
Het ‘Path’ veld is in dit geval het pad in de URL waaronder de dienst beschikbaar wordt gemaakt, In ons geval wordt de URL daarmee https://netiqam/namsp.
De ‘Host Header’ wordt gebruikt om onderscheid te kunnen maken voor de achterliggende website (bijvoorbeeld ‘vhost’ in de Apache webserver). We kunnen hier kiezen voor het doorsturen van de hostnaam van de NetIQ Access Manager (‘Forward Received Hostname’) of voor het doorsturen van een zelf gekozen naam (‘Web Server Host Name’). Dat doen we hier en de naam die we hier kiezen is ‘namsp’.
Klik op ‘OK’.
Aan de configuratie in het overzichtsscherm is nu de volgende regel toegevoegd:
Indien u nu in hier op Test-SP klikt kunt u nog specifieke instellingen aanbrengen. Het is afhankelijk van de dienst welke nodig zijn.
Klik nu in het overzichtsscherm op ‘NAM-Service’ (de overkoepelende configuratie voor de nieuwe reverse proxy). Ga nu naar de tab ‘Protected Resources’. Dan komen we in het volgende scherm:
Klik in dit scherm op ‘New’. En vul een naam in en klik op ‘OK’.
In het volgende scherm vullen we een beschrijving in en een URL. dat moet hetzelfde zijn als we eerder hebben ingevuld, namelijk namsp. Hiermee gaan we authenticatie afdwingen voor alles wat zich achter dit pad bevindt.
Nu gaan we naar de tab ‘Identity injection’ en we vinken ‘basic_auth’ aan en klikken op ‘Enable’. Dit geldt alleen als de achterliggende applicatie basic authentication aan kan.
Klik op de link ‘basic_auth’. Dan verschijnt het volgende scherm:
We klikken nu op ‘1’ onder ‘Rule’ en gaan daarmee de injection aanpassen.
We passen de configuratie aan zodat het LDAP attribuut ‘cn’ op de authentication header user name wordt afgebeeld. We hebben eerder namelijk in de attribute mapping (zie NetIQ Access Manager als IdP) aangegeven dat ‘cn’ voor SURFconext de gebruikersnaam (uid) is. We gebruiken hier een dummy password.
Klik op ‘OK’, sluit alle schermen door op ‘OK’ of ‘Close’ knoppen te klikken (sluit nooit een scherm vanuit de browser). Update nu de configuratie.
Ga nu als gebruiker naar de URL die hoort bij de reverse proxy voor de dienst. In ons geval https://netiqam/namsp. We hebben hier de volgende PHP pagina achter gezet:
<?php phpinfo(); ?> |
De output ziet er dan als volgt uit:
Hierin zijn de geauthenticereerde gebruiker en het door ons aangebrachte dummy wachtwoord te herkennen in de PHP server variabelen: PHP_AUTH_USER en PHP_AUTH_PW.