README.md

@@ -1,5 +1,86 @@
 # OTP-Login
 
-In Vereinen ist es wichtig, Helfern für eine bestimmte Zeit CRUD-Rechte zu geben. Es ist meist nicht notwendig, dass der Helfer dazu unbedingt einen Account benötigt.
+## Vorbemerkung
 
-Das genaue Vorgehen wird in der Readme bzw. per UML festgelegt.
+Bei Veranstaltungen kommt es oft vor, dass Clients (Browser auf Endgeräten) zeitweilig für Zugriffe freigegeben werden müssen. Dabei ist es oft nicht möglich, auf den Clients alle Sicherheitsaspekte zu beachten. Meist sind es private Endgeräte, da gerade Vereine auf die Bereitstellung privater Möglichkeiten angewiesen sind. Auch ist es nicht garantiert, dass der Nutzer diese Rechte jedes Mal identisch braucht.
+
+Das aktuelle Vorgehen ist es, dem Nutzer einen Account zu geben. Dabei hat man aber nur eine geringe Kontrolle des Passwortes und wie oben gesagt der Clients-Sicherheit. Je mehr Rechte der User bekommt, umso anfälliger wird die IT-Infrastruktur für absichtliches wie unabsichtliches Fehlverhalten. Ausserdem entstehen so eine Unmenge an Accounts, die nicht mehr ordentlich gewartet werden können. Das verschärft die Sicherheitsprobleme weiter.
+
+Als weiteres Problem kommt hinzu, dass das technische Verständnis der Nutzer nicht immer perfekt ist, um auch eine Account-Sicherheit zu gewährleisten. Das Betrifft zum Beispiel:
+
+* aufschreiben des Passwortes
+* weitergabe des Passwortes an weitere Personen
+
+Aus diesen Gründen ist das aktuelle Vorgehen nicht sicher genug.
+
+## Begrifflichkeiten
+
+### OTP
+
+Ausgeschrieben "One-Time-Password". Ist ein nur kurze Zeit gültiges Passwort, dass meist bei der Zwei-Faktor-Authentifizierung Anwendung findet.
+
+[Wikipedia - Einmalkennwort](https://de.wikipedia.org/wiki/Einmalkennwort)
+
+### Client
+
+Damit ist der Browser auf dem Endgerät eines Nutzers gemeint.
+
+### Veranstalter
+
+Verantwortliche für die Veranstaltung. Dieser Personenkreis hat am besten den Überblick über mögliche Mitarbeiter bei der Veranstaltung.
+
+### IT-Administratoren
+
+Die Verantwortlichen für die IT-Infrastruktur, die bei der Veranstaltung eingesetzt wird.
+
+## Einfache Beschreibung
+
+Ganz ohne Accounts geht es nicht. Dabei gibt es nur zwei Gruppen. IT-Administratoren und Veranstalter. Ein IT-Administrator kann einen Veranstalter Rechte geben, um Clients eine oder mehrere Rollen zu geben. Diese Client-Rechte sind Zeitlich begrenzt. Der Account eines Veranstalters ist nicht begrenzt.
+
+### IT-Administratoren
+
+* kann Veranstalter anlegen
+* hat erweitertes technisches Verständnis
+* kann Clients vorzeitig entfernen
+
+### Veranstalter
+
+* kann Clients freischalten
+* allgemeines technisches Verständnis reicht aus
+
+### Clients
+
+* es wird nur ein Browser des Endgerätes freigeschaltet
+* die Freischaltung ist von vorne rein zeitlich begrenzt
+
+## Detaillierter Ablauf
+
+### Phase I
+
+Ein schon angemeldeter IT-Administrator meldet einen Veranstalter beim System an. Der Veranstalter bekommt die Daten für eine OTP-App und einen Benutzernamen.
+
+### Phase II
+
+Ein Veranstalter entscheidet sich, ein Client für eine oder mehrere Rollen freizugeben. Dazu geht er im Browser auf die Freigabe-Seite. Dort muss er folgende Daten Eingeben:
+
+* Name des Clients
+* Rolle bzw Rollen des Clients
+* Benutzername des Veranstalters
+* gültiges OTP
+
+Es wird ein *JSON-Web-Token* im Browser als Cookie gespeichert. Dieser Token hat ein Verfallsdatum.
+
+### Phase III
+
+Der Nutzer des Clients möchte eine Web-API-Aktivität über die Weboberfläche ausführen. Dazu sendet die Weboberfläche per JavaScript eine Anfrage an die Web-API, bei der der *JSON-Web-Token* mitgesendet wird.
+Die Web-API überprüft durch den Login-Server die Korrektheit des Tokens. Dann wird die Rolle des Clients ausgewertet und entsprechend das Ergebnis zurückgegeben.
+
+* HTTP-Code-2XX: Anfrage erfolgreich
+* HTTP-Code-403: Die Aktion ist nicht erlaubt
+* HTTP-Code-401: Der Client hat überhaupt keine *JSON-Web-Token*
+
+## Bekannte Probleme
+
+Ein Veranstalter wird nur durch ein OTP geschützt. Es ist **keine** Zwei-Faktor-Authentifizierung.
+Dadurch wird aber auch die Sicherheit des Clients unproblematisch, da der Client nur ein OTP bekommt, dass nur eine kurze Zeit gültig ist.
+Des Weiteren laufen die Server nur für die Dauer der Veranstaltung. Auch das entschärft die Probleme.

resources/uml/Ablauf/Phase-I.puml

@@ -0,0 +1,21 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+actor Veranstalter
+actor IT
+boundary "Auth-Website" as AuthUI
+control "Auth-API" as AuthAPI
+database "Auth-Datenbank" as AuthDB
+
+Veranstalter -> IT : anfrage Account
+activate AuthUI
+IT -> AuthUI : Login
+IT -> AuthUI : Neuer //Veranstalter//
+Veranstalter -> AuthUI : Angabe Benutzername
+AuthUI -> AuthAPI : Erstellung //Veranstalter//
+AuthAPI -> AuthAPI : Erstellung //OPT-Token//
+AuthAPI -> AuthDB : Speicherung der Daten des //Veranstalter//
+AuthUI <-- AuthAPI : OTP-Token für die //OTP-App//
+Veranstalter <--AuthUI : OTP-Token für die //OTP-App//
+
+@enduml

resources/uml/Ablauf/Phase-II.puml

@@ -0,0 +1,29 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+actor Veranstalter
+actor Client
+boundary "Auth-Website" as AuthUI
+control "Auth-API" as AuthAPI
+control "OTP-API" as OTP
+database "Auth-Datenbank" as AuthDB
+
+Veranstalter -> Client : Anfrage mitarbeit?
+Client -> AuthUI : Aufruf Webseite Login
+Veranstalter -> AuthUI : Eintragung //Benutzername//-Client
+Veranstalter -> AuthUI : Eintragung //Benutzername//-Veranstalter
+Veranstalter -> AuthUI : Eintragung Rollen-Client
+Veranstalter -> AuthUI : Eintragung gültiges //OPT//
+AuthUI -> AuthAPI : Anfrage nach //Web-Token//
+AuthAPI -> AuthDB : Anfrage nach Veranstalter-Daten
+AuthAPI -> OTP : Prüfung OTP
+return
+alt OTP ist ok
+    AuthAPI -> AuthDB : Speichere Daten
+    AuthAPI -> AuthAPI : Erstelle //Web-Token//
+    AuthUI <-- AuthAPI : //Web-Token//
+    Client <-- AuthUI : //Web-Token//
+else OTP ist nicht ok
+    AuthUI <-- AuthAPI : HTTP-Error 401
+end
+@enduml

resources/uml/Ablauf/Phase-III-Token-auswerten.puml

@@ -0,0 +1,36 @@
+@startuml
+'https://plantuml.com/activity-diagram-beta
+
+start
+:Client möchte App-Server abfragen;
+:Client sendet Token>
+partition App-Server {
+    if (Token nicht in der Datenbank) then (Ja)
+        :Sende Token an Auth-Server>
+        partition Auth-Server {
+            :Überprüfe Token|
+            :Sende Ergebnis<
+        }
+        if (Token ist gültig) then (Ja)
+            :Speichere Token und Verfallsdatum
+            in Datenbank/
+        else
+            :Sende HTTP-Code 401<
+            stop
+        endif
+    else
+        if (Token ist verfalle) then (Ja)
+            :Sende HTTP-Code 401<
+            stop
+        endif
+    endif
+    :Rolle aus Token überprüfen]
+    if (Rolle erlaubt Abfrage) then (Ja)
+        :Abfrage ausführen|
+    else
+        :Sende HTTP-Code 403<
+    endif
+}
+stop
+
+@enduml

resources/uml/Ablauf/Phase-III.puml

@@ -0,0 +1,28 @@
+@startuml
+'https://plantuml.com/sequence-diagram
+
+actor Client
+boundary "App-Website" as AppUI
+control "App-Rest-API" as AppAPI
+
+Client -> AppUI : Anfrage an Webseite
+AppUI -> AppAPI : Anfrage an Webseite
+Client --> AppUI : //Web-Token//
+AppUI --> AppAPI : //Web-Token//
+AppAPI -> AppAPI : //Web-Token// überprüfen
+alt //Web-Token// ist gültig
+    AppAPI -> AppAPI : Client-Rolle überprüfen
+    alt Rolle ist gültig
+        AppAPI -> AppAPI : Anfrage auswerten
+        AppUI <-- AppAPI :
+        Client <-- AppUI :
+    else
+        AppUI <- AppAPI : HTTP-Code 403
+        Client <- AppUI : HTTP-Code 403
+    end
+else
+    AppUI <- AppAPI : HTTP-Code 401
+    Client <- AppUI : HTTP-Code 401
+end
+
+@enduml

resources/uml/Komponenten.puml

@@ -0,0 +1,30 @@
+@startuml
+'https://plantuml.com/component-diagram
+
+
+node Webseite {
+    component UI
+    folder Cookies
+    UI <--> Cookies
+}
+node "App-API" {
+    component API
+    database "DB" as AppDB {
+      folder "Clients" as BekannteClients
+    }
+    API <--> AppDB
+}
+node "Auth-API" {
+    component "API" as AuthAPI
+    database "DB" as AuthDB{
+      folder "Administratoren"
+      folder "Veranstalter"
+      folder "Clients"
+    }
+    AuthAPI <--> AuthDB
+}
+
+UI <-> API
+API <-> AuthAPI
+
+@enduml