Keycloak für OIDC-Authentifizierung einrichten (Grundkonfiguration)

Diese Aufgabe beschreibt, wie Keycloak als OpenID Connect (OIDC) Authentifizierungsanbieter für WinCC OA in der Grundkonfiguration eingerichtet wird.

Keycloak ist eine Open-Source-Lösung für Identitäts- und Zugriffsmanagement. Diese Anleitung erklärt, wie Sie Keycloak für die OIDC-Authentifizierung einrichten, die als sichere Anmeldemethode für die WinCC OA Benutzeroberfläche in der Grundform verwendet werden kann. Für erweiterte Konfigurationen oder Informationen zur Vorbereitung von Keycloak für den Einsatz in Produktionsumgebungen konsultieren Sie bitte die offizielle Keycloak-Dokumentation. Relevante Links finden Sie am Ende dieser Schritt-für-Schritt-Anleitung.

  1. Installieren Sie OpenJDK 21 oder neuer.

    Keycloak benötigt OpenJDK 21 oder eine neuere Version. Stellen Sie vor der Installation von Keycloak sicher, dass die richtige Java-Version auf Ihrem System installiert ist.

    Anmerkung:
    Sie können Ihre installierte Java-Version mit java -version in der Eingabeaufforderung oder im Terminal überprüfen. Falls Sie Java installieren oder aktualisieren müssen, laden Sie es von der offiziellen OpenJDK-Webseite herunter.
  2. Laden Sie Keycloak herunter und installieren Sie es.

    Laden Sie den aktuellen Keycloak-Server von der offiziellen Keycloak-Downloadseite herunter. Entpacken Sie die Datei und starten Sie Keycloak mit dem passenden Skript für Ihr Betriebssystem aus dem entpackten Keycloak-Paket:

    • Windows
    • Linux
    bin\kc.bat start-dev
    bin/kc.sh start-dev

    Siehe: Getting Started Guide

    Anmerkung:
    Beachten Sie, dass dieser Befehl Keycloak im Entwicklungsmodus startet. Für Produktionsumgebungen muss stattdessen der Parameter start verwendet werden. Weitere Informationen zur Einrichtung von Keycloak für Produktionsumgebungen finden Sie in der offiziellen Keycloak-Dokumentation: Keycloak konfigurieren – Starten im Produktionsmodus
  3. Greifen Sie auf die Keycloak Admin-Konsole zu.

    Öffnen Sie http://localhost:8080 in Ihrem Browser. Klicken Sie auf Administration Console und erstellen Sie den initialen Admin-Benutzer wie angegeben. Melden Sie sich mit Ihren Admin-Zugangsdaten an.

    Siehe: Server Administration Guide

  4. Erstellen Sie einen neuen Realm.

    Wählen Sie in der Admin-Konsole das Realm-Dropdown-Menü und klicken Sie auf Create Realm. Geben Sie einen Namen ein (z. B. winccoa-realm) und klicken Sie auf Create.

    Siehe: Realms

  5. Erstellen Sie einen Client für Ihre Anwendung.

    Gehen Sie zu Clients > Create Client. Geben Sie eine Client-ID ein (z. B. winccoa-client), wählen Sie OpenID Connect als Protokoll und klicken Sie auf Next.

    Siehe: Clients

  6. Konfigurieren Sie die Client-Funktionen.
    • Stellen Sie sicher, dass der Authentifizierungsablauf Standard Flow aktiviert ist.

    Fahren Sie mit der Konfiguration fort, indem Sie auf Next klicken.

    Siehe: OIDC Clients

  7. Legen Sie die Root-URL auf die Basis-URL Ihrer Anwendung fest (z. B. http://localhost) und klicken Sie auf Save, um die Client-Konfiguration abzuschließen.
  8. Optional: Wenn Sie das ULC UX verwenden, fügen Sie alle Ihre verfügbaren Webserver zur Liste Valid Redirect URIs mit den vollständigen Domainnamen im Format https://<hostname als FQDN>:<port>/oidcCodeVerification hinzu.
  9. Optional: Wenn Sie das Mobile UI Applikation verwenden, fügen Sie die URL winccoaui.siemens.com://oauth2redirect zur Liste der Valid Redirect URIs hinzu.
  10. Erstellen Sie einen Benutzer zum Testen der Authentifizierung.

    Gehen Sie zu User > Add User. Geben Sie einen Benutzernamen ein, z. B. myuser, und alle erforderlichen Felder, dann klicken Sie auf Save.

    Siehe: Users

    Anmerkung:
    Um mögliche Konflikte zwischen WinCC OA-Benutzerkonten und in Keycloak erstellten Benutzern zu vermeiden, wird empfohlen, eindeutige Namen für Keycloak-Benutzer zu verwenden.
  11. Gehen Sie zum Tab Credentials Ihres neuen Benutzers und legen Sie ein Passwort fest.
  12. Integrieren Sie Keycloak in Ihre WinCC OA-Anwendung.

    Konfigurieren Sie Ihr Projekt für die Verwendung von OIDC, siehe OIDC-Authentifizierung für WinCC OA Projekt konfigurieren für die notwendigen Konfigurationsschritte.

  13. Testen Sie den Authentifizierungsablauf.

    Starten Sie Ihr Projekt und die Benutzeroberfläche, um eine Anmeldung zu initiieren. Sie sollten zur Keycloak-Anmeldeseite weitergeleitet werden. Melden Sie sich mit dem erstellten Benutzer an. Nach erfolgreicher Authentifizierung startet die Benutzeroberfläche mit Ihren Benutzerdaten.

Keycloak ist nun als OIDC-Provider für WinCC OA eingerichtet. Für erweiterte Konfigurationen (Rollen, Gruppen, Mappings usw.) siehe die Keycloak-Dokumentation.