Dokument History

Version	Datum	Autor	Erläuterung
0.1	10.01.2025	Fillinger	Grobe Erstellung Aufbau
0.2	15.01.2025	Walther	Einleitung + Features
0.3	17.01.2025	Fillinger	Sequenz Diagramme
0.4	18.01.2025	Walther	Setup / Startanleitung
0.5	19.01.2025	Brachwitz	ER Diagramm
0.6	19.01.2025	Brachwitz	Frontend Dokumentation
1.0	21.01.2025	Walther	Überarbeitung Inhalte

1 Einführung

Das Projekt ist eine Enterprise-Anwendung, die sich auf die Verwaltung und Ausführung von Ansible Playbooks spezialisiert. Ziel ist es, eine zugängliche und leistungsstarke Lösung bereitzustellen, insbesondere für Nutzer, die von den Vorteilen von Ansible profitieren möchten, jedoch nicht über die nötigen technischen Kenntnisse verfügen, um Server eigenständig zu konfigurieren.

Die Hauptziele des Projekts sind:

1. Bereitstellung einer benutzerfreundlichen Oberfläche
   Ansible ist zwar ein mächtiges Tool, aber der Einstieg kann für weniger erfahrene Nutzer herausfordernd sein. Das Projekt bietet eine intuitive Benutzeroberfläche, die es ermöglicht, Ansible Playbooks einfacher zu verwalten und auszuführen. So können auch Nutzer ohne tiefgehende technische Expertise komplexe Serverkonfigurationen umsetzen.
2. Sichere, aber einfache Login-Optionen
   Das System gewährleistet eine einfache und sichere Anmeldung durch die Integration eines Single-Sign-On (SSO)-Systems mit Keycloak. Zusätzlich wird eine Zwei-Faktor-Authentifizierung (2FA) angeboten, um die Sicherheit weiter zu erhöhen.
3. Trennung von Webserver und Playbook-Ausführung
   Um die Sicherheit zu maximieren, werden die Komponenten für die Weboberfläche und die Ausführung der Playbooks strikt voneinander getrennt. Dies minimiert Risiken, da Ansible Playbooks mit umfassenden Zugriffsrechten auf Servern operieren können.
4. Rollenbasierte Verwaltung von Playbooks und Variablen
   Playbooks und deren Variablen werden zentral in einer Datenbank gespeichert und rollenbasiert verwaltet. Dadurch wird sichergestellt, dass nur autorisierte Benutzer Zugriff auf sensible Daten oder Konfigurationen haben.

2 Anwendungsfälle

2.1 Funktionen aus Usersicht:

• Login
• Starten von Playbook
• Veränderung von Playbook Variablen
• Scann nach neuen Playbooks

2.2 Detailbeschreibung Funktionen

Feature	Beschreibung
Playbook Button	- Dynamisch geladen, basierend auf der Benutzerrolle (nur Playbooks, für die der Benutzer berechtigt ist). - Bei Maus-Hover wird eine Beschreibung angezeigt. - Beim Anklicken werden die Variablen (Vars) des Playbooks geladen und ein Start-Button erscheint.
Login	-Weiterleitung an Keycloak
Variablen (Vars)	- Variablen werden dynamisch geladen, sobald ein Playbook ausgewählt wurde. - Vor dem Laden wird überprüft, ob der Benutzer berechtigt ist, die Variablen zu sehen.
Rescan	- Scannt auf neue Playbooks. - Neu gefundene Playbooks (inklusive Beschreibung und zugehöriger Standardwerte) werden in die Datenbank eingetragen. - Die Beschreibung, Standardwerte und anzuzeigende Rollen werden ebenfalls gespeichert.
Speichern	- Speichert die Werte der Variablen dauerhaft in der Datenbank. - Werte werden zusätzlich in einer Standarddatei abgelegt.
Start	- Startet das ausgewählte Playbook. - Änderungen an den Variablen, die nicht gespeichert wurden, werden beim Start berücksichtigt.
Tooltip	- Zeigt zusätzliche Informationen zu den Variablen an (Hilfe und Beschreibung).
User Icon	-Falls Gravatar Icon zur Mail des Users existiert wird diese angezeigt, ansonsten Standart User Icon - Anklicken leitet zu Keycloak Profile weiter
Logs	-Log-System auf Basis von slf4j.Logger

3 Technische Umsetzung

3.1 Sequenzdiagramme

3.1.1 Sequenzdiagramm Login

3.1.2 Sequenzdiagramm Datenbank Abfragen

3.1.3 Sequenzdiagram Playbook starten

3.2 Struktur/Architektur

3.3 Technologien & Systeme

3.3.1 MySQL-Server:

• Datenbank für Playbooks (Schema in EnterprisePlaybookLib.sql).
• Datenbank für Keycloak

3.3.2 Keycloak-Server:

• Authentifizierungs- und Autorisierungsserver (Realm-Definition in Keycloak-Enterprise-realm-export.json).

3.3.3 Spring Boot Backend:

• API für Playbook-Operationen
• API für Datenbank Abfragen

3.3.4 Web Server (NginX):

• JavaScript (API aufrufe, Funktionalität Website
• HTML
• CSS (Design der Website)

4 Setup und Startanleitung

4.1 Setup

4.1.1 MySQL-Server einrichten

1. Datenbank starten

2. Datenbankschema importieren

   mysql -u <db_user> -p<db_password> <path_to>/EnterprisePlaybookLib.sql

3. Zugangsdaten anlegen:

   • Benutzername: <db_user>
   • Passwort: <db_password>

---

4.1.2 Keycloak-Server einrichten

1. Keycloak-Server starten:

   ./bin/kc.sh start-dev

2. Realm importieren:

   • Importieren der Realm-Konfiguration Keycloak-Enterprise-realm-export.json.

     ./bin/kc.sh import --file=<path_to>/Keycloak-Enterprise-realm-export.json

   • Anpasse URLs und Konfigurationen in der JSON-Datei:

     • Web-Domain (z. B. http://localhost:8080 oder Produktions-URL).
     • Datenbank-Domain
     • Datenbank-User
     • Datenbank-Password
     • Keycloak-Domain

3. Benutzer erstellen:

   • Keycloak-Admin-Konsole (Standard unter http://localhost:8080).
   • Navigiere zu Benutzer → Hinzufügen.

---

4.1.3 Spring Boot Server einrichten

1. Konfigurationsanpassungen:

   • Webserever Domain
   • Datenbank Host
   • Datenbank-User
   • Datenbank-psw
   • Keycloak-Domain
   • Playbooks speicher Ort

   Build erstellen:

   mvn clean package

---

4.1.4 Frontend Einrichtung

• API anfragen an eigene Domäne anpassen z.B. "https://enterprise.faxe.gay/"
• Website Namen anpassen z.B. "FilBraWal Applications"

4.2 Starten des Systems

Die Reihenfolge des Starts ist wichtig, um sicherzustellen, dass alle Komponenten korrekt miteinander kommunizieren können.

4.2.1 Datenbank starten

service mysql start

4.2.2 Keycloak-Server starten

Starten des Keycloak-Servers im Entwicklungsmodus:

./bin/kc.sh start-dev

4.2.3 Spring Boot Backend starten

Starte der Spring Boot Anwendung:

java -jar target/backend-1.0-SNAPSHOT.jar

---

---

5 Frontend

Dieses Skript bildet den Kern der Webanwendung "FilBraWal Applications", die entwickelt wurde, um die Interaktion mit Ansible-Playbooks zu vereinfachen. Es umfasst Benutzerauthentifizierung, dynamische Inhaltsanzeige und eine Schnittstelle zur Verwaltung von Playbooks über eine API.

5.1 Technische Übersicht

5.1.1 Abhängigkeiten

KeycloakJS	CryptoJS	DOM-Manipulation	Fetch-API
Ermöglicht Single Sign-On und Benutzerauthentifizierung	Generiert MD5-Hashes für Gravatar-URLs	Nutzt das Document Object Model (DOM) zur dynamischen Aktualisierung von UI-Elementen	Ermöglicht die Kommunikation mit RESTful-APIs.

5.1.2 Authentifizierungs Workflow

1. Die Keycloak-Instanz wird mit einem Realm und einer Client-ID initialisiert.
2. Beim Laden der Seite überprüft das Skript eine vorhandene SSO-Sitzung.
3. Wenn der Benutzer authentifiziert ist, wird das Benutzerprofil geladen, und relevante Token werden lokal gespeichert.
4. Falls keine Authentifizierung vorliegt, wird der Benutzer zur Anmeldung aufgefordert.

5.1.3 Hauptfunktionen

1. Dynamische UI:
   • Schreibmaschineneffekt für Branding.
   • Tooltips für verbesserte Benutzerfreundlichkeit.
2. Playbook-Interaktion:
   • Abrufen von Playbooks über REST-APIs.
   • Unterstützt die Live-Bearbeitung von Variablen und das Starten von Playbooks.
3. Gravatar-Integration:
   • Anzeige von Benutzer-Avataren basierend auf E-Mail-Adressen.

5.2 Implementierungsdetails

5.2.1Schreibmaschineneffekt

Der Schreibmaschineneffekt animiert Text auf der Seite:

• Funktionalität:

  • Zeigt den Text "FilBraWal Applications" Zeichen für Zeichen an.
  • Enthält einen blinkenden Cursor-Effekt.

• Code-Implementierung:

  function typeWriter() {
      if (index < typewriterText.length) {
          typewriterElement.innerHTML = typewriterText.substring(0, index + 1) + "_";
          index++;
          setTimeout(typeWriter, 100);
      } else {
          blinkCursor();
      }
  }

5.2.2 Benutzerauthentifizierung und Profilverwaltung

• Keycloak-Integration:

  • Das Skript initialisiert Keycloak mit den angegebenen Parametern und überprüft die Authentifizierung beim Laden der Seite.

  await keycloak.init({ onLoad: 'check-sso' });
  
  if (keycloak.authenticated) {
      const userProfile = await keycloak.loadUserProfile();
  }
  
  

• Gravatar-Integration:

  • Verwendet MD5-Hashing zur Generierung von Gravatar-URLs für Benutzerprofilbilder.

5.2.3 Playbook-Management

 Abrufen von Playbooks:

• Ruft Playbooks über die REST-API ab und zeigt sie dynamisch an.

• Beispiel für einen API-Aufruf:

  const response = await fetch('https://enterprise.faxe.gay/api/playbooks/all/', {
      method: 'GET',
      headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
      }
  });
  
  

• Bearbeiten von Variablen:

  • Ermöglicht die Live-Bearbeitung von Variablen innerhalb von Playbooks.
  • Beinhaltet Validierung und serverseitige Aktualisierungen über PUT-Anfragen.

• Ausführen von Playbooks:

Benutzer können Playbooks mit aktualisierten oder Standardwerten ausführen.

5.3 Herausforderungen und Lösungen

Herausforderungen

1. Dynamisches Token-Management:
   • Token laufen ab und müssen periodisch erneuert werden.
2. Fehlerbehandlung:
   • Sicherstellen robuster Antworten für fehlgeschlagene API-Aufrufe.

Lösungen

1. Implementierung von lokalem Speicher für Token, um nahtlose API-Aufrufe zu erleichtern.

Erweiterte Fehlerprotokollierung zur Unterstützung von Debugging und Benutzerfeedback.

5.4 Fazit

Das Skript von "FilBraWal Applications" integriert Keycloak-Authentifizierung mit dynamischen UI-Funktionen, um die Verwaltung von Ansible-Playbooks zu verbessern. Der modularer Aufbau und die Mechanismen zur Fehlerbehandlung geben Zuverlässigkeit und Benutzerfreundlichkeit und bieten eine solide Grundlage für zukünftige Erweiterungen.