Keycloak .NET Adapter

Wie Sie die Keycloak Authentifizierungs-Funktionen auch in Microsoft® Visual Studio und .NET-Umgebungen nutzen.

In diesem Artikel zeigen wir Ihnen, wie man eine Instanz von Keycloak installiert, die Seiten aus einer ASP.Net MVC-Anwendung absichert. Diese verwendet die Web-API MVC Anwendung als Backend.

Keycloak

Keycloak ist eine Open-Source-Lösung für Identity und Access Management, die auf die Entwicklung moderner Anwendungen und Services ausgerichtet ist. Keycloak macht es einfach, die Authentifizierung an Anwendungen und Diensten mit wenig bis gar keinem Code sicher zu implementieren.

Der Hauptunterschied zwischen Keycloak und anderen Lösungen besteht darin, dass es sich bei Keycloak um ein eigenständiges Produkt und nicht nur um eine Library handelt. Das bedeutet, dass die Software eigenständig lauffähig ist. Wenn Sie eine Vielzahl von Anwendungen und Systemen haben, die mit verschiedenen Technologien erstellt wurden, und die Authentifizierung und Autorisierung zentralisieren möchten, ist Keycloak eine sichere und sehr gute Wahl. Keycloak ist funktional sehr umfangreich und multi-mandantenfähig. Die anwenderfreundliche SSO-Lösung bietet eine leicht bedienbare Benutzeroberfläche.

Um Keycloak mit Anwendungen und Systemen zu integrieren, gibt es standardmäßig eine ganze Reihe von sog. „Client Adaptern“.

p

Was sind Keycloak Client Adapter?

Keycloak Client Adapter sind Bibliotheken, die es sehr einfach machen, die Authentifizierung an Anwendungen und Diensten mit Keycloak sicher durchzuführen. Wir nennen sie daher „Adapter“ und nicht „Library“, da sie eine enge Integration mit der zugrunde liegenden Plattform und dem Framework ermöglichen. Dies macht die Nutzung der Keycloak Client Adapter einfach und sie benötigen deutlich weniger Code als das, was normalerweise von einer Library benötigt wird.

Bevor wir den Keycloak .NET Adapter genauer beschreiben, beginnen wir zuerst mit der Installation von Keycloak.

Installation von Keycloak

Keycloak wurde mit Java und dem Java-Applikationsserver Wildfly entwickelt. Dazu gibt es eine sehr umfassende Installationsanweisung, die in der Dokumentation beschrieben wird. In unserem Beispiel wollen wir uns auf einen schnell verfügbaren, Docker-basierten Testserver fokussieren, auf dem wir zügig unsere ersten Beispielanwendungen entwickeln wollen.

Wir werden hier nicht erklären, wie man Docker installiert, das geht ziemlich straight forward. Gehen Sie auf die Docker-Homepage, wenn Sie Hilfe benötigen. Wir nehmen einfach an, dass Sie bereits Docker auf Ihrem Rechner installiert haben und er korrekt funktioniert.

Es gibt eine ganze Reihe von Docker-Images auf der Docker Webseite. Wir werden das offizielle „Standard-Paket“ nutzen, welches im Grunde genommen eine sofort einsatzbereite Keycloak-Installation beinhaltet, inklusive einer Datenbank und allem anderen. Sie können ein paar Umgebungsvariablen übergeben, mit denen Sie das Admin-Konto direkt erstellen können, da standardmäßig keines erstellt wird.

docker run --name keycloak -p 8080:8080 -e KEYCLOAK_USER= -e 
KEYCLOAK_PASSWORD= jboss/keycloak

Dadurch wird Keycloak auf dem Port 8080 des Host-Computers eingebunden. Sobald die Maschine gestartet ist, öffnen Sie Ihren Browser und gehen Sie zu localhost:8080. Es sollte die Startpage von Keycloak angezeigt werden.

Anmerkung: Wie würden nicht empfehlen, diese Keycloak-Installation im Produktionsbetrieb zu verwenden, da es keinerlei Redundanzen und kein Backup gibt. Sprechen Sie uns gerne an, wenn Sie dazu Fragen haben.

Keycloak Standard Admin-Oberfläche

Klicken Sie auf den Link Administrationskonsole und melden Sie sich mit der Kombination aus Benutzername und Passwort an, die Sie im Docker run-Befehl festgelegt haben. Sie sollten nun die Administrationsseite von Keycloak sehen.

Damit ist Ihre Keycloak-Instanz funktionsfähig und einsatzbereit.

Keycloak Standard Admin-Oberfläche

Konfiguration von Keycloak

Wir werden in diesem Artikel nicht allzu tief auf die Konfiguration von Keycloak eingehen. Das Einzige, was notwendig ist, um unsere Anwendung zu sichern, ist die Erstellung eines Clients.

Klicken Sie dazu auf die Option Clients im linken Menü. Es wird eine Liste einiger vordefinierter Clients angezeigt. Klicken Sie oben rechts auf die Schaltfläche Create. Wählen Sie im angezeigten Menü einen Namen, z.B. Demo-App, und behalten Sie das Client-Protokoll als OpenID Connect.

Stellen Sie dann sicher, dass Sie eine gültige Redirect-URL konfigurieren. Zur Vereinfachung fügen Sie * hinzu, um jede Redirect-URL zuzulassen. Aktivieren Sie auch „implicit flow“, indem Sie das Kontrollkästchen aktivieren.

Menüpunkt Clients (links) in der Keycloak Standard Admin-Oberfläche

Erstellen der Asp.NET MVC Anwendung

Das Erstellen einer neuen ASP.NET MVC-Anwendung erfolgt in Microsoft Visual Studio mit dem Assistenten für neue Projekte.

Dann wählen wir den Projekttyp, damit Visual Studio das Projektverzeichnis mit den notwendigen Dateien erstellen kann.

Keycloak .NET Adapter

Keycloak wurde vollständig in Java entwickelt. Sie können Keycloak  jedoch auch verwenden, um die Authentifizierung an Anwendungen und Systemen sicher durchzuführen, die in beliebigen Programmiersprachen entwickelt wurden. Das funktioniert solange es einen Adapter gibt, der die Verbindung verwaltet.

Die am häufigsten verwendeten Adapter sind die Java-Adapter, die von Red Hat unterstützt werden. Keycloak kann jedoch auch mit ASP.NET MVC-Webanwendungen eingesetzt werden. Es gibt nur einen von der Community entwickelten Adapter für .NET-Anwendungen von Dylan Plecki. Der Adapter beinhaltete einige Fehler. Zudem ging aus den im Github-Repository geposteten Problemen hervor, dass er seit langem nicht mehr gepflegt wird.

Im November 2017 gab der Entwickler des Adapters bekannt, dass er einen Maintainer sucht. Dieser sollte die Wartung des Adapters übernehmen, weil er selbst keine Zeit mehr dafür fand.

Joseph Boctor, Software-Entwickler und .NET-Experte bei der Syntlogo GmbH hat den Kontakt zu ihm hergestellt und die Maintainer-Rechte für das Repository erhalten. Zu diesem fügte er direkt 2 Bug-Fixes hinzu für die Fehler, mit denen er bisher konfrontiert war.

Leider konnte er das NuGet-Paket, das erstellt wurde, nicht aktualisieren, da er den API-Schlüssel vom Nuget.org-Konto des ursprünglichen Entwicklers nicht hatte.

Also hat H. Boctor das Software-Repository geteilt. Er hat ein eigenes Konto auf nuget.org erstellt, damit er das aktualisierte Paket ohne Fehler hochladen konnte. Er benannte das Paket anders, um zwischen der ursprünglichen und der gefixten Version zu unterscheiden.

p

Login Alliance / Syntlogo GmbH entwickelt den Keycloak .NET Adapter weiter und bietet professionellen Support an

Da sowohl Keycloak als auch .NET zwei gefragte Plattformen sind, engagiert sich H. Boctor, Software-Entwickler bei der Syntlogo GmbH, in dem Open-Source Projekt. Und ist mittlerweile der primäre Maintainer des Keycloak .NET Adapters.

Die in der Zwischenzeit durchgeführten Bug-Fixes und funktionalen Erweiterungen werden – für die Community frei zugänglich – hier zur Verfügung gestellt:

Integration des Keycloak .NET Adapters

 

Der erste Schritt ist die Integration des Adapters in Ihre Lösung über die Nuget Package Manager Konsole in Visual Studio.

Installation des KeyWin Keycloak .NET Adapter

Dann fügen wir die Bibliotheken zur Datei startup.cs und verbinden diese mit Keycloak.

Wichtige Elemente sind der Client-Name, das Secret, der Realm-Name von Keycloak und die URL des Keycloak-Servers.

Verbindung zum Keycloak .NET Adapter

Nachdem wir die Verbindung zu Keycloak konfiguriert haben, müssen wir der Anwendung noch mitteilen, welche Benutzer sich einloggen können und welche Rollen sie erhalten sollen. Dafür können wir in den Controller-Klassen suchen, wo wir jedem Action Result eine eigene Rolle geben können. Meldet sich der Benutzer an, werden ihm die entsprechenden Rollen zugewiesen.

Rollenzuweisung in Keycloak .NET Adapter