Keycloak .NET Adapter
Wie Sie die Keycloak Authentifizierungs-Funktionen auch in Microsoft® Visual Studio und .NET-Umgebungen nutzen.
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“.
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.
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
DIESER ABSCHNITT WIRD ÜBERARBEITET, DA DER INHALT NICHT MEHR AKTUELL IST. BITTE MELDEN SIE SICH DIREKT BEI UNS, FALLS SIE FRAGEN DAZU HABEN.
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, .NET-Experte und ehemaliger Software-Entwickler bei der Syntlogo GmbH stellte den Kontakt zu ihm her und erhielt die Maintainer-Rechte für das Repository. 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.
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, ehemaliger 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