Identity Provider. Nov 24, 2021

(1)

Identity Provider

Nov 24, 2021

(2)

(3)

Allgemeines

1 Zweck des Identity Providers 3

1.1 Allgemeine Funktionsweise . . . 3

1.2 Externe ID . . . 4

1.3 Begriffe . . . 5

1.4 Voraussetzungen . . . 6

1.5 Installation . . . 6

1.6 Konfiguration. . . 9

1.7 Updates . . . 11

1.8 Benutzerrollen . . . 12

1.9 Cronjobs . . . 12

1.10 Active Directory-Anbindung . . . 14

1.11 Erste Schritte . . . 14

1.12 Benutzertypen . . . 14

1.13 Benutzerrollen . . . 15

1.14 Benutzer anlegen . . . 16

1.15 Synchronsiationsregeln. . . 16

1.16 Dienste . . . 18

1.17 Attribute . . . 18

1.18 API-Schnittstelle . . . 19

1.19 Datenimport . . . 20

1.20 Benutzer . . . 20

1.21 Registrierungscodes . . . 22

i

(4)

(5)

Identity Provider

Diese Dokumentation dient einerseits einem Administrator zur Einrichtung und Verwaltung der Software und andererseits den Anwendern als Hilfe zu Workflows.

Allgemeines 1

(6)

2 Allgemeines

(7)

CHAPTER 1 Zweck des Identity Providers

Der Identity Provider stellt eine zentrale Datenbank für alle Benutzer bereit. Diese wird von allen Diensten der SchulIT Software Suite genutzt, um Benutzer zu authenfizieren und authorisieren.

Es handelt sich dabei um die zentrale Instanz für das Single-Sign-On. Dank Single-Sign-On müssen Benutzer nur in einem System eingerichtet und verwaltet werden. Für Benutzer ergibt sich der Vorteil, dass sie sich mit ihren Benutzerdaten an mehreren Diensten anmelden können.

1.1 Allgemeine Funktionsweise

1.1.1 Benutzerdatenbank

Dieser Identity Provider stellt zunächst eine Datenbank von Benutzern zur Verfügung. Zu jedem Benutzer gibt es einige Standarddaten (bspw. Vorname, Nachname, Anmelde-E-Mail-Adresse, . . . ), die gespeichert werden. Zusätzlich ist es möglich, beliebige weitere Daten für Benutzer abzuspeichern (diese nennt man Attribute).

Benutzertypen und -gruppen

Jedem Benutzer wird genau ein Benutzertyp zugeordnet. Diese entsprechen der Zugehörigkeit innerhalb der Schule (bspw. Lehrkraft, Schülerin/Schüler, Elternteil, Sekretariat, Andere). Es lassen sich auch eigene Benutzertypen definieren.

Zusätzlich dazu lassen sich Benutzergruppen definieren. Benutzer können Mitglied mehrerer Benutzergruppen sein.

Benutzergruppen lassen sich zum Beispiel für Arbeitsgemeinschaften oder Administratoren definieren.

Der Vorteil der Benutzertypen und -gruppen wird im Rechtesystem ausgespielt.

1.1.2 Zentraler Anmeldedienst

Der Identity Provider ist als Benutzerdatenbank die Anmeldeschnittstelle, Stichwort Single-Sign-On. Dies wird mithilfe desSAML-Protokollsrealisiert.

3

(8)

Der Ablauf sieht dabei folgendermaßen aus:

Fig. 1: Ablauf eines SAML-Authentifizierungsanfrage (© Tom Scavo, CC BY-SA 3.0,zum Bild)

1. Der Benutzer möchte sich an einem Dienst (bspw. dem ICC) anmelden und öffnet dazu die URL des Dienstes.

Der Dienst schaut nach, welche Identity Provider findet. Dabei ist dieser Identity Provider als einziger hinterlegt.

2. Der Dienst antwortet dem Benutzer mit einer Weiterleitungsseite zum Identity Provider. Diese Seite enthält die Anfrage für das Single-Sign-On.

3. Der Browser navigiert automatisch zum Identity Provider (mit der Anfrage). Dort muss der Benutzer sich authentifizieren. Es wird anschließend geprüft, ob der Benutzer die Berechtigung besitzt, den Dienst zu nutzen.

4. Der Identity Provider antwortet mit einer Weiterleitungsseite, die zurück zum Dienst weiterleitet. Ähnlich zu Schritt 2 enthält diese Weiterleitung die Antwort auf die Anfrage (aus Schritt 2).

5. Der Dienst nimmt die Anfrage an und wertet diese aus. Beim ICC erfolgt nun die Verknüpfung von Benutzern zu Schülerinnen und Schülern bzw. Lehrkräften.

Ab nun ist der Benutzer beim Dienst angemeldet.

1.1.3 Rechtesystem

Dienste und Attributwerte lassen sich sowohl pro Benutzertyp als auch pro Benutzergruppe und Benutzer freischalten bzw. definieren.

Um zu entscheiden, welche Dienste ein Benutzer verwenden darf und welchen Attributwert einzelne Attribute an- nehmen, geht der Identity Provider in der folgenden Reihenfolge vor:

1. Benutzertyp 2. Benutzergruppe 3. Benutzer

Attributswerte einer Benutzergruppe überschreiben also Werte, die beim Benutzertyp festgelegt wurden, und werden (falls vorhanden) von Werten des Benutzers überschrieben.

Eine Freischaltung von Diensten erfolgt in der gleichen Reihenfolge. Allerdings lässt sich eine Freischaltung nicht überschreiben. Wenn also Dienst A für den Benutzertyp freigeschaltet ist, reicht dies aus. Der Dienst kann dann nicht mehr durch eine Benutzergruppe oder den Benutzer selbst gesperrt werden.

1.2 Externe ID

Die externe ID ist eine ID, mit der man einen Benutzer über mehrere Systeme hinweg zuordnen kann. Beispiel:

Eine Lehrkraft existiert einerseits als Benutzer im Identity Provider und andererseits als Lehrkraft in Schulverwal- tungssystemen. Damit bspw. das ICC weiß, dass Benutzerm.mustermann@schule.dezur Lehrkraft Max Mustermann (Kürzel: MU) gehört, wird die externe ID benötigt.

Die externe ID kann durch die Schule vorgegeben werden. Wichtig ist, dass sie in allen Systemen identisch ist. Das ICC bspw. importiert Daten wie den Vertretungplan aus Drittsystemen, sodass auch hier eine Zuordnung stattfinden muss.

Die externe ID kann entweder eine beliebige Zeichenkette sein. Sie sollte muss nur eindeutig sein, sprich MU darf nur zur Lehrkraft Max Mustermann gehören. Da man Zahlen auch als Zeichenkette darstellen kann, können auch Zahlen (bspw. IDs aus anderen Systemen) verwendet werden.

4 Chapter 1. Zweck des Identity Providers

(9)

Hinweis: Das System überprüft nicht, ob eine eindeutige ID mehrfach vergeben wird. Das System speichert die ID ohne weitere Überprüfung.

1.2.1 Lehrkräfte

Es kann sinnvoll sein, als externe ID das Kürzel der Lehrkraft zu verwenden. Dieses wird bei vielen Verwaltungspro- grammen (Stunden- oder Vertretungplan) verwendet.

1.2.2 Schülerinnen und Schüler

Hier kann man die ID des Schülers oder der Schülerin im Schulverwaltungsprogramm (bspw. SchILD NRW) nutzen.

1.2.3 Eltern

Um Eltern ihren Kindern zuzuordnen, speichert man mehrere externe IDs in der externen ID. Da die ID grundsätzlich nur einen Wert zulässt, werden die IDs der Kinder mittels Komma abgetrennt.

1.2.4 Normale Benutzer

Benutzer, die man nicht zu Datensätzen aus anderen Systemen zuordnen muss, benötigen keine externe ID.

1.3 Begriffe

1.3.1 Identity Provider

Als Identity Provider wird diese Software bezeichnet, da sie für beliebige Dienste eine Benutzerdatenbank sowie eine Anmeldeprozedur zur Verfügung stellt.

SieheIdentitätsanbieter (Wikipedia)undIdentity provider (Wikipedia, Englisch).

1.3.2 Service Provider/Dienst

Als Service Provider oder Dienst wird Software bezeichnet, die den Identity Provider als Grundlage zur Authen- tifizierung nutzt.

SieheService provider (Wikipedia, Englisch).

1.3.3 SAML

Protokoll zum Austausch von Authentifizierungs- und Authorisierungsdaten.

Siehe SAML (Wikipedia) <https://de.wikipedia.org/wiki/Security_Assertion_Markup_Language> und SAML (Wikipedia, Englisch).

1.3. Begriffe 5

(10)

1.3.4 Attribut

Bei der Kommunikation zwischen Identity Provider und Attribut werden Daten über den Benutzer übertragen. Jede Information wird dabei als Attribut bezeichnet.

Beispiele: Anmelde-E-Mail-Adresse, externe ID, Vorname, Nachname, . . .

1.4 Voraussetzungen

Der Identity Provider ist so programmiert, dass es auf gängigen Webspaces installiert werden kann.

1.4.1 Obligatorische Software

• Webserver (Apache oder nginx)

– der Identity Provider muss auf einer Subdomain laufen, also bspw.sso.example.com

• PHP 7.4

– aktivierte Plugins: json, ctype, iconv, openssl, xml

• MySQL 5.7+ oder MariaDB 10.3+

• SSH-Zugriff auf den Webspace

• Cronjobs (entweder als Skriptausführung oder HTTP-Anfrage)

1.4.2 Optionale Tools

Außerdem sollten folgende Tools auf dem Webserver installiert sein:

• git (wird zum Herunterladen des Codes benötigt)

• composer (wird zum Herunterladen von PHP Abhängigkeiten benötigt)

• nodejs und yarn (wird zum Kompilieren des Designs benötigt)

Falls die Tools nicht vorhanden sein sollten, kann man eine ZIP-Datei mit allen benötigten Dateien herunterladen und auf dem Webspace hochladen.

1.5 Installation

1.5.1 Schritt 1: Anwendung installieren

Möglichkeit 1: Installation mit Git

Zunächst mittels Git den Quelltext des Projektes auschecken:

$ git clone https://github.com/schulit/idp.git

$ git checkout -b 1.0.0

Dabei muss1.0.0durch die gewünschte Version ersetzt werden.

Anschließend in das Verzeichnisiccwechseln und alle Abhängigkeiten installieren:

(11)

$ composer install --no-dev --optimize-autoloader --no-scripts Die Direktiveno-scriptsist wichtig, da es ansonsten zu Fehlermeldungen kommt.

Warning: Der folgende Teil funktioniert nur, wenn Node und yarn verfügbar sind. Falls die beiden Tools nicht verfügbar sind, müssen die Dateien manuell hochgeladen werden.

Nun müssen noch die Assets installiert werden:

$ yarn encore production

Möglichkeit 2: Installation ohne Git

Den Quelltext der Anwendung vonGitHubherunterladen und auf dem Webspace entpacken. Anschließend kann mit der Konfiguration fortgefahren werden.

1.5.2 Schritt 2: Konfiguration

Nachdem der Quelltext und seine Abhängigkeiten installiert sind, müssen alle benötigten Zertifikate und Konfigura- tionsdateien erstellt werden.

Schritt 2.1: Konfigurationsdatei erstellen SieheKonfiguration.

Schritt 2.2: Zertifikate erstellen

Damit der Identity Provider sich gegenüber den einzelnen Anwendungen ausweisen kann, wird ein Zertifikat benötigt.

Das Zertifikat kann über die Konsole erstellt werden:

$ php bin/console app:create-certificate --type saml

Anschließend werden einige Daten abgefragt. Diese können abgesehen vomcommonNamefrei beantwortet werden.

• countryName,stateOrProvinceName,localityNamegeben den Standort der Schule an

• organizationNameentspricht dem Namen der Schule

• organizationalUnitNameentspricht der Fachabteilung der Schule, welche das ICC administriert, bspw.

Schulname und IT-Suffix

• commonNameDomainname des ICCs, bspw.icc.example.com

• emailAddressentspricht der E-Mail-Adresse des Administrators

1.5.3 Schritt 3: Installation abschließen

Nun folgende Kommandos ausführen, um die Installation abzuschließen:

1.5. Installation 7

(12)

$ php bin/console cache:clear

$ php bin/console doctrine:migrations:migrate --no-interaction

$ php bin/console app:setup

$ php bin/console shapecode:cron:scan

1.5.4 Schritt 4: Ersten Benutzer erstellen

Nun muss ein Benutzer erstellt werden. Dieser muss als Administrator eingerichtet werden, sodass man alle weiteren Konfigurationsschritte über das Web Interface erledigen kann.

Als Benutzernamen wählt man eine (beliebige) E-Mail-Adresse aus. Diese muss nicht mit der echten E-Mail-Adresse übereinstimmen.

Wichtig:Der Benutzer muss als Administrator (Schritt 7) angelegt werden.

$ php bin/console app:add-user Username:

> admin@example.com Firstname:

> Erika Lastname:

> Mustermann E-Mail:

> admin@example.com Password:

>

Repeat Password:

>

Is this an administrator? (yes/no) [yes]:

> yes

Select user type [user]:

[0] user

> user

[OK] User successfully added

1.5.5 Schritt 5: ICC im Webspace einrichten

Das ICC muss auf einer Subdomain (bspw. sso.example.com) betrieben werden. Das Betreiben des Identity Providers in einem Unterordner wird nicht unterstützt.

Warning: Der Root-Pfad der Subdomain muss auf daspublic/-Verzeichnis zeigen. Anderenfalls funktioniert das ICC nicht und es können wichtige Konfigurationsdaten abgerufen werden.

(13)

1.6 Konfiguration

1.6.1 Konfigurationsdatei anlegen

Die Vorlage für die Konfigurationsdatei befindet sich in der Datei.env. Von dieser Datei muss eine Kopie.env.

localerzeugt werden. Anschließend muss die Datei angepasst werden.

$ cp .env .env.local

1.6.2 Konfigurationseinstellungen

APP_ENV

Dieser Wert muss immerprodenthalten, sodass das System in der Produktionsumgebung ist.

Warning: Niemalsdevin einer Produktivumgebung verwenden.

APP_SECRET

Dieser Wert muss eine zufällige Zeichenfolge beinhalten. Diese kann beispielsweise mitopenssl rand -base64 32erzeugt werden

APP_URL

Dieser Wert beinhaltet die URL zur Instanz, bspw.https://sso.example.com/

ADAUTH_ENABLED

Gibt an, ob die Anmeldung mittels Active Directory aktiviert ist.

ADAUTH_URL

Gibt die URL zum Active Directory Authentication Server an, bspw. tls://your-static-ip:55117. Dabei ist dieyour-static-ipdurch die IP-Adresse oder den Hostnamen zu ersetzen, unter dem der Server erreichbar ist. Die Portnummer55117muss angepasst werden, sofern der Server nicht über diesen Standard-Port erreichbar ist.

ADAUTH_PEERNAME

Peername des Serverzertifikats vom Active Directory Authentication Server.

ADAUTH_FINGERPRINT

Fingerabdruck des Serverzertifikats vom Active Directory Authentication Server.

1.6. Konfiguration 9

(14)

APP_NAME

Name des Identity Providers, kann nach Belieben geändert werden.

APP_LOGO

Pfad zum großen Logo für den Fußbereich. Das Bild muss impublic-Ordner (oder einem Unterordner) abgelegt werden.

APP_SMALLLOGO

Pfad zum kleinen Logo für den Kopfbereich. Das Bild muss impublic-Ordner (oder einem Unterordner) abgelegt werden.

SAML_ENTITY_ID

ID des ICCs, welche für SAML-Anfragen (Authentifizierung) genutzt wird. Dieser Wert muss mit dem Wert im Identity Provider übereinstimmen. Als Entity ID wird in der Regel die URL der Anwendung (bspw. https://

icc.example.com/verwendet).

MAILER_FROM

E-Mail-Adresse des Absenders von E-Mails aus der Anwendung heraus, bspw.noreply@schulit.de.

CRON_PASSWORD

Das Passwort für den Cronjob-Benutzer, welcher Cronjobs über eine HTTP-Anfrage ausführt. Siehe Cronjobs.

DATABASE_URL

Verbindungszeichenfolge für die Datenbankverbindung. Aktuell unterstützt das ICC ausschließlich MySQL/MariaDB-Datenbanken ab Version MySQl 5.7. Die Zeichenfolge setzt sich dabei folgendermaßen zusammen:

mysql://USERNAME:PASSWORD@HOST:3306/NAME

• USERNAME: Benutzername der Datenbank

• PASSWORD: zugehöriges Passwort des Datenbankbenutzers

• HOST: Hostname des Datenbankservers

• NAME: Name der Datenbank Weitere Informationen (englisch) gibthier.

(15)

MAILER_URL

Verbindungszeichenfolge für das E-Mail-Postfach, welches zum Versand von E-Mails verwendet werden soll.

Beispiele:

• Generischer SMTP-Versand:smtp://SMTPSERVER:465?encryption=ssl&auth_mode=login&username=USERNAME&password=PASSWORD

• Google Mail-Postfach:gmail://USERNAME:PASSWORD@localhost

Dabei sind die ParameterSMTPSERVER,USERNAMEundPASSWORDentsprechend anzupassen.

1.7 Updates

1.7.1 Schritt 1: Quelltext aktualisieren

Möglichkeit 1: Installation mit Git

Wenn das ICC aus dem Git installiert wurde, kann man mittels Git auf eine neue Version wechseln (VERSIONdurch die entsprechende Version ändern):

$ git fetch

$ git switch -b VERSION

Anschließend folgende Kommandos ausführen:

$ composer install --no-dev --optimize-autoloader --no-scripts

$ yarn encore production

Möglichkeit 2: Installation ohne Git

Die Verzeichnissenode_modules,public/build,public/bundles,src,templates,translations undvendorlöschen:

$ rm -rf node_modules/

$ rm -rf public/build/

$ rm -rf public/bundles/

$ rm -rf src/

$ rm -rf templates/

$ rm -rf translations/

$ rm -rf vendor/

Anschließend den neuen Quelltext vonGitHubherunterladen und aufspielen.

1.7.2 Schritt 2: Anwendung aktualisieren

Nun die folgenden Kommandos ausführen, um die Anwendung zu aktualisieren:

$ php bin/console cache:clear $ php bin/console doctrine:migrations:migrate –no-interaction $ php bin/console app:setup $ php bin/console shapecode:cron:scan

Die Anwendung ist nun aktualisiert.

1.7. Updates 11

(16)

1.8 Benutzerrollen

1.8.1 ROLE_USER

Diese Rolle muss jeder Benutzer haben und besitzt keine besonderen Zugriffsrechte.

1.8.2 ROLE_ADMIN

Nutzer mit dieser Rolle dürfen Benutzer anlegen, bearbeiten, löschen und importieren. Selbiges gilt für Reg- istrierungscodes.

1.8.3 ROLE_SUPER_ADMIN

Diese Rolle beinhaltet die RolleROLE_ADMINund erlaubt darüber hinaus, alle weiteren administrativen Aufgaben zu erledigen. Dazu zählt die Verwaltung von Benutzertypen, -gruppen, Diensten, Attributen sowie die Anzeige des Logs.

1.8.4 ROLE_CRON

Diese Rolle darf nicht vergeben werden. Sie wird dem einzigen Cronjob-Benutzer automatisch zugewiesen.

1.9 Cronjobs

Das System muss einige wiederkehrende Aufgaben ausführen, bspw. das Versenden von Benachrichtigungen. Der Administrator muss daher sicherstellen, dass diese Aufgaben automatisiert ausgeführt werden.

1.9.1 Möglichkeit 1: Cronjobs mittels HTTP-Anfrage ausführen

Viele Webspace-Betreiber bieten die Möglichkeit, Cronjobs in Form von HTTP-Anfragen zu realisieren. Dazu wird dann in einem fest definierten Zeitintervall eine Website vom System aufgerufen.

Vorbereitung: Passwort festlegen

Zunächst muss das Passwort für den Cronjob generiert werden.

$ php bin/console security:encode-password --no-interaction [password]

˓→Symfony\Component\Security\Core\User\User In der Ausgabe ist das Passwort enthalten:

--- ---

˓→---

Key Value

--- ---

˓→---

Encoder used Symfony\Component\Security\Core\Encoder\MigratingPasswordEncoder (continues on next page)

(17)

(continued from previous page) Encoded password $argon2id$v=19$m=65536,t=4,p=1$YXNrRzRXZGZwdi51S202eQ

˓→$DlMW6D+P896CMTj1U/Jn7KssfJqLcU98Q+lIm+AVOmk

--- ---

˓→---

Der Wert vonEncoded passwordmuss in der.env.localunterCRON_PASSWORDeintragen werden.

Warning: Der Wert des Passwortes ändert sich mit jedem Aufruf des Kommandos, auch wenn das Passwort identisch ist.

Vorbereitung: PHP-Version spezifizieren

Einige Webhoster bieten mehrere PHP-Versionen gleichzeitig an. Der Identity Provider benötigt jedoch mindestens PHP 7.4. Falls die Ausgabe

$ php --version

nicht PHP 7.4 anzeigt, muss noch angegeben werden, wo das Executable von PHP 7.4 zu finden ist. Bei manchen Hostern kann manphp74verwenden, um PHP 7.4 zu nutzen. Dann mittelswhich php74den Pfad zur Executable herausfinden und anschließend in der.env.local(ganz unten) ergänzen:

PHP_BINARY=/usr/bin/php74

Cronjob einrichten

Folgende Daten in der Cronjob-Verwaltung des Webspace festlegen

• URL:https://sso.example.com/cron(sso.example.comdurch die echte Adresse des ICC ersetzen)

• Intervall: alle zwei Minuten

• Authentifizierung:

– Art: HTTP-Basic – Benutzername: cron

– Passwort: wurde oben festgelegt

1.9.2 Möglichkeit 2: Cronjobs auf Betriebssystemebene ausführen

Falls man einen eigenen Server betreibt, können Cronjob-Programme wie crontab oder systemd genutzt werden, um ein PHP-Skript in regelmäßigen Abständen auszuführen. Dazu im Cronjob-Programm folgendes Skript alle zwei Minuten ausführen lassen:

php /path/to/sso/bin/console shapecode:cron:run

1.9. Cronjobs 13

(18)

1.10 Active Directory-Anbindung

Hat man ein lokales Active Directory, lassen sich Benutzer einerseits aus dem lokalen Verzeichnis in den Identity Provider importieren und weiter können Passwörter aus dem lokalen Schulnetzwerk zum Anmelden verwendet werden.

Warning: Bevor der Authentication Server oder Connect Client genutzt werden können, müssen dieSynchroni- sationsregelnerstellt werden.

1.10.1 Active Directory Authentication Server

Der Active Directory Authentication Server ist ein Programm, welches im Schulnetzwerk (besser: in einer DMZ) läuft und Authentifizierungsanfragen (Benutzername und Passwort) entgegennimmt und gegen das Active Directory auswertet. Als Antwort liefert es im Falle eines Erfolges Informationen über den Benutzer im Active Directory (ob- jectGuid, E-Mail-Adresse, Vorname, Nachname, Organisationeinheit, Gruppenmitgliedschaften).

Nach einer erfolgreichen Anmeldung wird der Benutzer - sofern er nicht bereits vorhanden ist - im Identity Provider hinterlegt. Das Passwort wird kryptografisch sicher abgespeichert, sodass sich ein Benutzer auch anmelden kann, falls der Server ausfällt.

Die Verbindung zwischen dem Identity Provider und dem Active Directory Authentication Server ist mit TLS ver- schlüsselt.

Zum Active Directory Authentication Server

1.10.2 Active Directory Connect Client

Mithilfe des Active Directory Connect Clients werden Benutzer aus dem Active Directory im Identity Provider vorab provisioniert. Dies ermöglicht es, Benutzer zu bearbeiten bevor sie sich initial anmelden. Außerdem übernimmt das Tool das Löschen von nicht mehr vorhandenen Benutzern.

Zum Active Directory Connect Client

1.11 Erste Schritte

Bevor das System einsatzbereit ist, müssen einige Bereiche konfiguriert und an die eigene Schule angepasst werden.

Anderenfalls verhält sich das System unter Umständen nicht so, wie es erwartet wird.

Warning: Die Konfiguration benötigt die BenutzerrolleROLE_ADMIN.

1.12 Benutzertypen

Jedem Benutzer wird genau ein Benutzertyp zugeordnet. Dieser kann (muss aber nicht) seiner Funktion an der Schule entsprechen (bspw. Lehrkraft, Sekretariat, Lernende, . . . ).

Der Benutzertyp wird in Form zweier Attribute (sowohl das SAML-AttributeduPersonAffiliationals auch das selbst-definierte Attributurn:type) an Dienste wie das ICC, das Service Center oder andere SAML-kompatible Dienste weitergegeben.

(19)

1.12.1 Standard-Benutzertyp Benutzer

Standardmäßig gibt es den BenutzertypBenutzer. Dieser Benutzertyp sollte allen Benutzern zugewiesen werden, die keine bestimmte Funktion an der Schule einnehmen (bspw. externe Benutzer oder Administratoren).

1.12.2 Standard-Typen erzeugen

In der Verwaltung können unter Benutzertypen die Standard-Benutzertypen für Eltern, Lehrkräfte, Lernende und Sekretariat angelegt werden.

1.12.3 Weitere Benutzertypen erzeugen

Neben den Standard-Typen lassen sich auch weitere Benutzertypen nach belieben erstellen. Dazu müssen folgende Informationen eingegeben werden:

• Name: Anzeigename des Benutzertyps

• Alias: Kurzname des Benutzertypes (sollte keine Leer- oder Sonderzeichen enthalten). Wird als Attributwert genutzt bei der Weitergabe an Dienste genutzt.

• eduPersonAffiliation: Gibt an, welche Rolle Benutzer dieses Benutzertyps im Hinblick auf die Schule einnehmen.

• Dienste (optional): Die hier angegebenen Dienste sind für Benutzer mit diesem Benutzertyp immer freigeschaltet.

Unter Attribute können nun einzelne Attributwerte festgelegt werden.Wichtig:Diese Werte können durch Benutzer- rollen oder explizit beim Benutzer gesetzte Werte überschrieben werden (sie werden nicht zusammengeführt).

1.13 Benutzerrollen

Jeder Benutzer kann beliebig viele Benutzerrollen zugewiesen bekommen. Benutzerrollen können dazu genutzt werden, um einer Benutzergruppe (bspw. Administratoren oder AG-Schülern) bestimmte Rechte zuzuweisen.

1.13.1 Benutzerrollen verwalten

Benutzerrollen können in der Verwaltung unter Benutzerrollenverwaltet werden. Standardmäßig sind keine Rollen definiert.

1.13.2 Benutzerrolle erstellen

Zum Erstellen einer Benutzerrolle müssen folgende Informationen angegeben werden:

• Name: Anzeigename der Benutzerrolle.

• Beschreibung: Kurze Beschreibung der Rolle (wird nur in der Verwaltung angezeigt).

• Dienste (optional): Die hier angegebenen Dienste sind für Benutzer dieser Benutzergruppe immer freigeschaltet.

Unter Attribute können nun einzelne Attributwerte festgelegt werden. Wichtig:Diese Werte überschreiben Attribute von Benutzertypen und können durch beim Benutzer explizit gesetzte Werte ersetzt werden (sie werden nicht zusam- mengeführt).

1.13. Benutzerrollen 15

(20)

1.14 Benutzer anlegen

Das Anlegen der Benutzer kann entweder händisch erfolgen oder automatisiert. Anleitungen zum automatisierten Import sind unterDatenimportzu finden.

1.14.1 Lehrkräfte und Lernende

Da Lehrkräfte und Lernende in der Regel in einer Datenbank (entweder Schulverwaltungsprogramm oder in einem Active Directory/LDAP-Verzeichnis) gespeichert sind, kann ein Datenimport aus einer dieser Quellen erfolgen.

Der Import aus CSV-Dateien wirdhiererläutert.

Um den Import weiter zu vereinfachen, wird der Import aus dem Active Directory empfohlen. Dazu werden zwei Komponenten benötigt:

• Active Directory Authentication Server: Dieser Server beantwortet Authentifizierungsanfragen, sodass sich Be- nutzer mit ihrer E-Mail-Adresse und dem Passwort aus dem Schulnetzwerk anmelden können.

• Active Directory Connect (optional, aber empfolen): Diese Software synchronisiert alle Benutzer vorab zum Identity Provider, sodass Benutzer bereits vor ihrer ersten Anmeldung dort bekannt sind und bearbeitet werden können.

Damit die Benutzer für sie passende Rechte zugewiesen bekommen, müssenSynchronisationsregelnerstellt werden.

1.14.2 Eltern

Eltern

1.15 Synchronsiationsregeln

Nutzt man die Möglichkeit, den Active Directory Authentication Server oder Connect Client zur Authentifizierung bzw. Synchronisation der Benutzer zu verwenden, so müssen Regeln definiert werden, um die Benutzer korrekt im Identity Provioder anzulegen.

Warning: Die Synchronisationsregeln werden bei jedem Import und bei der jeder erfolgreichen Anmeldung angewendet.

Die Synchronisationsregeln können in der Verwaltung unter AD Synchronisationsregelnverwaltet werden.

1.15.1 Regeln für Benutzertypen

Wenn Lernende und Lehrkräfte über das Active Directory authentifiziert werden sollen, müssen für beide Benutzer- typen entsprechende Regeln erstellt werden. Dazu klickt man auf Neue AD Synchronisationsregelund trägt folgende Informationen ein:

• Name: Der Anzeigename für die Regel.

• Beschreibung: Kurze Beschreibung (wird nur in der Verwaltung angezeigt).

• Active Directory Quelle: legt fest, welcher Wert für diese Regel verglichen werden soll.

(21)

– Gruppe: Distinguished Name der Gruppe (bspw. CN=Administratoren,CN=Users,DC=ad, DC=meine-schule,DC=de

– Organisationseinheit: Distinguished Name der Organisationseinheit (bspw. OU=Students, DC=ad,DC=meine-schule,DC=de)

Das System überprüft dann, ob der Benutzer Mitglied der Gruppe ist oder Mitglied in der Organisationseinheit.

Bei letzterem kann der Benutzer auch Mitglied einer Unter-Organisationseinheit sein.

• Wert: Der zu vergleichende Wert (siehe Beispiele oben)

• Benutzertyp: Der zuzuweisende Benutzertyp.

1.15.2 UPN-Suffixe

Damit der Identity Provioder weiß, welche Anmeldedaten zwecks Authentifizierung an den Authentifizierungsserver weitergeleitet werden sollen, müssen Suffixe der Anmelde-E-Mail-Adressen definiert werden. Bei diesen Suffixen handelt es sich um die zugehörigen E-Mail-Domains der Benutzer (d.h. der Teil hinter dem @-Zeichen).

Die Suffixe werden dabei explizit und ohne @-Zeichen angegeben. Wildcard-Suffixe werden nicht unterstützt. Sub- domains müssen ebenfalls explizit angegeben werden.

Warning: Man muss die UPN-Suffixe unbedingt auch in den Konfigurationsparameter REGISTRA- TION_DOMAIN_BLOCKLISTeintragen. Anderenfalls werden Authentifizierungsanfragen unnötig an den Au- thentifizierungsserver weitergeleitet.

1.15.3 Regeln für Benutzerrollen

Bei der Authentifizierung über das Active Directory können auch Benutzerrollen automatisch zugewiesen werden.

Dazu klickt man auf Synchronisationsregeln für Benutzerrollenund dort auf Neue Synchronisationsregelund trägt folgende Informationen ein:

• Name: Der Anzeigename für die Regel.

• Beschreibung: Kurze Beschreibung (wird nur in der Verwaltung angezeigt).

– Gruppe: Distinguished Name der Gruppe (bspw. CN=Administratoren,CN=Users,DC=ad, DC=meine-schule,DC=de

– Organisationseinheit: Distinguished Name der Organisationseinheit (bspw. OU=Students, DC=ad,DC=meine-schule,DC=de)

• Wert: Der zu vergleichende Wert (siehe Beispiele oben)

• Benutzerrolle: Die zugewiesene Benutzerrolle.

Warning: Es werden nur Benutzerrollen hinzugefügt. Es werden grundsätzlich keine Benutzerrollen entfernt.

1.15. Synchronsiationsregeln 17

(22)

1.15.4 Regeln für Klassen

Bei der Authentifizierung von Lernenden über das Active Directory können auch Klassen automatisch eingetragen werden. Dazu klickt man auf Synchronisationsregeln für Klassenund dort auf Neue Synchronisationsregelund trägt folgende Informationen ein:

• Klasse: Die Klasse, die eingetragen werden soll.

– Gruppe: Distinguished Name der Gruppe (bspw. CN=05A,CN=Users,DC=ad, DC=meine-schule,DC=de

– Organisationseinheit: Distinguished Name der Organisationseinheit (bspw. OU=05A, OU=Students,DC=ad,DC=meine-schule,DC=de)

• Wert: Der zu vergleichende Wert (siehe Beispiele oben).

1.16 Dienste

Jede Anwendung, die diesen Identity Provider zu Authentifizierung und Authorisierung nutzt, wird als Dienst bezeichnet. Grundsätzlich wird jede Anwendung unterstützt, die das SAML-Protokoll unterstützt.

1.16.1 Benötigte Daten

Um einen neuen Dienst zu registrieren, werden neben dem gewünschten Anzeigenamen und einer Beschreibung weitere Daten benötigt:

• Entity ID: eine Art ID, die den Dienst eindeutig identifiziert. Dies ist in der Regel die URL, unter der der Dienst erreichbar ist (bspw.https://icc.example.com/)

• Assertion Customer Service URL: die URL, an der der Benutzer nach der erfolgreichen Anmeldung und Au- thorisierung weitergeleitet wird.

• Zertifikat: das Zertifikat des Dienstes, welches zur Verschlüsselung der Daten zwischen Identity Provider und Dienst genutzt wird.

1.16.2 Dienst erstellen

Den Dienst erstellt man in der Verwaltung unter Dienste. Dort trägt man alle benötigten Informationen ein.

Im Anschluss muss geprüft werden, ob für den Dienst bestimmte Attribute (bspw. zur Festlegung der Rollen) angelegt werden müssen.

1.17 Attribute

Mithilfe von Attributen lassen sich Daten für Benutzer im Identity Provider ablegen. Unterstützt werden dabei:

• einfache Zeichenketten (Freitext)

• vordefinierte Werte (Zeichenketten), hier ist eine Mehrfachauswahl möglich

(23)

1.17.1 Standard-Attribute

Jeder Benutzer verfügt standardmäßig über folgende Attribute:

Attribut Beschreibung

urn:id Eindeutige UUID, die der Benutzer im Identity Provider besitzt.

http://schemas.xmlsoap.org/ws/2005/05/

identity/claims/surname

Nachname http://schemas.xmlsoap.org/ws/2005/05/

identity/claims/givenname

Vorname http://schemas.xmlsoap.org/ws/2005/05/

identity/claims/emailaddress

E-Mail-Adresse

urn:external-id Externe ID

urn:services Liste von Diensten, für die der Benutzer freigeschaltet ist. Wird jeweils als JSON-Objekt serialisiert.

urn:grade Klasse des Benutzers (falls vorhanden)

urn:type Alias des Benutzertyps

eduPersonAffiliation eduPersonAffiliation des Benutzertyps

1.17.2 Benutzerdefinierte Attribute

Neben den Standard-Attributen lassen sich auch weitere Attribute definieren. Dabei lässt sich auch festlegen, welche Dienste das Attribut auslesen können. Sie lassen sich in der Verwaltung unter Attribute verwalten.

Beim Anlegen müssen folgende Informationen angegeben werden:

• Name: eindeutiger Name des Attributes. Wird intern verwendet und darf nicht mehrfach verwendet werden.

• Anzeigename: wird als Anzeigename bei der Anzeige der Attribute verwendet.

• Beschreibung: kurze Beschreibung, wozu das Attribut verwendet wird. Wird den Benutzern angezeigt.

• Die Option “Benutzer können dieses Attribut ändern” ist selbsterklärend

• SAML Attribut-Name: entspricht dem Attributsnamen, der bei der SAML Antwort eingetragen wird.

• Typ: Text (Freitext) oder Auswahlfeld (vordefinierte Optionen, Mehrfachauswahl möglich, s.u.)

• Dienste: gibt die Dienste an, bei denen das Attibut in der SAML Antwort enthalten sein soll.

Wenn als TypAuswahlfeldausgewählt wurde, lassen sich die einzelnen Optionen über das angeben. Der Schlüssel entspricht dem Wert, der in der SAML Antwort übertragen wird. Als Wert trägt man den Anzeigenamen ein.

1.18 API-Schnittstelle

Die API-Schnittstelle ermöglicht es, Daten automatisiert in das System zu importieren.

1.18.1 Token erstellen

Um die API nutzen zu können, muss zunächst ein passendes Token erzeugt werden. Dieses Token muss bei jedem Import im Kopfbereich der HTTP-Anfrage alsX-Tokenmitgesendet werden.

Das Token erzeugt man in der Verwaltung unter Anwendungen.

Beim Erzeugen muss ausgewählt werden, welche Funktionalität das Token hat:

1.18. API-Schnittstelle 19

(24)

• Allgemeine API: erlaubt die Nutzung der Endpunkte /api/user_types, /api/user und /api/

registration_codes

• IdP Exchange: erlaubt die Nutzung der Endpunkte/exchange/. Diese Endpunkte werden für IdP Exchange- Funktionalitäten genutzt. Diese werden bei den jeweiligen Anwendungen (ICC, . . . ) beschrieben

• AD Connect: erlaubt die Nutzung der Endpunkte/api/ad_connect. Wird für AD Connect Clients benötigt.

Sofern man den Zugriffsbereich IdP Exchange auswählt, muss auch ein Dienst angegeben werden. Nur so wird sichergestellt, dass nur für den Dienst bestimmte Benutzerdaten übertragen werden.

Nachdem das Token erstellt wurde, wird es auf der Übersichtsseite angezeigt.

1.18.2 Dokumentation der API

Die Schnittstellen für IdP Exchange und AD Connect sind aktuell nicht dokumentiert, da für sie enstsprechende Bibliotheken oder Clients existieren, die diese API-Schnittstelle (exklusiv) nutzen.

Die Allgemeine API ist entsprechend dokumentiert. Die Dokumentation findet man in der Verwaltung unterAPI Dokumentation.

1.19 Datenimport

Benutzer und Registrierungscodes können auch aus anderen Datenquellen importiert werden.

Dazu stellt der Identity Provider mehrere Möglichkeiten zur Verfügung:

• CSV: Sowohl Benutzer als auch Registrierungscodes können mittels einer CSV-Datei importiert werden.

• API: Sowohl Benutzer als auch Registrierungscodes können mittels einer API-Schnittstelle automatisiert importiert werden.

• Active Directory: Benutzer können aus dem Active Directory synchronisiert werden. Passwörter werden dabei nicht synchronisiert.

1.20 Benutzer

1.20.1 Vorbemerkungen

Beim Import müssen folgende Dinge beachtet werden:

• Importiert man vorhandene Benutzer erneut, werden diese entsprechend der neuen Daten aktualisiert. Pass- wörter werden dabeinichtüberschrieben, sondern ignoriert.

• Das System erkennt vorhandene Benutzer anhand der E-Mail-Adresse.

• Wenn beim Import kein Passwort angegeben wird, muss der Benutzer diePasswort zurücksetzen-Funktion verwenden, um sich ein Passwort zu setzen. Wichtig: Die E-Mail-Adresse muss gültig sein und E-Mails vom System empfangen können!

1.20.2 CSV-Import

Zunächst muss eine CSV-Datei mit den folgenden Spalten erzeugt werden:

(25)

E-Mail,Passwort,Vorname,Nachname,Klasse,ID

max.mustermann@mail.example.com,Test1234$,Max,Mustermann,5A,42 erika.musterfrau@mail.example.com,Test1234$,Erika,Musterfrau,EF,100 Erläuterungen:

• Die Felder Passwort, Vorname, Nachname, Klasse und ID dürfen leer sein.

• Das Feld ID speichert eine ID, mit der der Benutzer an Diensten wie dem ICC “wiedererkannt” werden kann.

• Die E-Mail-Adresse ist gleichzeitig auch die Anmelde-E-Mail-Adresse.

• Die Reihenfolge der Spalten ist beliebig.

Den Import startet man in der Benutzerverwaltung über den Button Benutzer importieren. Dort wählt man zunächst die CSV-Datei aus. Anschließend überprüft man, ob das Trennzeichen (, oder ;) passt. Zum Schluss wählt man noch aus, welchem Benutzertyp die importieren Benutzer zugewiesen werden sollen.

Nun überprüft man die Daten, ändert sie ggf. ab und klickt auf fertigstellen.

Warning: Nach dem CSV-Import dauert es eine Weile, bis die Benutzer provisioniert wurden. Da das Hashen der Passwörter Zeit in Anspruch nimmt, wird diese Aufgabe von einer Hintergrundaufgabe erledigt.

Man erkennt noch nicht bereitgestellte Benutzer am TagBereitstellung ausstehend:

1.20. Benutzer 21

(26)

Sobald das Tag verschwunden ist, kann sich der Benutzer anmelden.

1.20.3 API-Import

Über dieREST-Schnittstellekönnen Benutzer automatisiert angelegt werden.

Die Dokumentation der Schnittstelle ist in der Verwaltung unterAPI-Dokumentationangegeben.

Zur Nutzung der API bitte unterAPI-Schnittstelleweiterlesen.

1.21 Registrierungscodes

1.21.1 Vorbemerkung

Bei einem erneuten Import eines Registrierungscodes wird dieser aktualisiert. Für den Fall, dass der Code bereits eingelöst wurde, werden die Änderungen zwar in der Datenbank hinterlegt, aber da der Benutzer bereits angelegt wurde, wird diesernichtgeändert.

1.21.2 CSV-Import

Zunächst muss eine CSV-Datei mit den folgenden Spalten erzeugt werden:

Code,Benutzername,Suffix,Vorname,Nachname,E-Mail,Klasse,ID ABCD-EFG,,extern.example.com,,,,,

Erläuterungen:

• Die Felder Vorname, Nachname, Klasse, E-Mail und ID dürfen leer sein.

• Das Feld ID speichert eine ID, mit der der Benutzer an Diensten wie dem ICC “wiedererkannt” werden kann.

• Wenn weder Benutzername noch Suffix angegeben sind, kann sich der Benutzer eine beliebige Anmelde- E-Mail-Adresse zuweisen (sofern diese nicht bereits existiert). Hierbei wird der Konfigurationsparameter REGISTRATION_DOMAIN_BLOCKLISTberücksicht.

• Die Reihenfolge der Spalten ist beliebig.

Den Import startet man in der Verwaltung der Registrierungscodes über den Button Registrierungscodes importieren.

Dort wählt man zunächst die CSV-Datei aus. Anschließend überprüft man, ob das Trennzeichen (, oder ;) passt. Zum Schluss wählt man noch aus, welchem Benutzertyp die den Benutzern des Registrierungscodes zugewiesen werden sollen.

(27)

Nun überprüft man die Daten, ändert sie ggf. ab und klickt auf fertigstellen.

1.21.3 API-Import

Über dieREST-Schnittstellekönnen Benutzer automatisiert angelegt werden.

Die Dokumentation der Schnittstelle ist in der Verwaltung unterAPI-Dokumentationangegeben.

Zur Nutzung der API bitte unterAPI-Schnittstelleweiterlesen.

1.21. Registrierungscodes 23