Kapitel 21

Tipps, Best Practices & Versteckte Funktionen

Dieses Kapitel sammelt weniger bekannte API-Funktionen, Sicherheitsempfehlungen und bewährte Best Practices für die Integration mit der BigBlueButton-API. Viele dieser Details sind in den offiziellen Quellen nur teilweise dokumentiert und wurden durch Quellcodeanalyse und Community-Recherche verifiziert.

Versteckter Wert der Gast-Richtlinie

Zusätzlich zu den drei bekannten Werten für den Parameter guestPolicy gibt es einen vierten Wert, der selten dokumentiert ist, aber für Szenarien mit gemischtem Publikum sehr nützlich ist.

Wert Verhalten
ALWAYS_ACCEPT Alle Benutzer treten sofort ohne Genehmigung bei.
ALWAYS_DENY Nur Moderatoren können dem Meeting beitreten.
ASK_MODERATOR Gäste warten in der Lobby, bis ein Moderator sie genehmigt.
ALWAYS_ACCEPT_AUTH Authentifizierte Benutzer treten direkt bei. Nur nicht authentifizierte Gäste benötigen die Genehmigung eines Moderators.

Die Richtlinie ALWAYS_ACCEPT_AUTH ist ideal, wenn registrierte Benutzer aus einem LMS ohne Wartezeit beitreten sollen, während externe Gäste weiterhin von einem Moderator genehmigt werden müssen.

Serverseitiger Callback mit meetingEndedURL

Der Parameter meetingEndedURL bietet einen serverseitigen Callback, der sich in wichtigen Punkten vom häufig verwendeten meta_endCallbackUrl unterscheidet:

  • Er wird dem Client nicht offengelegt und nicht in Aufzeichnungen gespeichert.
  • Er wird intern von Systemen wie Scalelite verwendet.
  • Er eignet sich gut für serverseitige Integrationen, bei denen die Callback-URL verborgen bleiben muss.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Erfassungsparameter für Breakout-Räume

Über die Standardparameter für Breakout-Räume hinaus unterstützt BigBlueButton zusätzliche Optionen, um Inhalte aus Breakout-Räumen zurück in das Hauptmeeting zu übernehmen.

Parameter Typ Beschreibung
breakoutRoomsCaptureSlides Boolean Folien aus Breakout-Räumen in das Hauptmeeting importieren.
breakoutRoomsCaptureNotes Boolean Geteilte Notizen aus Breakout-Räumen in das Hauptmeeting importieren.
breakoutRoomsCaptureNotesFilename String Benutzerdefinierter Dateiname für die erfasste Notizdatei.

Parameter für Anmerkungen und Branding

Der Parameter lockSettingsHideViewersAnnotation blendet Whiteboard-Anmerkungen anderer Zuschauer aus, sodass jeder Teilnehmer nur seine eigenen Anmerkungen und die des Präsentators sieht. 

create?meetingID=replace-with-meeting-id&lockSettingsHideViewersAnnotation=true&checksum=replace-with-checksum

Der Parameter copyright setzt einen benutzerdefinierten Copyright-Text im BBB-Client, was für White-Label-Deployments nützlich sein kann: 

create?meetingID=replace-with-meeting-id&copyright=Example+Organization&checksum=replace-with-checksum

Der Parameter logo funktioniert nur, wenn displayBrandingArea=true in der Server-Konfigurationsdatei /etc/bigbluebutton/bbb-web.properties gesetzt ist.

Bewährte Sicherheitspraktiken

createTime immer in Join-URLs einschließen

Fügen Sie den Wert createTime aus der Antwort von create immer in Ihre join-URL ein. Dadurch wird verhindert, dass alte Join-Links erneut verwendet werden, wenn ein neues Meeting mit derselben Meeting-ID erstellt wird. 

join?meetingID=replace-with-meeting-id&fullName=Max&role=VIEWER&createTime=1715261728123&checksum=replace-with-checksum

Checksum-Berechnung für POST-Anfragen

Ein häufiger Fehler: Die Checksumme wird immer nur aus dem URL-Query-String berechnet, selbst bei POST-Anfragen. Der Request-Body (XML, JSON) wird niemals in die Checksum-Berechnung einbezogen. 

Checksum = SHA256("create" + "meetingID=replace-with-meeting-id&name=Demo" + "replace-with-secret")

Der POST-Body (z. B. Präsentations-XML) wird separat gesendet, aber nicht gehasht.

Eine frühere Sicherheitslücke (CVE GHSA-4m48-49h7-f3c4) ermöglichte es Angreifern mit einer gültigen Join-URL, zusätzliche Parameter in signierte Join-Links einzuschleusen. Validieren und bereinigen Sie immer alle Parameter serverseitig, bevor Sie signierte API-URLs erzeugen.

BBB 3.0 Inkompatible Änderungen

BigBlueButton 3.0 führt mehrere inkompatible Änderungen ein, die API-Integrationen betreffen. Prüfen Sie die folgende Tabelle sorgfältig vor einem Upgrade:

Änderung Details
password → role Der Aufruf join verwendet jetzt role=MODERATOR oder role=VIEWER anstelle von Passwörtern.
POST entfernt für /join Für Aufrufe von GETjoin werden nur -Anfragen akzeptiert.
Content-Type erforderlich Muss für alle POST-Anfragen angegeben werden.
Akzeptierte Content-Types für /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Entfernte Parameter breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled wurden durch den Parameter disabledFeatures ersetzt.

Veraltete Endpunkte

Die folgenden Endpunkte sind veraltet und sollten in neuen Integrationen nicht verwendet werden:

Endpunkt Status Ersatz
getDefaultConfigXML Seit BBB 2.4 veraltet, in BBB 3.0 entfernt. clientSettingsOverride
setConfigXML Seit BBB 2.4 veraltet, in BBB 3.0 entfernt. clientSettingsOverride

Merge-Verhalten von Plugin-Manifests

Plugin-Manifeste aus drei Quellen werden beim Erstellen eines Meetings zusammengeführt (nicht überschrieben):

  1. Serverkonfiguration
  2. Parameter pluginManifests im Aufruf create
  3. Parameter pluginManifestsFetchUrl

Duplikate werden automatisch entfernt. Dies ermöglicht eine flexible Plugin-Konfiguration über mehrere Ebenen hinweg.

Wichtige Serverkonfigurationsoptionen

Die folgenden Einstellungen aus bigbluebutton.properties können nicht über die API gesteuert werden, beeinflussen aber direkt das API-Verhalten:

Eigenschaft Standard Beschreibung
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Unterstützte Prüfsummenalgorithmen für die API-Authentifizierung.
maxUserConcurrentAccesses 3 Maximale Anzahl gleichzeitiger Sitzungen pro Benutzer (nach externer ID).
allowOverrideClientSettingsOnCreateCall false Aktiviert den Parameter clientSettingsOverride im Body von create.
allowRevealOfBBBVersion false Zeigt die BBB-Version in der API-Root-Antwort an.
allowFetchAllRecordings true Erlaubt getRecordings ohne Filter nach Meeting-ID.
maxFileSizeUpload 30000000 Maximale Dateigröße für Präsentations-Uploads (30 MB).
defaultHttpSessionTimeout 14400 HTTP-Sitzungs-Timeout in Sekunden (4 Stunden).
sessionsCleanupDelayInMinutes 60 Sitzungen bleiben noch so viele Minuten nach Ende eines Meetings aktiv.
fetchUrlSupportedProtocols https Erlaubte Protokolle für URL-Abrufe (z. B. Präsentations-Downloads).

Media-Bridge-Konfiguration

BigBlueButton 3.0 führt LiveKit als alternative Medienbrücke ein. Die folgenden Parameter von create steuern, welche Brücke verwendet wird:

Parameter Mögliche Werte Standard
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Timeout für die Präsentationskonvertierung

Ab BBB 3.0 begrenzt der Serverparameter maxPageConversionTime (Standard: 60 Sekunden) die Konvertierungszeit pro Folie. Komplexe Präsentationen mit vielen Seiten oder aufwendiger Grafik können dieses Timeout erreichen, wodurch Folien nicht konvertiert werden.

Wenn bei Ihren Präsentationen die Konvertierung häufig wegen eines Timeouts fehlschlägt, sollten Sie erwägen, sie in kleinere Dateien aufzuteilen oder komplexe Folien vor dem Upload zu vereinfachen.

Häufig gestellte Fragen

Es ist ein vierter, weniger bekannter Wert für den Parameter guestPolicy. Authentifizierte Benutzer treten sofort bei, während nicht authentifizierte Gäste auf die Freigabe durch einen Moderator warten müssen. Das ist nützlich, wenn LMS-Benutzer direkt eintreten sollen, externe Besucher aber überprüft werden müssen.

Der Parameter meetingEndedURL ist ein serverseitiger Callback, der niemals an Clients weitergegeben oder in Aufzeichnungen gespeichert wird. Er ist für interne Integrationen gedacht, bei denen die Callback-URL privat bleiben muss, etwa in Scalelite-Deployments.

Nein. Die Checksumme wird immer nur aus dem URL-Query-String berechnet. Der POST-Body (wie etwa Präsentations-XML) wird separat gesendet und ist nicht Teil des Hashs. Dies ist eine häufige Fehlerquelle für Entwickler, die neu mit der API arbeiten.

In BigBlueButton 3.0 wurde der Parameter password für den Aufruf join durch den Parameter role ersetzt. Sie übergeben jetzt role=MODERATOR oder role=VIEWER anstelle des Teilnehmer- oder Moderatorpassworts.

Das Einbeziehen des Werts createTime aus der Antwort von create stellt sicher, dass alte Join-Links nicht für ein neues Meeting mit derselben Meeting-ID wiederverwendet werden können. Dies ist ein wichtiger Sicherheitsmechanismus, der unbefugten Zugriff über veraltete URLs verhindert.

Beide Endpunkte wurden in BBB 2.4 als veraltet markiert und in BBB 3.0 entfernt. Sie wurden durch den Parameter clientSettingsOverride im Aufruf create ersetzt, der eine flexiblere Möglichkeit bietet, das Client-Verhalten pro Meeting anzupassen.