feat(doku): Anleitung, PDF und Ende-zu-Ende-Abnahme
Neun Kapitel unter docs/anleitung/ fuer Technik und Verwaltung, mit 35 Bildern aus `pnpm docs:screenshots` und einem Fehlerbehebungskapitel aus echten Meldungen. `pnpm docs:pdf` macht daraus 72 Seiten A4 — hell gedruckt, mit Deckblatt, Inhaltsverzeichnis und Seitenzahlen, ohne neue Abhaengigkeit. Die Ablaeufe pruefen ihre Voraussetzungen, bevor der erste startet: antwortet ein gebauter Stand, steht der Seed-Bestand, und liest der Server dieselbe Datenbank wie der Testprozess. Jeder Ablauf legt an, was er braucht, und raeumt es weg. Vier neue kommen dazu: Hauptablauf, Onboarding mit Vergleich der Zwischenablage, Rollen und 390 px auf achtzehn Seiten. Drei Fehler kamen dabei heraus. Das Projekt „handy" pruefte 412 px statt der verlangten 390. Ein angemeldeter Benutzer ohne Recht erfuhr nie, warum er abgewiesen wurde — die Meldung stand auf einer Seite, die ihn sofort weiterleitet; jetzt gibt es /kein-zugriff. Und der Verzeichnis-Ablauf schrieb die Attributzuordnung der ersten vorhandenen Quelle um, in einer echten Installation also der produktiven. 101 Ablaeufe in INTERN und 97 in DIENSTLEISTUNG, beide ohne Fehlschlag. Closes #18 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Florian Wilde
co-authored by
Claude Opus 5
Claude Opus 5
parent
9bd198a531
commit
10e272654f
@@ -0,0 +1,171 @@
|
||||
# Verzeichnis anbinden
|
||||
|
||||
Unter **Admin → Verzeichnis** wird ein Active Directory als Quelle der Personen eingerichtet. Dann
|
||||
muss beim Start eines Laufs nichts abgetippt werden, und `{{vorname}}`, `{{upn}}`, `{{sam}}` und
|
||||
`{{abteilung}}` stehen von selbst zur Verfügung.
|
||||
|
||||
Zwei Dinge vorweg:
|
||||
|
||||
- Der Reiter gibt es **nur im Modus Intern**. Dort hat das Haus ein Verzeichnis, aus dem seine Leute
|
||||
kommen. Im Modus Dienstleistung wären es Verzeichnisse fremder Kunden, und die bindet Laufzettel
|
||||
ausdrücklich nicht an — dort kommen Personen von Hand oder per CSV.
|
||||
- **Laufzettel schreibt nie ins Verzeichnis.** Ein Dienstkonto mit **Leserechten** genügt.
|
||||
Gespeichert werden nur die zugeordneten Felder — keine Passwörter, keine
|
||||
Gruppenmitgliedschaften.
|
||||
|
||||
Wer im Verzeichnis verschwindet oder dort deaktiviert wird, wird hier **inaktiv**. Gelöscht wird
|
||||
nie, sonst verlöre die Historie ihre Namen.
|
||||
|
||||
## Eine Quelle anlegen
|
||||
|
||||
|
||||
|
||||
Das Formular **Quelle anlegen** steht unten auf der Seite. Die Felder:
|
||||
|
||||
| Feld | Was hinein gehört |
|
||||
|---|---|
|
||||
| **Name** | wie du die Quelle nennst, etwa „Firmen-AD“ |
|
||||
| **Adresse** | `ldaps://dc01.firma.local:636` — nur Schema, Rechner und Port |
|
||||
| **Anmelde-DN** | das Dienstkonto, etwa `CN=laufzettel,OU=Dienstkonten,DC=firma,DC=local` |
|
||||
| **Passwort** | wird verschlüsselt gespeichert und nie wieder angezeigt |
|
||||
| **Basis-DN** | wo gesucht wird, etwa `OU=Benutzer,DC=firma,DC=local` |
|
||||
| **Filter (optional)** | leer lassen nimmt den Standard: aktive Personenkonten |
|
||||
| **Abgleich alle … Minuten** | zwischen 5 und 10080 (fünf Minuten bis eine Woche) |
|
||||
| **Nach Zeitplan abgleichen** | das Häkchen schaltet den Zeitplan ein |
|
||||
|
||||
Für die **Adresse** gibt es drei Formen:
|
||||
|
||||
- `ldaps://host:636` — verschlüsselt ab dem ersten Byte. **Die richtige Wahl.**
|
||||
- `ldap+starttls://host:389` — unverschlüsselt verbunden und dann hochgestuft.
|
||||
- `ldap://host:389` — im Klartext. Sobald du das eintippst, warnt das Formular: dann geht auch das
|
||||
Bind-Passwort im Klartext über das Netz. Für ein Dienstkonto im Active Directory ist das keine gute
|
||||
Idee.
|
||||
|
||||
In die Adresse gehören **kein Pfad und keine Zugangsdaten**. Der Basis-DN hat sein eigenes Feld,
|
||||
Bind-DN und Passwort ebenso; Laufzettel weist eine Adresse mit `/` oder `@` dahinter ausdrücklich ab.
|
||||
|
||||
Der **Standardfilter** schließt deaktivierte Konten aus. Das ist der Sinn: wer aus dem Ergebnis
|
||||
verschwindet, wird hier deaktiviert. Ein eigener Filter engt weiter ein, etwa auf eine einzelne OU.
|
||||
|
||||
Dann **Quelle anlegen**.
|
||||
|
||||
## Attributzuordnung
|
||||
|
||||
Hinter **Attributzuordnung anpassen** steht, welches Verzeichnis-Attribut auf welches Feld geht. Die
|
||||
Vorgaben sind die Namen eines Active Directory:
|
||||
|
||||
| Feld | Vorgabe |
|
||||
|---|---|
|
||||
| Vorname | `givenName` |
|
||||
| Nachname | `sn` |
|
||||
| Anzeigename | `displayName` |
|
||||
| E-Mail | `mail` |
|
||||
| UPN | `userPrincipalName` |
|
||||
| Anmeldename (sam) | `sAMAccountName` |
|
||||
| Abteilung | `department` |
|
||||
| Titel | `title` |
|
||||
| Vorgesetzter | `manager` |
|
||||
| Kennung (dauerhaft) | `objectGUID` |
|
||||
|
||||
Ein OpenLDAP heißt an einigen Stellen anders — dort ist die dauerhafte Kennung etwa `entryUUID`.
|
||||
Leer gelassene Felder bekommen die Vorgabe zurück.
|
||||
|
||||
> **Die Kennung ist das eine Feld, das später nicht mehr geändert werden sollte.** An ihr erkennt der
|
||||
> Abgleich eine Person wieder. Ein anderer Wert legt beim nächsten Lauf **alle Personen neu an**.
|
||||
|
||||
## Eigenes CA-Zertifikat
|
||||
|
||||
Nur nötig, wenn der Domänencontroller ein Zertifikat aus einer eigenen CA trägt. Hinter **Eigenes
|
||||
CA-Zertifikat hinterlegen** fügst du den **PEM**-Text ein, beginnend mit
|
||||
`-----BEGIN CERTIFICATE-----`. Ohne Eintrag gelten die Wurzelzertifikate des Systems.
|
||||
|
||||
Ist eines hinterlegt, sagt die Seite das. Das Feld bleibt beim Bearbeiten trotzdem leer: **Text
|
||||
eintragen ersetzt es, leer lassen behält es**, und das Häkchen **Hinterlegtes Zertifikat entfernen**
|
||||
nimmt es weg. Beides zugleich ergibt keinen Sinn und wird abgewiesen.
|
||||
|
||||
Dasselbe gilt für das **Passwort**: leer lassen behält das gespeicherte. Sonst nähme jede
|
||||
Namensänderung der Quelle ihre Anmeldung.
|
||||
|
||||
## Verbindung testen
|
||||
|
||||
|
||||
|
||||
**Verbindung testen** liest die ersten Einträge und zeigt sie so, wie sie ankämen — **gespeichert
|
||||
wird nichts**. Mach das immer vor dem ersten Abgleich. Klappt es nicht, steht der Grund in Rot
|
||||
darunter; die häufigsten stehen in [Kapitel 08](08-fehlerbehebung.md).
|
||||
|
||||
Der Wert steckt nicht im „geht“, sondern in der Liste darunter: erst an den zugeordneten Feldern
|
||||
siehst du, ob die Zuordnung stimmt. Ein grünes „Verbindung erfolgreich“ sähe genauso aus, wenn `sam`
|
||||
und `upn` vertauscht wären — und der Fehler fiele erst auf, wenn ein PowerShell-Befehl den falschen
|
||||
Anmeldenamen trägt.
|
||||
|
||||
Prüf also Zeile für Zeile: Steht unter **UPN** wirklich der UPN? Unter **sam** der Anmeldename? Ist
|
||||
die **Abteilung** genau der Name, unter dem du die Abteilung gepflegt hast?
|
||||
|
||||
Ein **Vorgesetzter** erscheint im Test nur, wenn er zufällig unter diesen Einträgen ist. Beim
|
||||
vollständigen Abgleich wird er aufgelöst.
|
||||
|
||||
## Zeitplan und „Jetzt abgleichen“
|
||||
|
||||
Ist **Nach Zeitplan abgleichen** gesetzt, läuft der Abgleich von selbst im gewählten Intervall; an
|
||||
der Quelle steht dann „alle 60 min“, sonst „kein Zeitplan“.
|
||||
|
||||
**Jetzt abgleichen** startet ihn sofort — nach einer Änderung am Filter will niemand bis zur nächsten
|
||||
vollen Stunde warten. Es ist derselbe Vorgang, den auch der Zeitplan ruft, es gibt also keinen
|
||||
zweiten Weg mit eigenen Regeln.
|
||||
|
||||
Läuft für diese Quelle gerade schon ein Abgleich, sagt Laufzettel das und tut nichts: „Für … läuft
|
||||
gerade schon ein Abgleich. Bitte das Ergebnis abwarten.“
|
||||
|
||||
## Was der Abgleich tut
|
||||
|
||||
1. Er liest das Verzeichnis in Seiten von je tausend Einträgen.
|
||||
2. Jeder Eintrag wird über die **Kennung** wiedererkannt und aktualisiert, oder neu angelegt.
|
||||
3. Eine **von Hand angelegte** Person wird über `upn` oder `sam` gefunden und **übernommen**, nicht
|
||||
verdoppelt. Genau so ist das Onboarding gedacht: die Person entsteht hier, das AD-Konto danach.
|
||||
4. **Erst nach einem vollständigen Durchlauf** wird deaktiviert, wer nicht wiedergesehen wurde. Ein
|
||||
Netzwerkfehler nach der halben Liste soll nicht die andere Hälfte der Firma abschalten.
|
||||
|
||||
Drei Sicherungen, die alle denselben Fehler verhindern — dass eine kaputte Eingabe wie „alle sind
|
||||
gegangen“ aussieht:
|
||||
|
||||
- **Ließ sich kein einziger Eintrag zuordnen, gilt der Abgleich als gescheitert** und es wird niemand
|
||||
deaktiviert. Die Meldung sagt: „Niemand wurde deaktiviert. Prüf die Attributzuordnung, besonders
|
||||
das Kennungsattribut.“
|
||||
- **Übersprungene Einträge sind nicht verschwunden** und werden aus der Abschaltung herausgenommen.
|
||||
- Eine Person, die schon eine **andere** Quelle führt, wird nie übernommen.
|
||||
|
||||
Der Abgleich läuft nicht in einer Transaktion. Bricht er in der Mitte ab, bleiben die bis dahin
|
||||
geschriebenen Personen stehen — ein zweiter Lauf holt den Rest.
|
||||
|
||||
## Das Abgleich-Log
|
||||
|
||||
|
||||
|
||||
An der Quelle steht der letzte Stand: „Zuletzt abgeglichen am …“ oder „Letzter Abgleich gescheitert“
|
||||
mit der Meldung dazu.
|
||||
|
||||
Hinter **Abgleich-Log** stehen die letzten Läufe mit Zeitpunkt, wer sie ausgelöst hat (steht dort
|
||||
**Zeitplan**, war es niemand von Hand — das ist der Regelfall) und der Bilanz:
|
||||
|
||||
| Zahl | Bedeutung |
|
||||
|---|---|
|
||||
| **gelesen** | Einträge, die aus dem Verzeichnis kamen |
|
||||
| **angelegt** | neue Personen |
|
||||
| **übernommen** | von Hand angelegte Personen, die jetzt am Verzeichnis hängen |
|
||||
| **aktualisiert** | vorhandene Personen mit geänderten Feldern |
|
||||
| **deaktiviert** | nicht mehr wiedergesehene Personen |
|
||||
| **übersprungen** | Einträge, die sich nicht zuordnen ließen |
|
||||
|
||||
**Nullen werden gezeigt.** „0 angelegt, 0 aktualisiert“ ist die Auskunft, dass der Abgleich lief und
|
||||
sich im Verzeichnis nichts geändert hat. Fehlte die Zeile, sähe ein erfolgreicher Lauf ohne Änderung
|
||||
aus wie ein Lauf, der nie stattfand.
|
||||
|
||||
**Übersprungene** Einträge sind kein Fehler der Quelle, sondern einzelne krumme Konten — sie stehen
|
||||
deshalb als Hinweis und nicht als Fehler da. Steigt die Zahl, prüf die Attributzuordnung.
|
||||
|
||||
## Ohne Verzeichnis
|
||||
|
||||
Eine Quelle ist keine Voraussetzung. Personen lassen sich von Hand anlegen oder aus einer CSV-Datei
|
||||
einlesen — ein Verzeichnis nimmt nur die Arbeit ab. Siehe
|
||||
[Kapitel 05](05-mitarbeiter-geraete.md).
|
||||
Reference in New Issue
Block a user