1.Inleiding
WebIDM is een webapplicatie die het toelaat om rechten voor toepassingen toe te kennen aan identiteiten die bekend zijn bij de Vlaamse overheid. Deze rechten worden altijd toegekend op basis van de koppeling met een organisatie of instelling, ook wel werkrelatie genoemd.
Naast het toekennen van gebruikersrechten, ondersteunt WebIDM ook een zeer fijne parametriseerbaarheid binnen het rollenmodel, die we generiek ‘contexten’ noemen. De bron voor de waarden van deze contexten kan ofwel lokaal WebIDM zelf zijn wanneer het rollenmodel statisch is en weinig verandert, of kan een externe web service zijn (gehost door de klant) waaruit WebIDM de waarden dynamisch ophaalt via SOAP. Deze webservice noemen wij de External Artefact WebService (EAWS), en wordt in dit document in detail beschreven.
De volgende afbeelding toont de interactie tussen de verschillende componenten wanneer een EAWS gebruikt wordt als (dynamische) bron voor contextwaarden:
De stappen gaan als volgt:
- De lokale beheerder wenst een recht toe te kennen aan een gebruiker van zijn organisatie.
- WebIDM stuurt een SOAP-request met de organisatiecode van de gebruiker naar de EAWS. De EAWS antwoordt met de contexten die de lokale beheerder mag toekennen voor deze gebruiker. De lokale beheerder kan vervolgens de contexten kiezen en het recht toekennen
- Een gebruiker wenst in te loggen op de toepassing en wordt omgeleid naar ACM voor authenticatie en autorisatie.
- ACM haalt de nodige rolleninformatie (waaronder de gekozen contextwaarden) op bij IDM.
- ACM stuurt de gebruiker door naar de toepassing met de identiteits- en rolleninformatie.
- De gebruiker is aangemeld op de toepassing.
2.Architectuur
Voor de gegevensuitwisseling tussen het Gebruikersbeheer en de EAWS, wordt gebruik gemaakt van een tussenliggende component, i.e. Datapower. Hieronder kan een vereenvoudigde afbeelding gevonden worden van de opzet. De verschillende componenten en eigenschappen zijn aangeduid op de figuur, waar kan gezien worden dat geen rechtstreeks communicatie tussen Gebruikersbeheer en EAWS zal plaatsvinden.
3.Beveiliging & Mutual SSL
Voor het beveiligen van de communicatie tussen WebIDM en de EAWS web service ondersteunen we enkel Mutual SSL authenticatie.
Naast deze beveiligingsmaatregelen, moeten mogelijks ook de nodige datastromen voorzien worden langs de kant van de toepassing. Het IP-adres van de Datapower kan gevonden worden in het integratiedossier.
Voor een veilige verbinding, zowel over het lokaal netwerk binnen VO als over Internet, moeten WebIDM en de EAWS web service Mutual SSL authenticatie implementeren, waarbij beide partijen zich authenticeren tegenover elkaar d.m.v. X509 certificaten.
De EAWS web service producer moet het client certificaat van Datapower vertrouwen. Daarnaast moet de EAWS web service producer een GlobalSign of VO PKI SSL server certificaat voorzien dat WebIDM kan vertrouwen.
4.Acties Klant - Onboarding
Om de EAWS web service te koppelen met het gebruikersbeheer IDM, moet de klant de technische details van de web service doorgeven aan het integratieteam. Het integratieteam zal deze gegevens dan opnemen in het onboardingsdocument, en daarna gebruiken als basis om de EAWS-webservice te configureren in WebIDM.
Daarnaast moet de klant ook een aantal acties uitvoeren om de volledige opzet te laten werken.
De gegevens die de klant moet aanleveren aan het integratieteam:
- IP + URL van de webservice + Poort (T&I + PRD)
- Host omgeving (VPC Cloud, NMC4, VPC Overgangszone of een andere externe omgeving)
- GlobalSign of VO PKI SSL server certificaat
Acties die de klant moet uitvoeren langs hun zijde:
- Datastromen voorzien voor IP Datapower. Informatie kan gevonden worden in integratiedossier
- Vertrouwen van client certificaat van Datapower. Certificaten kunnen gevonden worden in het integratiedossier
5.Technische Documentatie: EAWS - SOAP Webservice
De volgende figuur toont de interactie tussen WebIDM en de EAWS webservice wanneer WebIDM de contextwaarden opvraagt bij de EAWS.
WebIDM initieert de communicatie en stuurt de organisatiecode van de gekozen werkrelatie naar de EAWS. Het antwoord van de EAWS naar WebIDM dient opnieuw de gekozen organisatiecode te bevatten, én de contextwaarden die WebIDM mag weergeven aan de lokale beheerder voor die organisatie.
De volgende secties beschrijven de structuur van de SOAP-berichten, het XSD-schema, web service technische beschrijving (WSDL), en een voorbeeld-implementatie in JAVA.
5.1 Voorbeeld Request
Volgend XML-bestand toont een voorbeeld SOAP-bericht dat WebIDM verstuurt naar de EAWS. De enige parameter die WebIDM meestuurt in de request is de organisatiecode (GID: OVO-code, EA & LB: KBO-nummer, OV: vestigingsnummer):
De Body van het bericht bevat het element ‘QuerySingleFilterBeschikbareEntitlementRequest’. Dit element heeft een aantal kind-elementen, waarin uiteindelijk op het diepste niveau de organisatiecode vervat zit. Dit is de organisatiecode die de EAWS kan gebruiken om de gepaste contextwaarden op te zoeken en terug te sturen naar WebIDM.
Daarnaast vinden we in dit element ook het element ‘SelectAttributeList’ terug. De opgegeven attribuutwaarden binnenin dit element verwijzen naar de achterliggende naamgeving om de technische waarde en displaynaam van de contextlijst door te sturen. Deze naamgeving ligt vast, i.e. ContextWaarde en ContextNaam.
5.2 Voorbeeld
Volgend XML-bestand toont een voorbeeld SOAP-bericht dat de EAWS web service terugstuurt naar WebIDM. Het antwoord dient de originele vraag te bevatten (i.e. het ‘SingleWhereFilterQuery’ element uit de request), en de contextwaarden die van toepassing zijn voor de organisatiecode uit de request.
Voor elke contextwaarde dient de web service een ‘ResultRow’ aan te maken, die zowel de technische waarde als de displaynaam van de context bevat. De displaynaam is de waarde die WebIDM weergeeft aan de lokale beheerder tijdens het kiezen van de contexten, de technische waarde is de waarde die WebIDM wegschrijft in het attribuut met rolleninformatie voor het recht:
5.3 Web Service Schema en Beschrijving
Het volgende ZIP-bestand bevat een gedetailleerde technische beschrijving van de web service (WSDL-bestand), en de structuur van de elementen (XSD-bestanden) waaraan WebIDM en de EAWS moeten voldoen om te communiceren met elkaar.
5.4 Referentie Implementatie (JAVA - SPRING BOOT)
Het volgende ZIP-bestand bevat een referentie-implementatie van een EAWS web service, geschreven in JAVA, met behulp van het Spring Boot framework.
Het belangrijkste bestand in dit project is ‘src/main/java/webservice/OrganisationEndpoint.java’. Dit bestand implementeert de methode ‘getResponse()’, waarin de SOAP-request binnenkomt en gedecodeerd wordt.
Op basis van de organisatiecode in het ‘QuerySingleFilterBeschikbareEntitlementRequest’ object, haalt de web service één of meerdere bijhorende contextwaarden op (in dit voorbeeldproject op basis van een XML-bestand dat de organisaties en bijbehorende contexten bevat).
De web service stuurt deze contextwaarden dan terug naar WebIDM in een ‘QuerySingleFilterBeschikbareEntitlementStringResponse’ object.
In dit voorbeeld wordt lokaal de webservice opgestart op poort 9090. Dit wordt geconfigureerd in het bestand ‘src/main/resources/application.properties’. In die folder staan verder ook nog de schemadefinities en het bronbestand dat de organisaties en bijbehorende contextwaarden vastlegt.
Het project is gebaseerd op het volgende standaard Spring Boot project: https://spring.io/guides/gs/producing-web-service/, en heeft volgende requirements:
- Java JDK 1.8
- Gradle 2.3+ of Maven 3.0+
Spring Boot zorgt voor een self-contained web service, waardoor developers dit project eenvoudig zelf kunnen aanpassen, bouwen en opstarten.
De web service kan getest worden met bv. Postman, met behulp van volgende requests:
