Keycloak: Beliebiges User-Attribut im JWT ausgeben

In diesem Beitrag beschreibe ich, wie man in Keycloak ein beliebiges Attribut einem User hinzufügt und dieses dann in das JWT (JSON Web Token) ausgibt. Dies kann nützlich sein, um im Rahmen der Software-Entwicklung Daten zu fingieren oder um durch zusätzliche, manuell gesetzte Attribute den Funktionsumfang der eigenen Software aufzubohren.

Um in Keycloak einem User ein beliebiges Attribut zu ergänzen, sucht man zunächst den betreffenden User im Bereich Users. Hat man den entsprechenden User aufgerufen, wechselt man auf den Reiter Attributes. Ggf. werden hier bereits automatisch ergänzte Attribute angezeigt. Um ein beliebiges, statisches Attribut zu ergänzen, klickt man auf Add an attribute und füllt die Felder Key und Value und klickt anschließend aus Save.

Ein beispielhafter Eintrag könnte wie folgt aussehen:

Key	Value
city	Cologne

Dieses manuell ergänzte Attribut am User kann nachträglich noch beliebig verändert werden. Bedenke aber bitte, dass es beim Wert des Keys auf die exakte Groß- und Kleinschreibung ankommt, damit dieses Attribut später genutzt werden kann (also nicht city mit City verwechseln ;)).

User-Attribut an JWT übergeben

Nun, da das User-Attribut ergänzt ist, müssen wir definieren, dass das zusätzliche Attribut auch im JWT ausgegeben wird. Ohne diesen Schritt ist das Attribut zwar generell definiert, wird aber nicht weitergereicht!

Hierfür wechseln wir zu Client scopes (Pfeil 1) und klicken in der Auflistung auf profile. Dort wechseln wir dann auf den Reiter Mappers (Pfeil 3).

Als nächstes musst du auf dem Button Add mapper aus dem Dropdown By configuration auswählen (Pfeil 4).

Nun öffnet sich ein neuer Dialog, in welchem dir verschiedene „mappings“ zur Auswahl angeboten werden. Um ein beliebiges User-Attribut im JWT auszugeben, wählst du User Attribute.

Im Anschluss hieran öffnet sich ein weitere Dialog, in welchem du nun noch die Angaben zu dem im ersten Schritt von dir definierten, individuellen User-Attribut machen musst. Beachte bitte unbedingt, dass es auf die exakte Groß- und Kleinschreibung ankommt. Ein city entspricht in diesem Kontext nicht einem City!

Ich versuche im Kontext solcher „durchgereichten Informationen“ in Keycloak, wenn möglich, einheitliche Namen zu nutzen, um nicht durch sonst deutlich leichtere Fehler in einem solchen Mapper unnötig auf Fehlersuche gehen zu müssen. Für den folgenden Screenshot und das Beispiel „city“ würde dies bedeuten:

Name*	city
User Attribute	city
Token Claim Name	city

Alle Angaben sind also sowohl einheitlich klein geschrieben, als auch wörtlich identisch, sofern möglich!

In dem von mir beschriebenen Beispiel, musst du keine Einstellungen verändern, sondern kannst die Default-Werte übernehmen.

Als Ergebnis solltest du nun das User-Attribut city im JWT nach erfolgreichem Login mitgegeben bekommen (also key: city und value: Cologne)!