PoC Webservices en SURFfederatie Project Projectjaar Projectmanager Auteur(s) Opleverdatum Versie
: : : : : :
SURFworks 2009 Remco Poortinga – van Wijnen Peter Clijsters (Everett) 28-09-2009 1.0
Samenvatting Dit document geeft een beschrijving van de uitgevoerde Proof of Concept (PoC) voor webservices en de SURFfederatie. Het is een tweede stap in de technologieverkenning voor dit onderwerp, de eerste bestaat uit een rapport. De PoC is met succes uitgevoerd; het WS-Trust scenario zoals voorgesteld in het rapport is volledig geïmplementeerd op basis van het product PingFederate. Voor ontwikkeling van de webservice en de webservices client is gebruik gemaakt van het Metro framework, welke gebruik maakt van JAX-WS. Er worden aanbevelingen gedaan voor verdere stappen voor mogelijk gebruik van webservices binnen de SURFfederatie.
Voor deze publicatie geldt de Creative Commons Licentie “Attribution-NoncommercialShare Alike 3.0 Netherlands”. Meer informatie over deze licentie is te vinden op
SURFworks SURFfederatie PoCs Web Services Onderzoek naar standaarden voor federatieve webservices Publiek Everett
Dit project is tot stand gekomen met steun van SURF, de organisatie die ICT vernieuwingen in het hoger onderwijs en onderzoek initieert, regisseert en stimuleert door onder meer het financieren van projecten. Meer informatie over SURF is te vinden op de website (www.surf.nl).
2
6 dingen die je moet weten over PoC Webservices en SURFfederatie Context
Wat is het?
Voor wie is het?
Hoe werkt het?
Wat kan je ermee?
Extra (Bijlagen, Thema, Gerelateerde thema’s)
Proof of Concept nodig voor het faciliteren van federatief webservices verkeer tussen instellingen onderling en met andere informatie aanbieders en afnemers.
Toevoegen van een Security Token Service (STS) aan de SURFfederatie om federatieve webservices mogelijk te maken, in plaats van alleen web/browser gebaseerde interactie.
Ontwikkelaars van webservices, mogelijke aanbieders van webservice diensten, geïnteresseerden in federatieve webservices.
Toevoegen van een extra component (STS) die het mogelijk maakt de vertrouwensrol van SURFnet binnen de SURFfederatie uit te breiden naar webservices.
Mogelijk maken van aanbieden van diensten met behulp van webservices en/of diensten aan ‘de achterkant’ webservices te laten gebruiken ‘in naam van’ de gebruiker.
NetBeans projecten voor de verschillende onderdelen, aparte aanbeveling aan SURFnet over verdere voortzetting.
1 Inleiding 1.1 Achtergrond De focus van de SURFfederatie ligt momenteel op Identity Management (IdM) en Single Sign-On (SSO) voor interactieve, webgebaseerde diensten. In de toekomst zal echter federatieve identiteit veel breder worden gebruikt. De belangrijkste uitbreiding zal zijn naar het gebruik voor webservices (zoals SOAP en REST), zodat de identiteit in een Service Oriented Architecture (SOA) omgeving kan worden hergebruikt. Op deze manier kunnen systemen onderling informatie uitwisselen namens de gebruiker, zonder dat services misbruik kunnen maken van die rechten. De SURFfederatie zou in de toekomst voorzieningen kunnen bieden die het mogelijk maken om identiteitsgegevens voor webservices uit te wisselen.
1.2 Opdracht Om de mogelijkheden van de SURFfederatie uit te breiden met identiteitsgegevens voor webservices heeft SURFnet aan Everett de opdracht gegeven een technologieverkenning omtrent dit onderwerp uit te voeren. Deze verkenning moet in ieder geval een overzicht geven van webservices in het algemeen, de mogelijke beveiliging van webservices en hoe SURFnet, en specifiek de SURFfederatie, hierin een rol kan spelen. De technologieverkenning bestaat uit twee delen; een rapport en een Proof Of Concept (PoC). Dit document bevat een verslag van de PoC. Het rapport is eerder opgeleverd (ref[1]) en bevat o.a. een aanzet tot de uitvoering van de PoC. De technologieverkenning als geheel moet genoeg informatie opleveren om een beslissing te kunnen nemen over het doorgaan met verdere dienstontwikkeling omtrent webservices voor de SURFfederatie. Het advies dat dient als basis voor deze beslissing is geen onderdeel van dit document; de observaties en aanbevelingen in hoofdstuk 4 zijn dan ook technisch van aard en nuttig als wordt besloten om door te gaan met dit onderwerp binnen de SURFfederatie.
1.3 Werkwijze Deze PoC is uitgevoerd vanuit de conclusies van het webservices rapport en de bij Everett aanwezige kennis over webservices beveiliging. De PoC infrastructuur (VMWare servers) is opgebouwd bij en door SURFnet waarna Everett de installaties, configuraties en ontwikkeling van de PoC elementen zoals beschreven in hoofdstuk 2 heeft uitgevoerd.
1.4 Scope Uitgangspunt voor uitvoering van de PoC is hoofdstuk 4 van het webservices rapport (ref[1]). Hierin wordt voorgesteld de WS-Trust standaard te gebruiken als basis voor de PoC met PingFederate als product.
1.5 Leeswijzer Voor een goed inzicht in de werking van de PoC kan worden volstaan met het lezen van hoofdstukken 2 t/m 4. Hoofdstuk 2 beschrijft in het kort de use case en de gebruikte PoC infrastructuur, inclusief de software en de functies die ze invullen. Hoofdstuk 3 beschrijft de ontwikkelde applicaties, namelijk de webservice (WS-Provider) en de client (WSClient) webapplicaties. Hoofdstuk 4 geeft een evaluatie van de PoC, waarbij observaties worden gedaan en aanbevelingen worden gegeven indien verder wordt gegaan met de ontwikkeling omtrent webservices voor de SURFfederatie.
5
Hoofdstuk 5 is een bijlage die in detail aangeeft hoe de verschillende software componenten zijn geïnstalleerd en geconfigueerd en geeft de Java code van de gerealiseerde WS-Client. De gebruikte referenties in dit document zijn opgenomen in hoofdstuk 6.
6
2 PoC infrastructuur opzet In het voorafgaande rapport (ref[1]) wordt beschreven welke use case door de PoC gerealiseerd moet worden, deze is weergegeven in Figuur 1. De use case die wordt beschreven bestaat uit een ‘reguliere’ SURFfederatie web applicatie die namens de gebruiker andere web services aanroept. Het ‘namens de gebruiker’ aanroepen van webservices biedt de mogelijkheid om webapplicaties te ontwikkelen die een service aanbieden die is samengesteld uit afzonderlijke functionaliteiten bij verschillende aanbieders. Praktisch valt hierbij te denken aan bijvoorbeeld het dynamisch opzetten van lichtpaden, waarbij de management interface(s) die de lichtpaden opzetten als webservice worden aangeboden. Een ander voorbeeld is een workflow systeem voor wetenschappelijke experimenten waarbij de webapplicatie het workflow systeem vormt (de coördinator) en de afzonderlijke stappen die daarvoor nodig zijn - zoals verzamelen van data, verschillende verwerkingsstappen van deze data en het opslaan van resultaten en metadata – als individuele webservices worden aangeboden. Dit maakt het ontwikkelen van nieuwe services eenvoudiger omdat ze kunnen worden samengesteld uit generieke onderdelen zoals opslag van data en juist ook hele specifieke onderdelen (bijvoorbeeld analyseren van data afkomstig van een meetinstrument). Voor de aanbieders van zowel de specifieke als generieke onderdelen betekent dit dat het makkelijker wordt om deze aan te bieden, er kan immers gebruik worden gemaakt van gestandaardiseerde (webservice) technologie voor het aanbieden van de service en de service kan worden aangeboden zonder dat er een volledige dienst omheen gebouwd hoeft te worden, zodat de makers zich kunnen concentreren op hun eigen expertise. Instelling 3
SURFnet
B
SURFfederatie
Eindgebruiker
Instelling 1
A
Web applicatie WS Client
Instelling 2
WS Provider
C
(Legacy) applicatie
Figuur 1: Door PoC te realiseren Use Case. De generiek use case die deze verschillende mogelijkheden mogelijk maakt gaat uit van 3 instellingen en SURFnet (de SURFfederatie). De eindgebruiker bevindt zich in instelling 3 (of op een willekeurige plek met een browser met internet toegang) en maakt gebruik van een web applicatie in instelling 1, waarbij instelling 3 optreedt als IdP en instelling 1 als SP. Dit gedeelte is dus het 'reguliere' SURFfederatie scenario. De web applicatie van instelling 1 maakt echter gebruik van een webservice die wordt geleverd door instelling 2, het aanroepen van die webservice door de webapplicatie gebeurt hier namens de gebruiker. De webapplicatie gebruikt daartoe de WS Client om de WS Provider van instelling 2 aan te roepen (C). Voordat de WS Provider het verzoek verwerkt zal het verzoek moeten worden geauthenticeerd en geautoriseerd op basis van de eindgebruikers gegevens. Indien akkoord zal de WS Provider het verzoek doorgeven aan de onderliggende (legacy) applicatie. Deze zal het verzoek verwerken, een antwoord formuleren en dit middels dezelfde weg terug sturen. 7
In het voorafgaande rapport werd aanbevolen om de PoC uit te voeren op basis van een WS-Trust oplossing, waarbij de SURFnet STS (Security Token Service) middels PingFederate 6 wordt geïmplementeerd, aangezien dit product ook wordt gebruikt voor de implementatie in de SURFfederatie. De Proof of Concept dient wel los van de huidige SURFfederatie opgezet te worden. Daarbij zal een STS van een instelling in eerste instantie eveneens geïmplementeerd worden met PingFederate 6 De webservices client en provider die in de PoC worden gebruikt zijn eenvoudige webservices. De inhoud van de webservice is voor de PoC van minder belang, er zal voornamelijk aandacht besteed worden aan de webservices authenticatie. Verderop zal dit in meer detail worden besproken, inclusief de producten en plugin-ins die gebruikt zijn. Figuur 2 geeft dit gedetailleerde overzicht weer.
Figuur 2: PoC setup. Figuur 2 is verdeeld in 4 vlakken die ieder een instelling of SURFnet uitbeelden. De geinstalleerde componenten per instelling zijn: Instelling 1 / WS-Client Instelling 1 bestaat uit een VMWare image met RHEL Server 5.3 met hostname pocwsclient.wind.surfnet.nl. Hierop zijn de volgende componenten geïnstalleerd: • JDK 1.6.0 release 13. Deze wordt gebruikt door verschillende componenten, zoals Tomcat en PingFederate. • Apache 2.2.3 die middels een AJP/1.3 connector verbonden is met Tomcat. Daarbij is voor Apache een PingFederate Apache Integration Kit geïnstalleerd. Deze zorgt ervoor dat eindgebruikers die van de applicaties in Tomcat gebruik willen maken, bij de SURFfederatie geauthenticeerd worden of zijn. Na authenticatie wordt er bij de gebruiker een cookie gezet met een OpenToken. 8
• •
Tomcat 5.5.27 welke fungeert als de webcontainer voor het draaien van de WSClient webapplicatie. PingFederate (PF) 6.0.0.1 server; deze is geconfigureerd met een aantal rollen: ◦ In samenwerking met de Apache Integration Kit v2.1.1 als Service Provider (SP) voor de SURFfederatie. ◦ STS IdP functionaliteit voor instelling 1 met de OpenToken Token Translator v1.0 plugin geïnstalleerd. Deze maakt het mogelijk om het OpenToken van de eindgebruiker in te wisselen tegen een SAML token voor instelling 1.
De installaties en configuraties van de WS-Client software worden in detail beschreven in paragraaf 5.1. Instelling 2 / WS-Provider Instelling 2 bestaat uit een VMWare image met RHEL Server 5.3 met hostname pocwsprovider.wind.surfnet.nl. Hierop zijn de volgende componenten geïnstalleerd: • JDK 1.6.0 release 13, welke gebruikt wordt door Tomcat. • Tomcat 5.5.27 die fungeert als de webcontainer voor het draaien van de WSProvider webapplicatie. De installaties en configuraties van de WS-Provider software worden in detail beschreven in paragraaf 5.2. Instelling 3 / Eindgebruiker De eindgebruiker is een willekeurig persoon die de beschikking heeft over een internet browser. SURFnet Het SURFnet blok bestaat uit twee delen: • De SURFfederatie testomgeving, deze is niet n.a.v. deze PoC ingericht, maar bestond al binnen SURFnet. • De PoC STS VMWare image, deze fungeert als STS en is ingericht met RHEL Server 5.3 met hostname poc-sts.wind.surfnet.nl. Hierop zijn de volgende componenten geïnstalleerd: • JDK 1.6.0 release 13; deze wordt gebruikt door PingFederate. • PingFederate (PF) 6.0.0.1 server is geconfigureerd met twee STS rollen: ◦ STS IdP functionaliteit die het mogelijk maakt om het SAML token van instelling 1 in te wisselen tegen een SURFnet SAML token. ◦ STS SP functionaliteit die het mogelijk maakt om SURFnet SAML tokens te valideren. Deze functionaliteit kan gebruikt worden door instelling 2, maar is niet noodzakelijk; valideren van SURFnet SAML tokens kan ook gebeuren door een trust relatie tussen instelling 2 en de SURFnet STS. De installaties en configuraties van de SURFnet software worden in detail beschreven in paragraaf 5.3.
9
3 Applicaties Voor het ontwikkelen van de webservices applicaties is het Metro 1.5 framework gebruikt welke JAX-WS implementeert. In eerste instantie is gestart met het Axis2 framework; deze had echter het probleem dat voor WS-Security niet het SAML profiel werd ondersteund (wel het username/password en het X.509 certificaat profiel). Voor ontwikkeling is er gebruik gemaakt van de Netbeans IDE.
3.1 WS-Provider applicatie Er is een eenvoudige webservice geïmplementeerd met “StockQuote” functionaliteit (zie ref[3] voor een handleiding voor het maken van een webservice met Metro en Netbeans). Deze webservice biedt twee methodes aan: • getPrice(symbol); geeft de prijs van het aandeel “symbol” terug. • Update(symbol, price); wijzigt de prijs van aandeel “symbol” naar “price”, geeft geen data terug. Aan de hand van onderstaande eenvoudige Java code is een stockquote2 webservice gegenereerd. De webservice is vervolgens met WS-* features beveiligd. Dit is gedaan aan de hand van de instructies in ref[4]. Figuur 3 laat het bijbehorende Netbeans webservices security configuratiescherm zien.
package nl.surfnet.webservices.stockquote2; import java.util.HashMap; public class StockQuoteService { private HashMap map = new HashMap(); public double getPrice(String symbol) { Double price = (Double) map.get(symbol); if(price != null){ return price.doubleValue(); } return 42.00; } public void update(String symbol, double price) { map.put(symbol, new Double(price)); } }
10
Figuur 3: Webservice security instellingen in Netbeans. In Figuur 3 zijn de volgende configuratie items van belang: •
Het gekozen security mechanisme is “SAML sender vouches with certificates”. Metro biedt verschillende security mechanismen, zie voor een overzicht ref[2]. Een aantal van deze mechanismen zijn gericht op het gebruik van een STS. Deze lijken wellicht goed geschikt voor deze implementatie, maar het selecteren hiervan zal later bij het genereren van de WS-Client voor problemen zorgen. Zo zal de WS-Client dan bijvoorbeeld alleen met username/password tokens overweg kunnen, niet met SAML tokens; wat een vereiste is voor deze use case.
•
Het antwoord van de webservice op de getPrice() methode wordt gesigned en versleuteld. Hiervoor is een certificaat nodig welke opgenomen is in een Java keystore. De locatie van deze keystore, het wachtwoord en het alias van het gebruikte certificaat kan aangegeven worden door de knop “Keystore…” te gebruiken.
•
Certificaten spelen een belangrijke rol bij de hier geimplementeerde webservices security: • De signing en encryptie van de webservice aanroep wordt door het certificaat van de WS-Client gedaan. • De SAML assertion die bij de webservice aangeboden zal worden is gesigneerd door het SURFnet STS certificaat. De webservice moet dan ook de CA’s van beide certificaten vertrouwen. Met andere woorden: de CA’s en public keys moeten opgenomen zijn in een truststore 11
waarnaar de StockQuote2 applicatie verwijst. Achter de knop “Truststore…” in Figuur 3 kan de lokatie van de truststore en het wachtwoord ingevoerd worden. •
Optioneel - Om de SAML assertion te kunnen valideren kan volstaan worden met het valideren van de CA van het certificaat wat de SAML assertion heeft getekend. Echter, het is ook mogelijk de SAML assertion te valideren bij de SURFnet STS. Hiertoe kan achter de knop “Validators…” een SAML Validator class ingevuld worden. In de PoC is deze class ook daadwerkelijk gemaakt en getest. De toegevoegde waarde hiervan is echter beperkt aangezien de SURFnet STS eigenlijk alleen de CA verifieert van het certificaat waarmee het SAML assertion getekend is. Dit is echter ook al door de WS-Provider gedaan (zie vorige punt).
Bij het compileren en bouwen van het StockQuote2 project in Netbeans wordt de basis webservice met de toegevoegde security opties (als WS-SecurityPolicy elementen) door Metro in een WSDL document vertaald (zie paragraaf 5.4 voor een listing van de WSDL). Deze WSDL wordt vervolgens gebruikt voor het genereren van de WS-Client die de aanroep naar de webservice zal doen.
3.2 WS-Client applicatie De WS-Client applicatie van de PoC bestaat uit twee delen: •
Het presentatie en interactie deel voor de eindgebruiker, bestaande uit de stockquote2client.html webpagina en de StockQuote2ClientServlet.
•
De communicatie met de StockQuote2 webservice, inclusief de voorafgaande communicatie met de lokale en de SURFnet STS. Een groot deel van deze Java code is door Metro gegenereerd aan de hand van de webservice WSDL. Doordat voor de webservice het “SAML sender vouches with certificates” mechanisme is gekozen is er in de client nu een hook (de SamlCallbackHandler) gegenereerd die een SAML token moet teruggeven. Deze SamlCallbackHandler moet zelf geschreven worden en is verantwoordelijk voor de communicatie met de STS-en.
Figuur 4 geeft schematisch weer hoe de WS-Client applicatie eruit ziet. De code van de belangrijkste WS-Client componenten is opgenomen in paragraaf 5.5.
12
Figuur 4: Schematische weergave WS-Client applicatie. De stockquote2client.html pagina is de pagina die de gebruiker als eerste aanroept en ziet. Hier moet in een formulier het Stock symbol ingevoerd worden. Als nu op de submit knop wordt gedrukt wordt dit symbol aan de StockQuote2ClientServlet gegeven voor verwerking. Deze leest eerst het OpenToken cookie uit dat gezet is door de PingFederate Apache Integration Kit. Deze OpenToken moet later gebruikt kunnen worden door de SamlCallbackHandler en wordt tijdelijk weggeschreven in een Java singleton 1. Vervolgens doet de servlet de aanroep naar de gegenereerde webservice stub. 1
Merk op dat dit een slechte methode is om het OpenToken door te geven; deze Java singleton kan
namelijk maar één OpenToken bevatten. Bij meerdere gebruikers tegelijkertijd zal dit zeker tot conflicten
13
De gegenereerde Metro code, waaronder de webservices stubs, is lastig te doorgronden. In Netbeans is wel een wizard ter beschikking waarmee een aantal parameters voor deze code gezet kunnen worden. Figuur 5 laat deze wizard zien. De zaken die hier ingevuld moeten worden, zijn: •
Het verkeer naar de webservice moet worden gesigneerd en versleuteld. Hiervoor is een certificaat nodig welke opgenomen is in een Java keystore. De locatie van deze keystore, het wachtwoord en het alias van het gebruikte certificaat kan aangegeven worden door de knop “Keystore…” te gebruiken.
•
De antwoorden van de webservice zijn eveneens gesigneerd en versleuteld. Hiervoor moet dan ook de CA van het certificaat waarmee dit is gedaan (certificaat uit de keystore van de webservice) worden vertrouwd en de public key beschikbaar zijn. Met andere woorden, de CA en public key moeten opgenomen zijn in een truststore waarnaar de StockQuote2Client applicatie verwijst. Achter de knop “Truststore…” in Figuur 5 kan de lokatie van de truststore en het wachtwoord ingevoerd worden.
•
De SAML Callback Handler class die zorgt voor het SAML token moet ingevuld worden. Zoals in Figuur 4 al is weergegeven zorgt deze Handler ervoor dat, met behulp van de PingFederate WS-Trust Client API, het OpenToken ingewisseld wordt tegen een lokaal SAML token en vervolgens dit lokale SAML token wordt ingewisseld tegen een SURFnet SAML token.
Figuur 5: WS-Client security instellingen in Netbeans.
leiden. Idealiter zou het OpenToken via de Metro code aan de SAMLCallbackHandler doorgegeven moeten worden. Dit vereist echter het herschrijven van een deel van de gegenereerde code, wat hier niet nader is uitgewerkt.
14
Als laatste stap in Figuur 4 wordt het webservice verzoek door de Metro code volledig gemaakt (inclusief body, security headers, signing en encryptie) en opgestuurd naar de webservice. LET OP (1): Er zit een bug in de gebruikte release van de PingFederate WS-Trust Client API 1.0. Bij het configureren van een connectie naar een STS kan geen toegestane 'time skew' ingegeven worden die maakt dat kleine variaties in de tijd tussen servers worden genegeerd. Dit kan resulteren in regelmatige errors als een een RSTR (Request Security Token Response) bericht een creation date heeft die in de toekomst ligt. Dit RSTR bericht wordt dan door de WS-Trust Client als foutief bestempeld. In de PoC kwam dit regelmatig voor; de tijd op de SURFnet server liep geregeld voor op de tijd van de WS-Client server. Een workaround is om expres de tijd van de SURFnet server een aantal seconden achter te zetten t.o.v. de tijd op de WS-Client server. LET OP (2): Zorg dat bij ontwikkeling van de WS-Client applicatie in Netbeans minimaal JDK SE 6 Update 4 gebruikt. Deze JDK heeft namelijk JAX-WS 2.1 API (in plaats van versie 2.0 in oudere versies). Dit lost errors op bij het genereren van de webservice client. Om Netbeans met een andere JDK versie te laten werken moet etc/netbeans.conf worden aangepast.
15
4 Evaluatie PoC 4.1 Observaties Tijdens het uitvoeren van de PoC zijn een reeks observaties gedaan die van belang kunnen zijn voor een eventueel webservices vervolg traject. Deze observaties zijn: •
Het WS-Trust scenario zoals besproken in ref[1] is volledig gerealiseerd met behulp van PingFederate als STS. Extra varianten en STS implementaties zijn, wegens tijdsgebrek, niet meer getest.
•
Wat de meeste tijd heeft gekost tijdens de realisatie van de PoC is het toevoegen van webservices security aan de WS-Provider en WS-Client webapplicaties. Er is eerst met Axis2 gestart waarbij uiteindelijk bleek dat dit framework niet de juiste (SAML) profielen ondersteunde. Hierna zijn de webservices opnieuw gemaakt met het Metro framework wat JAX-WS implementeert. Daarbij is eveneens een overstap gemaakt van de Eclipse IDE naar Netbeans, aangezien de ondersteuning van Metro in Netbeans beter en uitgebreider is dan in Eclipse.
•
De configuratie van de PingFederate servers als STS ging erg voorspoedig en heeft geen problemen opgeleverd. De PingFederate WS-Trust Client API is verder eenvoudig in het gebruik en was met behulp van de meegeleverde voorbeelden snel geïmplementeerd. Logfile meldingen zijn van goede kwaliteit en maken bij problemen snel duidelijk waar eventuele oorzaken kunnen liggen. Er is een paar keer beroep gedaan op PingFederate Support; de response tijd was daarbij snel en van goede kwaliteit.
•
Metro was beter geschikt dan Axis2 voor het beveiligen van webservices in de PoC. Axis2 is zelf een webapplicatie die draait in Tomcat (of andere webcontainer), waarin vervolgens de webservices draaien. Dit maakt installatie ingewikkeld en het maken en deployen van webservices lastig (er kan geen “gewone” WAR gemaakt worden, maar er moet een speciale AAR worden gegenereerd). Dit in tegenstelling tot Metro wat bestaat uit een aantal libraries die in een standaard webservices WAR opgenomen kunnen worden. De ondersteuning van webservices security in Axis2 is verder beperkt en gaat uit van username/password of X.509 authenticatie. Authenticatie middels een SAML token, nodig voor deze use case, is (vooralsnog) geen standaard mogelijkheid. Metro ondersteunt op dit moment een reeks security mechanismen, waaronder SAML en WS-Trust scenario’s.
•
De WS-Provider webapplicatie was zeer eenvoudig te realiseren. De WS-Client realiseren was daarentegen een stuk ingewikkelder, omdat de WS-Client het lokale OpenToken uit de gebruikers sessie moet lezen en tijdelijk opslaan zodat dit later door de SamlCallbackHandler gebruikt kan worden (zie Figuur 4). De gebruikte singleton oplossing voldoet voor een PoC, maar voor productie gebruik zal hier een andere benadering voor moeten worden gerealiseerd. De SamlCallbackHandler zelf, met twee STS aanroepen, is overigens het meest complexe element uit de PoC.
16
4.2 Aanbevelingen De volgende aanbevelingen kunnen worden gedaan: •
Om een implementatie van een WS-Client applicatie eenvoudiger te maken voor een instelling zou een deel van de huidige WS-Client code als library door SURFnet aangeboden kunnen worden. Echter, de WS-Client applicatie zal nog steeds zelf geschreven webservices security code nodig hebben om bijvoorbeeld een lokaal security token uit te lezen en om te wisselen in een lokaal SAML token. Het meeleveren van voorbeeld code kan hierbij behulpzaam zijn.
•
De exacte security eisen van een webservice worden bepaald door de WSProvider. Hierbij bestaan zeer veel mogelijkheden waartussen de leverancier van de webservice kan kiezen. Het risico ontstaat dat de gebruikers van deze webservices veel verschillende clients, met verschillende security eisen moeten ontwikkelen. Het zou goed zijn hier een standaard, door SURFnet ondersteund, webservices security profiel voor te definieren. Een dergelijk profiel zou dan een aantal elementen uit de vele mogelijkheden binnen de WS-* standaarden moeten nemen. Hiervoor kan vervolgens een goed beschreven oplossing worden gegeven, inclusief ondersteunende libraries, voor zowel de WS-Provider als de WS-Client, voor de meest gangbare en geschikte frameworks.
17
5 Bijlage 5.1 WS-Client installaties en configuraties In deze paragraaf worden de installaties en configuraties die in het kader van deze PoC zijn uitgevoerd op de WS-Client (Instelling 1) server besproken. Het gaat hier om: • PingFederate • Apache • Tomcat
5.1.1
PingFederate
Het installeren van PingFederate is eenvoudig en staat goed beschreven in de “Getting Started” guide (ref[5]). De PingFederate installatie van de WS-Client (instelling 1) vervult twee functies: 1) SP voor de SURFfederatie. In combinatie met de Apache Integration Kit wordt de webapplicatie op de WS-Client afgeschermd en zal een niet geauthenticeerde eindgebruiker doorgestuurd worden voor authenticatie naar de SURFfederatie. Na authenticatie krijgt een gebruiker een cookie met een OpenToken gezet. 2) STS voor de lokale omgeving zodat het OpenToken ingewisseld kan worden voor een lokaal SAML token. Dit token kan later bij de SURFnet STS ingewisseld worden voor een token dat door de webservice wordt geaccepteerd. Beide functies worden in dezelfde PingFederate installatie op de pocwsclient.wind.surfnet.nl VMWare geconfigureerd. Onderstaande paragrafen beschrijven hoe beide functies zijn geimplementeerd in PingFederate.
5.1.1.1
SP voor SURFfederatie
Het configureren van de PingFederate installatie op de WS-Client als SP voor de SURFfederatie bestaat uit twee stappen. Allereerst moet de OpenToken adapter voor de Apache Integration Kit geconfigureerd worden (zie Figuur 6), deze wordt vervolgens gebruikt in de SURFfederatie connectie configuratie (zie Figuur 7). De configuratie voor de adapter zoals weergegeven in Figuur 6 is redelijk eenvoudig. De volgende zaken zijn van belang: • Type: Geeft aan dat het een OpenToken adapter betreft. • Transport Mode: De parameters tussen de Integration Kit en PingFederate worden middels Query parameters gecommuniceerd • Token Name: De naam van het cookie waarin de OpenToken wordt gezet. Het cookie met deze naam wordt later door de servlet in de WS-Client applicatie uitgelezen. • Extended Contract: Geeft aan welke attributen in het OpenToken gezet gaan worden. Attributen die vanuit de SURFfederatie worden verkregen kunnen hieraan gemapped worden (dit is geconfigureerd in de SURFfederatie SP connectie). Nadat de adapter geconfigueerd is moet deze configuratie bij de Apache Integration Kit ingebracht worden. Hiervoor kan de download optie gebruikt worden; naar de resulterende agent-config.txt moet verwezen worden door de PingFederateAgentConfigurationFile parameter in de mod_pf.conf file van de Integration Kit.
18
Figuur 6: SURFfederatie SP; Apache adapter configuration.
De SURFfederatie SP configuratie is weergeven in Figuur 7. Een groot deel van deze configuratie wordt ingevuld door de metadata file gekregen van de SURFfederatie (https://wayf-test.surfnet.nl/wayf-test-saml20-metadata-idp.xml). Overige belangrijke configuratie zaken zijn: • Attribute Contract: De attributen die ingevuld moet worden in de afgegeven SAML tokens. • Adapter instance: De adapter die hierboven is aangemaakt, in dit geval heeft de adapter de naam “Apache”. • Adapter Contract Fullfillment: Geeft aan hoe de benodigde attributen van de adapter (zoals genoemd in het “Attribute Contract”) gevuld gaan worden door de attributen verkregen uit de SURFfederatie. • Signature Verification Certificate: De CA van het certificaat waarmee de SURFfederatie tokens worden gesigned. Nadat de SP is geconfigureerd moet deze configuratie in de vorm van een metadata file geëxporteerd worden en aan de beheerders van de SURFfederatie gegeven worden. De exporteer functie kan gevonden worden onder “Administrative Funtions -> SAML Metadata”.
19
Figuur 7: SURFfederatie SP; SP configuratie.
5.1.1.2
STS voor lokale omgeving
Het configureren van de PingFederate installatie op de WS-Client als STS bestaat uit twee stappen. Allereerst moet de OpenToken Token Processor geconfigureerd worden (zie Figuur 8), deze wordt vervolgens gebruikt in de STS configuratie (zie Figuur 9). De OpenToken Token processor zorgt ervoor dat de STS OpenToken tokens kan omwisselen in SAML 2.0 tokens. PingFederate wordt niet standaard met deze Token Processor geleverd, dus deze moet gedownload en geïnstalleerd worden. Na installatie 20
kan een instance hiervan geconfigureerd worden. De configuratie hiervan is weergegeven in Figuur 8, hierbij zijn de volgende zaken van belang: • Type: Geeft hier aan dat het om een OpenToken Token Processor gaat • Extended Contract: Geeft aan welke attributen in het SAML token gezet gaan worden. Attributen die vanuit de OpenToken worden verkregen kunnen hieraan gemapped worden. Hier wordt alleen de subject gevuld, het was echter ook mogelijk om dit uit te breiden met bijvoorbeeld givenName, mail en surName.
Figuur 8: Instelling 1 STS; OpenToken Token Processor Instance. Er moet nu een specifieke connectie voor de WS-Client worden geconfigureerd die gebruikt zal worden door de PingFederate WS-Trust Client API in de WS-Client applicatie om het OpenToken token om te wisselen in een lokaal SAML token. Deze specifieke connectie maakt daarbij gebruik van de hierboven geconfigureerde OpenToken Token Processor instance. De belangrijkste eigenschappen van deze configuratie zoals weergegeven in Figuur 9, zijn: • •
• • •
•
WS-Trust STS: Het betreft een WS-Trust connectie Partner Service Identifier: Geeft de identifier aan waarmee van inkomende RST (Request Security Token) requests het AppliesTo veld gevuld is. Let op dat deze waarde ook ingevuld is in de configuratie van de WS-Trust Client API van de WSClient applicatie. Attribute Contract: De attributen die ingevuld moet worden in de afgegeven SAML tokens. Token Processor Instance: Wijst naar de instance van de OpenToken Processor die hierboven geconfigureerd is. Adapter Contract Fullfillment: Geeft aan hoe de benodigde attributen van de Token Processor (zoals genoemd in het “Attribute Contract”) gevuld gaan worden door de attributen verkregen uit het OpenToken. Selected certificate: Geeft het certificaat waarmee uitgaande lokale SAML tokens worden gesigned. 21
Figuur 9: Instelling 1 STS; WS-Client connectie configuratie.
5.1.2
Tomcat
Er is een reguliere Tomcat installatie uitgevoerd op de poc-wsclient.wind.surfnet.nl server. Na deze installatie moeten de Metro 1.5 libraries aan Tomcat toegevoegd worden. Doe dit door de *.jar files in de Metro 1.5 distributie te kopiëren naar de tomcat/shared/lib directory. Zoals al eerder besproken (zie paragraaf 3.2) moet er een Keystore en Truststore beschikbaar zijn voor de WS-Client webapplicatie. • De Keystore moet een certificaat bevatten wat de webservice aanroepen signed en encrypt. Doe dit bijvoorbeeld door een self-signed certificaat aan te maken als volgt: keytool -genkey –keyalg rsa -alias stockquote2client \ -keystore /usr/local/tomcat/certs/server-keystore.jks •
De Truststore van de WS-Client moet de CA en public key bevatten van het certificaat waarmee de antwoorden op de webservice aanroepen zijn gesigned en ge-encrypt. Dit certificaat bevindt zich op de WS-Provider server en is gegenereerd 22
zoals beschreven in paragraaf 5.2.1. Omdat dit ook een self-signed certificaat is moet op de WS-Provider eerst een export van deze CA gemaakt worden: keytool -exportcert -alias stockquote2 \ -keystore /usr/local/tomcat/certs/server-keystore.jks \ > stockquote2.pem Kopieer dit stockquote2.pem bestand naar de WS-Client en importeer dit hier in de Truststore: keytool -importcert -file stockquote2.pem \ -alias stockquote2 \ -keystore /usr/local/tomcat/certs/client-truststore.jks
5.1.3
Apache
Er is een reguliere Apache installatie uitgevoerd op de poc-wsclient.wind.surfnet.nl server (yum install httpd.i386). De PingFederate Apache Integration Kit zorgt ervoor dat de WS-Client webapplicatie (die draait op Tomcat) alleen toegankelijk is voor gebruikers die bij de SURFfederatie zijn geauthenticeerd. Om dit te realiseren moeten er binnen Apache twee zaken geconfigureerd worden. 1) Het proxyen van verzoeken voor Tomcat. Dit zorgt ervoor dat alle verkeer voor webapplicaties via Apache lopen en zodoende door Apache beveiligd kunnen worden. Voor dit proxyen is mod_jk gebruikt. Stappen voor installatie: • Download mod_jk.so. • Plaats deze in de Apache modules directory. • Voeg vervolgens de volgende configuratie regels toe aan httpd.conf: LoadModule jk_module modules/mod_jk.so JkWorkersFile /etc/httpd/conf/workers.properties JkShmFile /var/log/httpd/mod_jk.shm JkLogFile /var/log/httpd/mod_jk.log JkLogLevel info JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " JkMount /* worker1
•
Herstart Apache.
2) Het beveiligen van verzoeken voor een bepaalde web context door te controleren op een valide OpenToken cookie en indien nodig gebruikers doorsturen naar de PingFederate SURFfederatie SP configuratie. De Apache Integration Kit zorgt hiervoor. Stappen voor installatie en configuratie: • Download de PingFederate Apache Integration Kit en installeer deze volgens de bijgevoegde handleiding. • In de bijbehorende mod_pf.conf moeten een aantal parameters aangepast worden: PingFederateCookieDomain .wind.surfnet.nl PingFederateFilter /StockQuote2Client/ PingFederateLoginPageURL https://pocwsclient.wind.surfnet.nl:9031/sp/startSSO.ping?PartnerSpId=edugain.showcase.sur fnet.nl PingFederateErrorPageURL http://poc-wsclient.wind.surfnet.nl/error PingFederateSendAttributesOnce no
•
De PingFederate Apache module verwacht een aantal OpenSSL libraries in /usr/lib, deze staan nu echter in /lib. Maak links aan vanuit /usr/lib naar deze libraries in /lib: ln -s /lib/libssl.so.0.9.8e /usr/lib/libssl.so.0.9.8
5.2 WS-Provider installaties en configuraties In deze paragraaf worden de installaties en configuraties die in het kader van deze PoC zijn uitgevoerd op de WS-Provider (instelling 2) server besproken. Het gaat hier om: • Tomcat
5.2.1
Tomcat
Er is een reguliere Tomcat installatie uitgevoerd op de poc-wsprovider.wind.surfnet.nl server. Na deze installatie moeten de Metro 1.5 libraries aan Tomcat toegevoegd worden. Doe dit door de *.jar files in de Metro 1.5 distributie te copieren naar de tomcat/shared/lib directory. Zoals al eerder besproken (zie paragraaf 3.1) moet er een Keystore en Truststore beschikbaar zijn voor de WS-Provider webservice applicatie. • De Keystore moet een certificaat bevatten wat de webservice antwoorden signed en encrypt. Doe dit bijvoorbeeld door een self-signed certificaat aan te maken als volgt: keytool -genkey –keyalg rsa -alias stockquote2 \ -keystore /usr/local/tomcat/certs/server-keystore.jks •
De Truststore van de WS-Provider moet de CA en public key bevatten van het certificaat waarmee de webservice aanroepen zijn gesigned en ge-encrypt. Dit certificaat bevindt zich op de WS-Client server en is gegenereerd zoals beschreven in paragraaf 5.1.2. Omdat dit ook een self-signed certificaat is moet op de WSClient eerst een export van deze CA gemaakt worden: keytool -exportcert -alias stockquote2client \ -keystore /usr/local/tomcat/certs/server-keystore.jks \ > stockquote2client.pem Kopieer dit stockquote2client.pem bestand naar de WS-Provider en importeer dit hier in de Truststore: keytool -importcert -file stockquote2client.pem \ -alias stockquote2client \ -keystore /usr/local/tomcat/certs/client-truststore.jks
•
De Truststore van de WS-Provider moet ook de CA en public key bevatten van het certificaat waarmee het SURFnet SAML token is gesigned. Dit certificaat is aanwezig in de SURFnet STS en kan vanuit PingFederate geëxporteerd worden. Ga hiertoe naar de WSClient configuratie (aan de linker zijde, “My IdP Configuration”), open de WSClient SP configuratie, bij het tabblad “Credentials” kan een export gemaakt worden van het Digital Signature certificaat. Het resulterende bestand moet naar de WS-Provider worden gekopieerd en met een vergelijkbaar keytool import commando worden geimporteerd in de truststore.
5.3 SURFnet installaties en configuraties In deze paragraaf worden de installaties en configuraties die in het kader van deze PoC zijn uitgevoerd op de SURFnet server besproken. Het gaat hier om: 24
•
PingFederate
5.3.1
PingFederate
De PingFederate SURFnet installatie is alleen ingericht als STS en heeft twee functies in de PoC: 1) Inwisselen van SAML tokens van de WS-Client (instelling 1), waarbij een SURFnet SAML token wordt terug gegeven. Zie paragraaf 5.3.1.1 voor de bijbehorende PingFederate IdP configuratie. 2) Valideren van SURFnet SAML tokens. Merk op dat dit optioneel is in de PoC; de WS-Provider kan ook op basis van trust (vertrouwen in de CA van SURFnet) de SURFnet SAML tokens valideren.
5.3.1.1
IdP voor WS-Client
De IdP configuratie van de SURFnet STS bestaat uit twee delen; de configuratie van de Token Processor (zie Figuur 10) en de configuratie van de specifieke connectie met de WS-Client (zie Figuur 11). De Token Processor configuratie geeft aan hoe en onder welke voorwaarden tokens uitgedeeld worden. De belangrijkste eigenschappen van deze configuratie zijn: • Type: dit geeft aan dat het hier om een SAML 2.0 Token Processor gaat. Alleen SAML 2.0 tokens kunnen geaccepteerd worden. • Valid Certificate Subject DNs: De inkomende SAML 2.0 tokens moeten dit Subject DN hebben. Dit is, samen met het “Valid Certificate Issuer DN” welke niet is weergegeven in Figuur 10, een optionele parameter. Waarschijnlijk is het in een productie situatie nuttiger om alleen deze laatste in te vullen met alle CA’s van de instellings STS-en. • Audience: Geeft aan wat de waarde van het element in de inkomende SAML assertion moet zijn.
Figuur 10: SURFnet STS; IdP Token Processor Configuration. 25
Er moet nu een specifieke connectie voor de WS-Client worden geconfigureerd die gebruikt zal worden door de PingFederate WS-Trust Client API in de WS-Client applicatie om het instelling 1 SAML token om te wisselen in een SURFnet SAML token. Deze specifieke connectie maakt daarbij gebruik van de hierboven geconfigureerde Token Processor instance. De belangrijkste eigenschappen van deze configuratie zijn: • • • •
WS-Trust STS: Het betreft een WS-Trust connectie. Partner Service Identifier: Geeft de identifier aan waarmee van inkomende RST requests het AppliesTo veld gevuld is. Token Processor Instance: Wijst naar de instance die hierboven geconfigureerd is. Selected certificate: Geeft het certificaat waarmee uitgaande SURFnet SAML tokens gesigned worden.
Figuur 11: SURFnet STS; WS-Client connectie configuratie.
26
5.3.1.2
Token validatie voor WS-Provider
Deze configuratie is alleen nodig als WS-Providers actief de gebruikte SAML tokens gaan valideren bij de SURFnet STS. In deze PoC is dit wel getest, maar dit zal voor een productie situatie geen toegevoegde waarde hebben. De validatie is niet meer dan het controleren van de CA van het certificaat wat gebruikt is voor de signing van de SAML assertion, wat net zo goed direct door de WS Provider gedaan kan worden. Daarbij kan deze validatie veel data verkeer veroorzaken en performance kosten. De belangrijkste configuratie parameter hier zijn: • Request Processing Options: Hiermee wordt aangegeven dat alleen inkomende SAML Tokens gevalideerd worden. • Signature Verification Certificate: De geaccepteerde CA’s van de signing certificates in de te valideren SAML tokens.
Figuur 12: SURFnet STS; Validate token configuratie.
5.4 Webservice WSDL De WSDL van de StockQuote2 webservice kan opgevraagd worden middels de volgende URL: http://poc-wsprovider.wind.surfnet.nl:8080/StockQuote2/StockQuote2WS?wsdl De WSDL kan worden gebruikt om een webservice client stub te genereren. De WSDL ziet er als volgt uit:
