Wie man eine SCIM 2.0 Server-Konfiguration von Hand erstellt

SCIM 2.0 Server-Konfiguration manuell erstellen

RFCs sind berüchtigt schwer verständlich und die korrekte Umsetzung in JSON-Dokumente für die Service-Discovery-Endpunkte /ServiceProviderConfig, /ResourceTypes und /Schemas kann fehleranfällig und interpretationsbedürftig sein. Wenn Sie mit SCIM noch nicht vollständig vertraut sind, empfiehlt es sich, zunächst eine Einführung in SCIM und dessen praktische Funktionsweise zu lesen, bevor Sie tiefer in die technischen Details einsteigen.

RFC 7643 liefert die Core-Schemas in JSON-Form, enthält jedoch Fehler, die vor der Nutzung korrigiert werden müssen. Es gibt Tools, die SCIM und bestehende REST-APIs verbinden (SCIM-Bridges), aber wenn Sie nur die Service-Konfiguration für Ihre Anwendung benötigen, können Sie dies manuell erledigen.

Was muss ich unterstützen?

Praktisch müssen Sie mindestens Folgendes unterstützen:

• Den Core-Ressourcentyp User mit dem Core-Schema User.

• Den Core-Ressourcentyp Group mit dem Core-Schema Group.

Der SCIM-Standard erlaubt Ihnen, Ihre Ressourcen vollständig zu inividualisieren, was jedoch die Interoperabilität beeinträchtigen würde.

In der Praxis sind diese beiden Ressourcentypen essenziell. Für jede Ressource müssen Sie die Common-Attribute id, externalId und meta mit ihren Unterattributen – außer dem optionalen meta.version – unterstützen.

Attribute für den User

Der User muss mindestens das Attribut userName enthalten. Es wird dringend empfohlen, active und password zu unterstützen, sofern Ihr Service diese Funktionalität bietet.

Wenn es technisch möglich ist, alle Mitgliedschaften eines Benutzers zu bestimmen, sollten Sie auch das Attribut groups mit seinen Unterattributen unterstützen. Füllen Sie groups.display mit dem displayName der jeweiligen Gruppe.

Beachten Sie, dass das Unterattribut groups.type eine andere Bedeutung hat als sein Gegenstück im Attribut members in der Gruppe. Wenn Sie keine impliziten Mitgliedschaften haben, setzen Sie es auf „direct“ statt das Attribut wegzulassen. Das macht es Clients einfacher. Vergessen Sie nicht, canonicalValues für groups.type im Schema so anzupassen, dass nur „direct“ enthalten ist.

Die Unterstützung weiterer Attribute ist optional.

1. Laden Sie die Schema-Definition herunter. Verwenden Sie unsere korrigierte Schema-Definition statt des im RFC 7643 enthaltenen Schemas, da letzteres bekannte Fehler enthält, die noch manuell korrigiert werden müssen.

2. Gehen Sie die Schemas und deren Attribute einzeln durch und erstellen Sie eine erste Zuordnung zu den Attributen Ihrer Anwendung.

3. Prüfen Sie alle zugeordneten Attribute in RFC 7643 und verifizieren Sie deren Bedeutung. Verwenden Sie niemals Attribute mit abweichender Bedeutung vom Standard. Passen Sie Ihre Zuordnungstabelle gegebenenfalls an.

4. Analysieren Sie Abhängigkeiten zwischen Attributen, die Sie über SCIM bereitstellen wollen, und vermeiden Sie diese möglichst. RFC 7643 definiert einige Abhängigkeiten (z. B. zwischen $ref und value), die von Clients erwartet werden. Aber es ist nicht möglich, in SCIM-Schemas weitere Abhängigkeiten zu definieren, und diese könnten die Interoperabilität beeinträchtigen. Ein Client kann solche Abhängigkeiten nicht vorhersehen, sondern nur auf Ergebnisse reagieren – und das möglicherweise nicht wie erwartet. Angenommen ein Attribut könnte nicht geändert werden, solange ein anderes boolesches Attribut gesetzt ist. Ihr Service könnte die Operation entweder ablehnen oder sie erfolgreich ausführen, ohne den Wert zu ändern. Egal wofür Sie sich entscheiden würden, in beiden Fällen wäre Benutzbarkeit schlecht. Beispiele für Abhängigkeiten:

   • Ihre Anwendung verlangt, dass Clients eines von zwei Attributen angeben.

   • Das Setzen eines Attributs hängt vom Wert eines anderen ab.

   • Das Ändern eines Attributs bewirkt Änderungen in einem anderen.

5. Entfernen Sie nicht unterstützte Attribute und Unterattribute aus dem Core-User-Schema.

6. Überprüfen Sie die verbleibenden Attribute, kontrollieren Sie deren Eigenschaften und passen Sie diese an. Ändern Sie name oder type eines Attributs nicht.

7. Wenn Sie noch Attribute ohne SCIM-Gegenstück haben, prüfen Sie das Enterprise User-Schema.

8. Erstellen Sie eigene Schema-Erweiterungen falls nötig. Verwenden Sie die im SCIM-Standard definierten Unterattribute für bessere Interoperabilität: type, primary, display, value, $ref.

9. Nutzen Sie unseren SCIM 2.0 Schema Checker zur Validierung Ihres Ergebnisses.

Attribute für die Group

Die Group muss die Attribute displayName und members mit deren Unterattributen enthalten. Beachten Sie, dass members.type eine andere Bedeutung hat als sein Gegenstück im Attribut groups im User. Wenn nur User Mitglieder Ihrer Gruppen sein können, setzen Sie es fest auf „User“ anstatt das Attribut wegzulassen. Das macht es Clients einfacher. Vergessen Sie nicht, canonicalValues für members.$ref und members.type im Schema so anzupassen, dass nur „User“ enthalten ist.

Ressourcentyp und Service Provider-Konfiguration

Die Definition für Ressourcentypen und Service-Provider-Konfiguration ist unkompliziert. Laden Sie die JSON-Dateien herunter, die wir für Errata im RFC korrigiert haben, und passen Sie diese nach Bedarf an.

Service-Discovery-Konfigurationsdefinitionen

Sie können entweder Definitionen für die Konfigurationsressourcen ServiceProviderConfig, ResourceType und Schema an den Endpunkten /ResourceTypes und /Schemas bereitstellen oder sie komplett entfernen. Die zweite Option ist einfacher. Erwarten Sie nicht, dass Clients auf Änderungen in diesen Definitionen reagieren, da sie nicht selbsterklärend genug sind.

Ein Kommentar zu den technischen Details des SCIM-Standards

Über 96% aller SCIM-Service-Provider nutzen SCIM 2.0, die aktuelle Version, definiert durch:

1. RFC 7642 ist informativ und „legt die Konzepte, Modelle und Abläufe des Systems dar und enthält Benutzerszenarien, Anwendungsfälle und Anforderungen.“

2. RFC 7643 ist die technische Spezifikation für das „Schema- und Erweiterungsmodell zur Darstellung von Benutzern, Gruppen und anderen Ressourcentypen.“

3. RFC 7644 ist die technische Spezifikation des SCIM-Protokolls für den Datenaustausch.

RFC 7643 schlägt eine Reihe von Unterattributen für komplexe Attribute vor, was zu konsistenter Benennung und Nutzung durch Service-Provider führt (Abschnitt 2.4):

• type

• primary

• display

• value

• $ref

Dies ist ein effektiver und nützlicher Ansatz, der auch auf Ressourcen hätte angewendet werden können. Jeder Ressourcentyp sollte eine menschenlesbare ID haben, wie userName im Core-User, und ein Anzeigeattribut. Der Core-User hat ein displayName-Attribut mit derselben Bedeutung und Semantik wie display. Das displayName-Attribut der Core-Gruppe hat leicht abweichende Semantik: Es ist nicht unique wie display, aber required, was darauf hindeutet, dass es auch als menschenlesbare ID dienen sollte.

Die grundlegende Verbesserung von SCIM 2.0 gegenüber früheren Versionen ist die Einführung der /ResourceTypes- und /Schemas-Discovery-Endpunkte, die SCIM erweiterbar und flexibel machen. Die Trennung von Ressourcentyp- und Schema-Definitionen erlaubt die Nutzung eines einzelnen Schemas für mehrere Ressourcentypen. Obwohl dies sinnvoll erscheint, wird in der Praxis immer eine 1:1-Zuordnung verwendet.

Daher würde das Einbetten der Schema-Definition in den Ressourcentyp die Dinge vereinfachen und den Bedarf an Schema-Erweiterungen eliminieren. Das würde sogar für die Core-Ressourcen funktionieren. Das RFC sagt: „Wo erlaubt, können einzelne Werte und Schemas geändert werden,“ setzt aber kaum Grenzen. Dadurch können Core-Schemas nahezu uneingeschränkt geändert werden und einige Service-Provider fügen bereits Attribute zu den Core-Schemas hinzu.

Mehrdeutigkeiten im SCIM-RFC

RFC 7643 enthält eine erhebliche Menge an Ungenauigkeiten, mehr als für RFCs üblich. Das auffälligste Beispiel ist die ungenaue Verwendung von Schlüsselwörtern wie REQUIRED und OPTIONAL. Ein Attribut kann z. B. die Eigenschaft „required: true“ haben, deren Bedeutung in RFC 7644 definiert ist: Ein Client muss für solche Attribute beim Ersetzen einer Ressource einen Wert angeben. Das ist nicht dasselbe wie das REQUIRED-Schlüsselwort aus RFC 2119. Dennoch setzt RFC 7643 die Attribut-Eigenschaft und das Schlüsselwort in Abschnitt 2.2 gleich, folgt dem aber nicht konsequent. Im gesamten RFC 7643 scheinen sowohl das Schlüsselwort als auch die Attribut-Eigenschaft zu bedeuten, dass Attribute einen Wert haben müssen, was wiederum nicht dasselbe ist wie die Verpflichtung des Clients, einen Wert bereitzustellen.

Dadurch haben viele schreibgeschützte Attribute die required-Eigenschaft gesetzt und viele Attribute sind als REQUIRED gekennzeichnet, obwohl sie nicht unterstützt werden müssen. Die einfachste Interpretation des REQUIRED-Schlüsselworts für Attribute wäre, die Unterstützung des Attributs zu verlangen, d. h. es muss möglich sein, dass das Attribut einen Wert hat. Jeder konforme Server muss es im Schema enthalten und Clients müssen damit umgehen können.

In diesem Sinne ist das id-Attribut REQUIRED. Aber wie steht es um externalId? Muss ein Server das Attribut externalId unterstützen, um standardkonform zu sein? Server können die Unterstützung für gemeinsame Attribute nicht deklarieren, da sie immer implizit im Schema enthalten sind. RFC 7643 sagt in Abschnitt 3.1: „Gemeinsame Attribute gelten als Teil jedes Basisressourcen-Schemas.“ Das legt nahe, dass sie unterstützt werden müssen, da sie Teil des Schemas sind. Einige Service-Provider unterstützen externalId jedoch nicht und argumentieren, das RFC sage: „Dieses Attribut ist OPTIONAL.“ Wahrscheinlich soll dies aber nur klarstellen, dass externalId keinen Wert haben muss und die required-Eigenschaft nicht gesetzt ist. Das wäre eine Ausnahme zur vorangehenden Aussage: „Mit Ausnahme der Server-Discovery-Endpunkte /ServiceProviderConfig und /ResourceType und deren zugehörige Ressourcen MÜSSEN diese Attribute für alle Ressourcen definiert sein.“ Hier scheint definiert sein wieder nur einen Wert haben zu bedeuten, da Abschnitt 5 sagt, dass die Common-Attribute auch dem Base-Schema der ServiceProviderConfig-Ressource hinzugefügt werden.

Das zentrale Attribut in SCIM ist id. Ohne dieses würde SCIM nicht funktionieren: Jede Ressource kann direkt durch Anhängen ihrer id an den Endpunkt aufgerufen werden, auch wenn dies nicht explizit im RFC steht. Jede Ressource? Nein, eine unbeugsame Ressource wird über ihr name-Attribut statt id referenziert: ResourceType. Diese Inkonsistenz ist nicht nur akademisch – ein Client muss den Ressourcentyp prüfen, um das Basisschema einer Ressource zu bestimmen, wie im RFC beschrieben. Dieses Verfahren hätte vermieden werden können, wenn die Ressource einfach angegeben hätte, welches ihrer Schemas das Basisschema ist.

Benötigt der SCIM-Standard ein Update?

RFC 7643 ist oft vage und schwer zu interpretieren. Eine aktualisierte Version, etwa SCIM 2.1, wäre wertvoll.

Verbesserungen könnten sein:

• Überprüfung und Korrektur aller RFC 2119-Schlüsselwörter, insbesondere in RFC 7643.

• Klarstellung der Unterscheidung zwischen readWrite und writeOnly. Die Werte implizieren Unterschiede in der Lesbarkeit, die der returned-Eigenschaft widersprechen können. Der Wert writeOnly könnte auch einen sicherheitskritischen Wert implizieren, der nicht geloggt werden sollte. Dies wäre aber besser durch eine neue, eigenständige sensitivity-Eigenschaft abgedeckt (z. B. default, personal, secret).

• Klarstellung der Rolle des id-Attributs für den Ressourcenabruf.

• Für jedes Attribut klarstellen, ob es unterstützt werden und ob immer ein Wert definiert sein muss.

• Um die Eigenschaften der Core-Attribute festzulegen, sollten Schema-Definitionen verwendet werden. Das wäre klarer und präziser.

• Bedeutung der required-Eigenschaft klarstellen. Clients sollten Werte für solche Attribute beim Erstellen oder Ersetzen von Ressourcen angeben müssen, nicht nur beim Ersetzen.

• Klar zwischen Verpflichtungen für Server und Clients unterscheiden.

• Festlegen, welche Schema-Teile geändert werden dürfen oder nicht.

• Zirkuläre Definitionen durch sinnvolle ersetzen (z. B. in RFC 7643 für required und changePassword).

• Bedeutung der Eigenschaft „uniqueness“: „server“ klarstellen und Durchsetzung verlangen.

• Ein Attribut zu Ressourcen hinzufügen, das ihr Basisschema angibt.

• Attributnamen für menschenlesbare IDs und für Anzeigezwecke für alle Ressourcen empfehlen und eine solche ID im Group-Schema ergänzen.

• Veraltete kanonische Werte aus dem ims-Attribut entfernen.

Bei diesen Verbesserungen blieben die meisten Service-Provider und Clients kompatibel, während neue Implementierungen leichter zu entwickeln wären. Eine andere Frage ist, ob es Zeit wäre, mit der Entwicklung eines SCIM-3.0-Standards zu beginnen, was inkompatible Änderungen erlauben würde. Es gibt zwar einige mögliche Änderungsbereiche, aber keiner scheint relevant genug, um den Aufwand zu rechtfertigen, den die Umstellung für die meisten Service-Provider und Clients bedeuten würde.