Clarify BizTalk SQL authorization setup

Dokumentation.md

@@ -166,6 +166,8 @@ Dieses Konto besitzt nicht automatisch BizTalk- oder SQL-Berechtigungen. Daraus
 
 Der ACC-Test vom 29.07.2026 bestaetigt genau diesen Pfad: Auf `AV23AGPWBIO1` ist WMI erreichbar, aber der Provider meldet `COMException 0x80131904` mit `Login failed for user 'BEW\AV23AGPWBIO1$'`. Die `UNKNOWN`-Services fuer Plattform, Host Instances, Runtime Artifacts und Suspensions sowie die fehlende SQL-Zielermittlung sind Folgefehler. DCOM-, Firewall- oder WMI-ACL-Erweiterungen beheben diesen konkreten SQL-Loginfehler nicht. Der Event-Log-Check arbeitet bereits und seine Fehler/Warnungen sind separat zu bewerten.
 
+Die Codekorrektur ersetzt die Berechtigungsfreigabe nicht. Sie klassifiziert den Fehler korrekt, zeigt das abgewiesene Konto und fuehrt die SQL-Folgediagnose als Berechtigungsfehler. Sie veraendert weder AD noch SQL Server. Daher bleibt die neue Version ohne Gruppenfreigabe `UNKNOWN`; umgekehrt kann auch die alte Version nach korrekter Freigabe grundsaetzlich auf die Daten zugreifen.
+
 ### Pruefung und Freigabe
 
 Der direkte Programmstart in einer administrativen Shell laeuft unter dem angemeldeten Benutzer und ist deshalb kein ausreichender Berechtigungstest. Verbindlich ist die Ausfuehrung durch den Checkmk Agent Controller als `LocalSystem`:
@@ -186,6 +188,17 @@ Bei Zugriffsfehlern gilt folgendes Least-Privilege-Vorgehen:
 
 Die Operator-Rolle ist fuer grundlegendes Monitoring und Zustandsabfragen vorgesehen. Direkte manuelle Aenderungen an den Rollen der BizTalk-SQL-Datenbanken sind zu vermeiden; die durch BizTalk konfigurierte Windows-Gruppe ist die vorgesehene Berechtigungsgrenze.
 
+Im Normalfall ist diese Windows-Gruppe bereits als SQL-Gruppenlogin und als Datenbankbenutzer eingerichtet. Ihre Benutzerzuordnung vermittelt `BTS_OPERATORS` unter anderem in `BizTalkMgmtDb` und `BizTalkMsgBoxDb`. `BEW\AV23AGPWBIO1$` erhaelt den Zugriff durch die AD-Gruppenmitgliedschaft und braucht keinen eigenen SQL-Login.
+
+Bleibt der Fehler trotz bestaetigter Gruppenmitgliedschaft, AD-Replikation und erneuertem Maschinen-Token bestehen, pruefen BizTalk- und SQL-Administration:
+
+1. Ist die exakt konfigurierte Domain-Gruppe in `sys.server_principals` als Windows-Gruppe vorhanden?
+2. Existiert ihr Datenbankbenutzer in `BizTalkMgmtDb` und `BizTalkMsgBoxDb`?
+3. Ist dieser Benutzer in beiden Datenbanken Mitglied von `BTS_OPERATORS`?
+4. Entspricht diese Abbildung weiterhin der BizTalk-Konfiguration?
+
+Fehlende Zuordnungen werden fuer die konfigurierte Gruppe konsistent repariert. Ein individueller Login, manuelle Sonderrollen oder `sysadmin` fuer das Maschinenkonto waeren keine geeignete Abkuerzung.
+
 | Agent-Dump-Ergebnis | Massnahme |
 | --- | --- |
 | Plausible Werte fuer alle BizTalk-Services | Keine Berechtigungsaenderung. |

README.md

@@ -210,6 +210,12 @@ Damit ist der lokale Namespace `root\MicrosoftBizTalkServer` bereits erreichbar.
 
 `BizTalk Event Log` funktioniert unabhaengig von diesem SQL-Zugriff. Die dort sichtbaren zwei Fehler und sechs Warnungen sind echte Ereignisse im betrachteten Zeitfenster und nach Behebung der Berechtigung separat zu untersuchen.
 
+### Codekorrektur und Berechtigungsfreigabe sind zwei getrennte Schritte
+
+Die ueberarbeitete Version vergibt keine Windows-, Active-Directory- oder SQL-Rechte. Sie erkennt den eingebetteten SQL-Loginfehler nur korrekt, nennt das abgewiesene Konto und verhindert eine irrefuehrende Provider-/Konfigurationsdiagnose. Ohne Berechtigungsfreigabe bleibt der Check deshalb auch mit der neuen EXE `UNKNOWN`.
+
+Der Zugriff funktioniert erst, wenn `BEW\AV23AGPWBIO1$` Mitglied der exakt konfigurierten BizTalk-Operator-Gruppe ist und das erneuerte Maschinen-Token diese Mitgliedschaft enthaelt. Normalerweise ist diese Windows-Gruppe bereits durch die BizTalk-Konfiguration als SQL-Login beziehungsweise Datenbankbenutzer mit `BTS_OPERATORS` in den BizTalk-Datenbanken eingerichtet. Das Maschinenkonto erbt diese SQL-Rechte ueber seine Gruppenmitgliedschaft; ein eigener SQL-Login fuer `BEW\AV23AGPWBIO1$` ist dann weder erforderlich noch gewuenscht.
+
 ### Test im echten Checkmk-Kontext
 
 Ein manueller Aufruf von `BizTalkCheckmkPulse.exe` oder des Wrappers verwendet das Konto der angemeldeten Person. Ein erfolgreicher manueller Test beweist daher nicht, dass die Ausfuehrung durch Checkmk als `LocalSystem` ebenfalls funktioniert.
@@ -291,6 +297,8 @@ local:
 
 Die Operator-Rolle ist fuer grundlegende Administration und Monitoring vorgesehen und kann Zustands- und Message-Flow-Informationen lesen, ohne BizTalk-Konfiguration oder Nachrichteninhalte einzusehen. Das Plugin fuehrt ausschliesslich Leseabfragen aus. Direkte manuelle Aenderungen an BizTalk-SQL-Datenbankrollen sollten nicht vorgenommen werden; die von BizTalk konfigurierte Windows-Gruppe ist die vorgesehene Berechtigungsgrenze.
 
+Bleibt `Login failed` nach bestaetigter Gruppenmitgliedschaft, AD-Replikation und Token-Erneuerung bestehen, pruefen BizTalk- und SQL-Administration die Gruppenabbildung auf dem SQL Server. Die konfigurierte Domain-Gruppe muss als Windows-Gruppenlogin aufloesbar sein und ihre Datenbankbenutzer muessen den von BizTalk vorgesehenen Rollen angehoeren, insbesondere `BTS_OPERATORS` in `BizTalkMgmtDb` und `BizTalkMsgBoxDb`. Eine fehlende oder abweichende Abbildung wird mit der BizTalk-Konfiguration abgeglichen und fuer die Gruppe repariert, nicht durch einen ad-hoc Einzel-Login fuer das Maschinenkonto umgangen.
+
 Entscheidungsmatrix:
 
 | Ergebnis im Agent-Dump | Massnahme |

docs/ACC-WMI-SQL-Berechtigung.txt

@@ -19,6 +19,18 @@ Keine DCOM-, Firewall- oder WMI-Namespace-Rechte erweitern. Keinen direkten
 SQL-Login, keine manuellen BizTalk-Datenbankrollen und kein sysadmin fuer das
 Maschinenkonto anlegen.
 
+WICHTIG ZUR NEUEN VERSION
+=========================
+
+Die neue EXE repariert keine Berechtigungen. Sie erkennt den eingebetteten
+SQL-Loginfehler korrekt, zeigt BEW\AV23AGPWBIO1$ und klassifiziert die
+Folgediagnose als Berechtigungsproblem. Ohne die nachfolgende Freigabe bleiben
+die betroffenen Checks auch mit der neuen Version UNKNOWN.
+
+Die alte Version kann nach korrekter Freigabe grundsaetzlich funktionieren.
+Empfohlen ist die neue Version zusammen mit der Gruppenfreigabe, weil sie
+Fehlerursache, Konto und Massnahme eindeutig anzeigt.
+
 FREIGABE
 ========
 
@@ -82,6 +94,40 @@ Der separate Event-Log-Service zeigte im Screenshot zwei Fehler und sechs
 Warnungen. Diese Ereignisse bleiben nach der Berechtigungsfreigabe fachlich zu
 pruefen.
 
+WENN ES DANACH WEITERHIN SCHEITERT
+==================================
+
+Normalerweise wurde die konfigurierte BizTalk-Operator-Gruppe bereits durch die
+BizTalk-Konfiguration am SQL Server eingerichtet. Das Maschinenkonto erbt ueber
+seine AD-Gruppenmitgliedschaft die Rolle BTS_OPERATORS und benoetigt keinen
+eigenen SQL-Login.
+
+Bleibt "Login failed" trotz bestaetigter Mitgliedschaft, AD-Replikation und
+Token-Erneuerung bestehen, prueft die SQL-Administration read-only:
+
+  SELECT name, type_desc
+  FROM sys.server_principals
+  WHERE name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>';
+
+Danach jeweils in BizTalkMgmtDb und BizTalkMsgBoxDb:
+
+  SELECT
+      member_principal.name AS member_name,
+      role_principal.name AS role_name
+  FROM sys.database_role_members AS drm
+  JOIN sys.database_principals AS role_principal
+      ON role_principal.principal_id = drm.role_principal_id
+  JOIN sys.database_principals AS member_principal
+      ON member_principal.principal_id = drm.member_principal_id
+  WHERE member_principal.name =
+      N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>'
+    AND role_principal.name = N'BTS_OPERATORS';
+
+Fehlt die Abbildung, gleichen BizTalk- und SQL-Administration sie mit der
+BizTalk-Konfiguration ab und reparieren sie fuer die konfigurierte Gruppe.
+Keinen Einzel-Login oder Sonderrollen fuer BEW\AV23AGPWBIO1$ als Umgehung
+anlegen.
+
 SICHERHEIT
 ==========
 

docs/Integration.md

@@ -97,6 +97,17 @@ Auf `AV23AGPWBIO1` meldet der Provider `COMException HRESULT=0x80131904` und als
 
 Die vielen `UNKNOWN`-Services sind Folgewirkungen desselben Fehlers. WMI-Namespace-ACL, DCOM und Firewall muessen fuer diesen Befund nicht erweitert werden. Die zwei Fehler und sechs Warnungen in `BizTalk Event Log` sind davon unabhaengig und separat auszuwerten.
 
+### Was die neue Version aendert - und was nicht
+
+Die neue Version verbessert Diagnose und Betriebsfuehrung:
+
+- `0x80131904` mit `Login failed for user` wird als `Wmi/Permission` erkannt.
+- Das wirklich abgewiesene Konto wird aus der Providerfehlermeldung uebernommen.
+- Die unvollstaendige SQL-Zielermittlung wird als `Sql/Permission` statt als allgemeine Konfigurationstoerung ausgegeben.
+- Nach erfolgreichem Zugriff wird die konfigurierte Gruppe als `operator_group=` sichtbar.
+
+Die EXE kann und darf jedoch keine AD-Gruppenmitgliedschaft, SQL-Logins oder Datenbankrollen anlegen. Die alte Version kann nach korrekter Berechtigungsfreigabe grundsaetzlich arbeiten; die neue Version ohne Freigabe bleibt weiterhin `UNKNOWN`. Der Sollzustand ist daher: neue Version plus korrekte Gruppenberechtigung.
+
 ### Verbindlicher Funktionstest
 
 Der direkte Start des Wrappers in einer administrativen Eingabeaufforderung ist nur ein Vorabtest, weil er mit dem angemeldeten Benutzer laeuft. Fuer die Berechtigungspruefung ist die Ausgabe unter dem echten Checkmk-Kontext massgeblich:
@@ -144,6 +155,35 @@ Alternativ koennen die Checkmk-Kollegen in der Agent Bakery die Regeln `Set exec
 
 Die BizTalk-Operator-Rolle ist fuer grundlegende Administration und Monitoring vorgesehen. Sie kann Zustands- und Message-Flow-Informationen lesen, darf aber keine Konfiguration oder Nachrichteninhalte einsehen. Das entspricht dem lesenden Funktionsumfang dieses Plugins. Keine direkten SQL-Rollen in den BizTalk-Datenbanken hinzufuegen; die von BizTalk konfigurierte Windows-Gruppe soll die Berechtigungen vermitteln.
 
+### Wenn die Gruppenmitgliedschaft allein nicht genuegt
+
+Normalerweise hat die BizTalk-Konfiguration die konfigurierte Domain-Gruppe bereits auf dem SQL Server abgebildet und ihren Datenbankbenutzern die Rolle `BTS_OPERATORS` zugeordnet. Das Maschinenkonto benoetigt dann keinen eigenen SQL-Login, sondern erbt den Zugriff ueber die AD-Gruppe.
+
+Bleibt der Loginfehler nach AD-Replikation und Token-Erneuerung bestehen, prueft die SQL-Administration zunaechst read-only den Gruppenlogin:
+
+```sql
+SELECT name, type_desc
+FROM sys.server_principals
+WHERE name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>';
+```
+
+Anschliessend wird in `BizTalkMgmtDb` und `BizTalkMsgBoxDb` die Rollenzuordnung geprueft:
+
+```sql
+SELECT
+    member_principal.name AS member_name,
+    role_principal.name AS role_name
+FROM sys.database_role_members AS drm
+JOIN sys.database_principals AS role_principal
+    ON role_principal.principal_id = drm.role_principal_id
+JOIN sys.database_principals AS member_principal
+    ON member_principal.principal_id = drm.member_principal_id
+WHERE member_principal.name = N'BEW\<EXAKTE_BIZTALK_OPERATOR_GRUPPE>'
+  AND role_principal.name = N'BTS_OPERATORS';
+```
+
+Liefert die Abfrage keinen passenden Eintrag, wird die fehlende Gruppenabbildung mit der BizTalk-Konfiguration verglichen und durch BizTalk-/SQL-Administration fuer die konfigurierte Gruppe repariert. Kein Einzel-Login fuer `BEW\AV23AGPWBIO1$`, keine ad-hoc Rollenvergabe und kein `sysadmin` als Umgehung.
+
 Entscheidungsmatrix:
 
 | Beobachtung | Bewertung und Massnahme |