EAWS REST doelsysteem documentatie
Inleiding
IDM (Gebruikersbeheer) 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 IDM ook een zeer fijne parametriseerbaarheid binnen het rollenmodel, die we generiek ‘contexten’ noemen. De bron voor de waarden van deze contexten kan ofwel lokaal IDM zelf zijn wanneer het rollenmodel statisch is en weinig verandert, of kan een externe web service zijn (gehost door de klant) waaruit IDM de waarden dynamisch ophaalt via REST. 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 voor het toekennen gaan als volgt:
De lokale beheerder wenst een recht toe te kennen aan een gebruiker van zijn organisatie.
IDM stuurt een REST-request met de organisatiecode(s) van de werkrelatie, naam van het recht en naam van de context 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
De stappen voor het aanmelden als gebruiker gaan als volgt:
Een gebruiker wenst in te loggen op de toepassing
Gebruiker 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.
Architectuur
Voor de gegevensuitwisseling tussen IDM 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 IDM en EAWS zal plaatsvinden.
oAuth beveiliging & Mutual TLS
Voor het beveiligen van de communicatie tussen IDM en de EAWS ondersteunen we enkel oAuth voor REST API’s.
De EAWS moet een GlobalSign of VO PKI TLS server certificaat voorzien dat Datapower kan vertrouwen. (Datapower trust niet alle root CAs)
Naast deze beveiligingsmaatregelen, moeten mogelijks ook de nodige datastromen voorzien worden langs de kant van de EAWS. Het IP-adres van de Datapower kan gevonden worden in het integratiedossier. Dit is enkel noodzakelijk indien de EAWS web service filtering doet op basis van caller IP.
Optioneel: Voor een extra veilige verbinding, kan de EAWS Mutual TLS authenticatie implementeren, waarbij beide partijen zich authenticeren tegenover elkaar d.m.v. X509 certificaten. De EAWS vertrouwt dan de het client certificaat van Datapower.
Acties Klant - Onboarding
Om de EAWS web service te koppelen met het 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 IDM.
Daarnaast moet de klant ook een aantal acties uitvoeren om de volledige opzet te laten werken.
Acties die de klant moet uitvoeren langs hun zijde:
oAuth API opzetten via het integratieteam van de Veiligheidsbouwstenen (integraties@vlaanderen.be)
Datastromen voorzien voor IP Datapower. Informatie kan gevonden worden in integratiedossier (Optioneel, enkel noodzakelijk in geval van IP filter)
Optioneel mTLS: Vertrouwen van client certificaat van Datapower. Certificaten kunnen gevonden worden in het integratiedossier
De gegevens die de klant moet aanleveren aan het integratieteam:
IP + URL van de webservice + Poort (T&I + PRD)
oAuth client id van de API en eventuele scopes
Host omgeving (VPC Cloud, NMC4, VPC Overgangszone of een andere externe omgeving)
GlobalSign of VO PKI SSL server certificaat
Technische Documentatie: EAWS - REST Webservice
IDM initieert de communicatie en stuurt de organisatiecode(s) van de werkrelatie, naam van het recht en naam van de context naar de EAWS. Het antwoord van de EAWS naar IDM bevat de contextwaarden die IDM mag weergeven aan de lokale beheerder voor die organisatie.
Naast het opvragen van de contexten gebeurt er periodieke een API call naar het alive endpoint.
Dit dient voor monitoring of de verbinding werkt.
Op deze pagina:
Vragen of suggesties, contacteer ons via: integraties@vlaanderen.be
Heb je nood aan ondersteuning bij het gebruik van de toepassing, contacteer de 1700.