Independent. Dynamic. Involved.
nlen

De 10 meest voorkomende pitfalls bij SCIM 2.0-compliant API-implementaties

Door Paul van Gool.  Steeds meer organisaties die Identity Governance and Administration-oplossingen (IGA) hebben geïmplementeerd, kiezen ervoor om de gebruikers- en autorisatie-data in businessapplicaties via allerlei verschillende integratiemethoden te onderhouden. We zien in dat verband veel verschillende methoden die geen enkele standaard gebruiken. In veel gevallen moet een ontwikkelaar een maatwerk-API en/of maatwerkconnectors bouwen, zodat IGA-systemen doelapplicaties kunnen voeden. Dat leidt tot hogere kosten en langere leadtijden van deze implementaties. Gelukkig is er nu een integratiestandaard in opkomst: SCIM. 

business man looking at pitfalls

SCIM, of System for Cross-domain Identity Management, is een open standaard voor het beheren van de gebruikers- en autorisatie-lifecycle in doelapplicaties. Doordat SCIM een open standaard is, zorgt het voor lagere kosten en minder complexiteit. Het leidt tevens tot snellere en kosteneffectievere onboarding van doelapplicaties binnen IGA-platforms. In deze blogpost richten we ons op de implementatie van de SCIM-serviceprovider-API. De SCIM-client-implementaties blijven buiten beschouwing. Meer achtergrond over het SCIM-protocol is te vinden op www.simplecloud.info.

Ik heb de afgelopen jaren tussen de veertig en vijftig SCIM 2.0 API-implementaties getest. Deze testen gaven een gevarieerd beeld met veel issues rond en afwijkingen van de SCIM-standaard. Op basis van al deze testen heb ik de meest voorkomende pitfalls/valkuilen rond de implementatie van SCIM 2.0-compliant API’s op een rij gezet:

  • Pitfall 1: Testen en troubleshooten met een generieke API IDE.
  • Pitfall 2: Aanpassingen aan het core schema.
  • Pitfall 3: Uitbreiden van het core schema zonder gebruik van schema-extensies.
  • Pitfall 4: Verwarring tussen de Id- en ExternalId-attributen.
  • Pitfall 5: Slecht geformeerde error response.
  • Pitfall 6: Ontbrekende of incorrecte metadata.
  • Pitfall 7: Ontbrekende configuratie-endpoints.
  • Pitfall 8: Het gebruik van PATCH als een (vereiste) methode om objecten te updaten.
  • Pitfall 9: Hoofdlettergevoeligheid.
  • Pitfall 10: Beheer van complexe of omvangrijke serviceprovider-autorisatiemodellen.

Voordat ik nader inga op de pitfalls, is het van belang op te merken dat veel inspanningen zijn te voorkomen (evenals de hier genoemde pitfalls) door de inzet van de Traxion SCIM Gateway. Deze API-front is volledig SCIM-compliant en maakt een applicatie ook SCIM-compliant, zonder de noodzaak om de API zelf te bouwen en onderhouden. Meer informatie over de Traxion SCIM Gateway is hier te vinden.

Pitfall 1: Testen en troubleshooten met een generieke API IDE

Het testen en troubleshooten van een SCIM-serviceprovider met een API IDE (Integrated Development Environment) is geen groot probleem, omdat je de ruwe verzoeken en responses kunt inspecteren. Maar deze tooling houdt geen rekening met SCIM 2.0-protocol-compliancy. Het is een veelvoorkomende fout om aan te nemen dat een SCIM API goed is getest als alle tests binnen de IDE goed verlopen. We hebben hier meteen de eerste en belangrijkste valkuil. Mijn advies in dit verband is dat serviceproviders hun SCIM API testen met een volledig SCIM-compliant testtool, zoals de door ons ontwikkelde Traxion SCIM Test Client. Optioneel is een webdebuggertool zoals Fiddler inzetbaar tussen de SCIM Test Client en de SCIM-serviceprovider. Dit biedt inzicht in de feitelijke requests die de SCIM-client verstuurt en de API-responses.

Pitfall 2: Aanpassingen aan het core schema

De SCIM 2.0-specificatie beschrijft een core schema. Hoewel dit core schema publiekelijk beschikbaar is, zien we toch nog veel ontwikkelaars die een schema van scratch proberen te ontwikkelen of het standaardschema ingrijpend veranderen. Dat leidt onder andere tot:

  • Ontbrekende attributen.
  • Hernoemde objecten en/of attributen.
  • Gewijzigde attribuuttypes.
  • Gewijzigde aanpasbaarheid, vereiste en/of read-only flags.
  • Droppen van canonical types.
  • Creëren van duplicaatattributen.

Al deze kleine fouten zorgen voor onverwacht gedrag dat geanalyseerd moet worden. Dat vraagt om kostbare tijd en vertraagt zo de implementatie. Het is daarom beter om een origineel SCIM 2.0-core schema te gebruiken. Wanneer sommige objecten en/of attributen niet door applicaties worden gebruikt, is het advies om deze gewoon leeg te laten en geen inkomende data voor deze attributen te verwerken. Het core schema is opgenomen in RFC7643.

Pitfall 3: Uitbreiden van het core schema zonder gebruik van schema-extensies

Wanneer aanvullende attributen nodig zijn, is het beter de User-, Group- en EnterpriseUser-schema’s niet aan te passen. Volgens de SCIM-specificaties moeten deze attributen niet worden toegevoegd binnen het core schema zelf, maar is het beter een schema-extensie te gebruiken. Kijk voor een voorbeeld naar de definitie van de EnterpriseUser-extensie en gebruik deze als een referentie voor je eigen extensie. Een voorbeeld van een attribuut dat vaak via een extensie wordt toegevoegd, is de categorie attribuut. Kijk voor meer informatie daarover bij RFC7643 (“3.3. Attribute Extensions to Resources”). Wanneer je extra resources beschikbaar moet maken, zoals een bedrijfsunit, volg dan RFC7643 (“3.2. Defining New Resource Types”).

Pitfall 4: Verwarring tussen de Id- en ExternalId-attributen

Er is soms sprake van verwarring over het verschil tussen de Id- en ExternalId-attributen, welk systeem voor welke attributen verantwoordelijk is en/of ExternalId-attributen opgeslagen moeten worden. We hebben voorbeelden gezien waar deze situatie leidde tot mismanagement van deze attributen. In de tabel een uitleg hoe dat kan gebeuren.

 

Attribuut Verantwoor-delijkheid Beschrijving
Id Service-provider Moet door de serviceprovider worden toegewezen bij het creëren van een resource. Elke resource moet een unieke en niet-aanpasbare id krijgen die voor alle resourcetypes uniek is. Het meest gebruikte format is een GUID.
ExternalId Klant Kan door de klant worden toegewezen en hangt af van de processen van de klant. Als er een id gespecifieerd is, moet deze opgeslagen worden in de datastorage van de serviceprovider. Een veelgebruikt voorbeeld is de identifier van een corresponderende identiteit in een Identity Governance & Administration-systeem (IGA).

 

Een voorbeeld van het gebruik van dit veld is een rejoiner-scenario. Een her-activatie van een soft-deleted account mag niet gebaseerd zijn op een gebruikersnaam of e-mailadres, omdat sommige bedrijven deze attribuutwaarden hergebruiken voor nieuwe gebruikers nadat de oude gebruikers het bedrijf hebben verlaten. Her-activatie moet gebaseerd zijn op een unieke en niet-aanpasbare ExternalId-waarde.

Pitfall 5: Slecht geformeerde error response

Bij het testen van SCIM-serviceproviders zien we veel slecht geformeerde error responses wanneer issues zich voordoen. De SCIM-specificatie schrijft voor hoe de error response eruit moet zien. Een veelvoorkomende fout in implementaties zijn niet-compliant error responses. Dan leveren SCIM-clients een algemene en niet-bruikbare error message, wat troubleshooten lastiger maakt. De vereiste definities voor error messages zijn te vinden in RFC7643 (“3.7.3. Response and Error Handling”).

Pitfall 6: Ontbrekende of incorrecte metadata

Het SCIM-protocol vereist dat elke resource bepaalde metadata krijgt toegewezen (zoals resourceType, created, lastModified, location, totalResults), die de serviceprovider terugmeldt. Het is een veelvoorkomende fout dat incorrecte metadata wordt teruggemeld, wat onverwacht gedrag veroorzaakt.

De meeste voorkomende fout hier is een incorrecte totalResults return-waarde op een gefilterde GET. Serviceproviders moeten het totale aantal objecten van een resourcetype terugmelden, niet alleen de resultaten van een gefilterde GET. Als het totale aantal objecten in een endpoint van een gebruiker 1912 is, en de gefilterde GET meldt “startIndex=151&count=50”, dan moet de totalResults return-waarde 1912 zijn en niet 50. Bekijk RFC7643 (“3.1. Common Attributes”) voor een beschrijving van alle vereiste metadata-types.

Pitfall 7: Ontbrekende configuratie-endpoints

De eerste dertig SCIM-connectors die we testten, waren alle specifiek voor een klant of een project ontwikkeld. Nu SCIM 2.0-complaint API-implementaties meer worden ingezet, testen we ook implementaties die al door andere SCIM-clients worden gebruikt. In de praktijk gaat het in de meeste gevallen om geïmplementeerde SCIM API’s die ontwikkeld zijn voor Azure AD-integratie.

Helaas vereist de Azure AD SCIM-component van Microsoft geen endpoints die volgens de SCIM-specificatie als verplicht zijn gedefinieerd. Veel van deze ontbrekende vereisten worden al besproken bij een andere valkuil. Niettemin lijken de meeste van deze implementaties de volgende drie vereiste configuratie-endpoints te missen:

  1. ServiceProviderConfig
    In deze endpoint definieert de serviceprovider compliance-specificaties en de types van authenticatie die zij naar de API ondersteunen (meest gebruikt is basic authentication, Bearer token authentication en Oauth 2.0 authentication). Authenticatie is niet voor dit endpoint vereist, in tegenstelling tot andere endpoints.
  2. ResourceTypes
    De serviceprovider definieert de ondersteunde resourcetypes in de ResourceTypes endpoint, zoals Users, Groups en alle schema-extensies. De meeste voorkomende fout hier is dat serviceproviders de vereiste vlag op ‘true’ zetten op niet-verplichte resourcestypes in de ResourceTypes-endpoint. Het beste voorbeeld hiervan is de eis van de EnterpriseUser-extensie als attributen van deze extensie niet ondersteund of vereist zijn. Ons advies is om altijd te checken of attributen in specifieke extensies vereist zijn om gebruikers te creëren. Alleen dan moet de requirement van de extensie op ‘true’ worden gezet.
  3. Schema’s
    Het endpoint waar de serviceprovider het volledige ondersteunde schema definieert. Zoals aangeraden in pitfall 2 en 3 heeft het implementeren van het core schema de voorkeur en vul je deze aan door het gebruik van schema-extensies.

Zonder deze drie discovery-endpoints zijn de meeste SCIM-implementaties onmogelijk, omdat de verbindende zijde nooit in staat zal zijn om alle variabelen en requirements van de serviceprovider op te halen.

Pitfall 8: Het gebruik van PATCH als een (vereiste) methode om objecten te updaten

Het SCIM-protocol beschrijft twee methoden om een resource te updaten:
1. Replace (PUT) vervangt de volledige resource door een nieuwere versie. De SCIM-client moet alle mogelijk te updaten attributen aanleveren tijdens de update-operatie.

2. PATCH updatet de resource naar een nieuwere versie met alleen de aangeleverde te updaten attributen. De SCIM-client moet ten minste één te updaten attribuut leveren tijdens de
update-operatie.

Methode 1 (Replace) moet door de serviceprovider worden geïmplementeerd. Methode 2 (patch) is optioneel. Onze ervaring met verschillende SCIM-implementaties op basis van Patch laat zien dat deze middelmatig tot slecht uitvallen. Dat komt vooral doordat wijzigingen die via PATCH zijn doorgevoerd niet goed verwerkt zijn. Het verwerken van dit type calls is complexer dan het vervangen van calls. Het kost veel troubleshooting en extra werk om dit goed werkend te krijgen.

Pitfall 9: Hoofdlettergevoeligheid

Alle informatie (van type “string”) die SCIM-implementaties naar de API van de serviceprovider stuurt, is hoofdlettergevoelig. Dat betekent dat de SCIM-serviceprovider de data op dezelfde manier moet opslaan en terugmelden als deze is aangeleverd. Als dat niet gebeurt, krijg je een nooit eindigende loop van requests naar de SCIM API. Deze verzoeken om de lettergrootte van bepaalde attributen aan te passen.

Pitfall 10: Beheer van complexe of omvangrijke serviceprovider-autorisatiemodellen

Door de groups endpoint te gebruiken, is een SCIM-implementatie normaal gesproken in volledige controle over alle autorisaties in een doelapplicatie. De serviceprovider kan naar deze autorisatietoewijzers verwijzen als groepen, autorisaties, rechten, rollen en meer. Niettemin verwijst SCIM slechts naar elk willekeurig iets dat een gebruiker elke mogelijke vorm van autorisatie als groep toekent.

Wanneer een serviceprovider beschikt over verschillende autorisatietoewijzers, is ons advies om een RBAC-model van groepen te implementeren dat via de SCIM-endpoint te beheren is. Wanneer dat nog steeds leidt tot een complexe set of een hoog aantal groepen, is het advies een categorie-achtig attribuut toe te voegen aan de groeps-endpoint. Het gebruik daarvan maakt het makkelijk om groepen binnen het IGA-systeem te creëren, waardoor je het beheer vergemakkelijkt. Ons advies is om niet meer dan twintig groepen aan een enkele categorie toe te voegen.

Conclusie

Het is duidelijk dat de bovengenoemde fouten bij het implementeren van SCIM goed te voorkomen zijn. Serviceproviders doen er in dat verband goed aan om een SCIM-specifieke testtool te gebruiken, zoals de Traxion SCIM Test Client waarmee de API volledig te testen is.

Hoewel de Test Client op Windows is gebaseerd, is het mijn aanbeveling om te investeren in een Windows-systeem dat de Test Client ondersteunt. Dit bespaart veel moeite tijdens de implementatie van de API, wat resulteert in een kortere doorlooptijd en lagere kosten.

Daarnaast biedt Traxion met de Traxion SCIM Gateway een API-front die volledig SCIM-compliant is en applicaties compliant maakt zonder de noodzaak van het zelf bouwen en onderhouden van een API.  Meer informatie over de gateway is hier te vinden.

Over de auteur

Paul van Gool werkt als consultant bij Traxion met als specialisatie de integratie van IGA-platforms met doelapplicaties op basis van SCIM en andere protocollen en standaards. Heb je vragen over dit onderwerp? Neem contact met ons op, wij helpen je graag verder.

 

 

 

Confidental Infomation