Rozdział 21

Wskazówki, najlepsze praktyki i ukryte funkcje

Ten rozdział zbiera mniej znane funkcje API, zalecenia dotyczące bezpieczeństwa i sprawdzone najlepsze praktyki integracji z API BigBlueButton. Wiele z tych szczegółów jest tylko częściowo udokumentowanych w oficjalnych źródłach i zostało zweryfikowanych poprzez analizę kodu źródłowego oraz badania społeczności.

Ukryta wartość polityki gości

Oprócz trzech dobrze znanych wartości parametru guestPolicy istnieje czwarta wartość, która jest rzadko dokumentowana, ale bardzo przydatna w scenariuszach z mieszaną grupą odbiorców.

Wartość Zachowanie
ALWAYS_ACCEPT Wszyscy użytkownicy dołączają natychmiast bez zatwierdzenia.
ALWAYS_DENY Tylko moderatorzy mogą dołączyć do spotkania.
ASK_MODERATOR Goście czekają w poczekalni, aż moderator ich zatwierdzi.
ALWAYS_ACCEPT_AUTH Uwierzytelnieni użytkownicy dołączają bezpośrednio. Tylko nieuwierzytelnieni goście wymagają zatwierdzenia przez moderatora.

Polityka ALWAYS_ACCEPT_AUTH jest idealna, gdy zarejestrowani użytkownicy z LMS mają dołączać bez oczekiwania, podczas gdy zewnętrzni goście nadal muszą zostać zatwierdzeni przez moderatora.

Callback po stronie serwera z meetingEndedURL

Parametr meetingEndedURL udostępnia callback po stronie serwera, który różni się od powszechnie używanego meta_endCallbackUrl w istotny sposób:

  • Nie jest ujawniany klientowi i nie jest przechowywany w nagraniach.
  • Jest używany wewnętrznie przez systemy takie jak Scalelite.
  • Dobrze nadaje się do integracji po stronie serwera, w których adres URL callbacku musi pozostać ukryty.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Parametry przechwytywania pokoi podgrup

Oprócz standardowych parametrów pokoi breakout, BigBlueButton obsługuje dodatkowe opcje przechwytywania treści z pokoi breakout z powrotem do głównego spotkania.

Parametr Typ Opis
breakoutRoomsCaptureSlides Boolean Importuj slajdy z pokoi podgrup do głównego spotkania.
breakoutRoomsCaptureNotes Boolean Importuj współdzielone notatki z pokoi podgrup do głównego spotkania.
breakoutRoomsCaptureNotesFilename String Niestandardowa nazwa pliku dla przechwyconego pliku notatek.

Parametry adnotacji i brandingu

Parametr lockSettingsHideViewersAnnotation ukrywa adnotacje na tablicy wykonane przez innych widzów, dzięki czemu każdy uczestnik widzi tylko własne adnotacje oraz adnotacje prezentera. 

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

Parametr copyright ustawia własny tekst praw autorskich w kliencie BBB, co może być przydatne w wdrożeniach white-label: 

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

Parametr logo działa tylko wtedy, gdy displayBrandingArea=true jest ustawione w pliku konfiguracji serwera /etc/bigbluebutton/bbb-web.properties.

Najlepsze praktyki bezpieczeństwa

Zawsze dołączaj createTime do URL-i dołączania

Zawsze dołączaj wartość createTime z odpowiedzi create do swojego adresu URL join. Zapobiega to ponownemu użyciu starych linków join, gdy nowe spotkanie zostanie utworzone z tym samym identyfikatorem spotkania. 

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

Obliczanie sumy kontrolnej dla żądań POST

Częsty błąd: suma kontrolna jest zawsze obliczana wyłącznie na podstawie ciągu zapytania URL, nawet dla żądań POST. Treść żądania (XML, JSON) nigdy nie jest uwzględniana przy obliczaniu sumy kontrolnej. 

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

Treść POST (np. prezentacja XML) jest wysyłana oddzielnie, ale nie jest haszowana.

Dawna podatność bezpieczeństwa (CVE GHSA-4m48-49h7-f3c4) pozwalała atakującym posiadającym prawidłowy URL dołączania wstrzykiwać dodatkowe parametry do podpisanych linków dołączania. Zawsze waliduj i sanitizuj wszystkie parametry po stronie serwera przed wygenerowaniem podpisanych URL-i API.

Zmiany niekompatybilne BBB 3.0

BigBlueButton 3.0 wprowadza kilka zmian niekompatybilnych, które wpływają na integracje API. Podczas aktualizacji uważnie przejrzyj poniższą tabelę:

Zmiana Szczegóły
password → role Wywołanie join używa teraz role=MODERATOR lub role=VIEWER zamiast haseł.
POST usunięto dla /join Dla wywołań GETjoin akceptowane są wyłącznie żądania .
Content-Type wymagane Musi być określone dla wszystkich żądań POST.
Akceptowane Content-Types dla /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Usunięte parametry breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled zostały zastąpione parametrem disabledFeatures.

Przestarzałe endpointy

Następujące endpointy są przestarzałe i nie powinny być używane w nowych integracjach:

Punkt końcowy Status Zastąpienie
getDefaultConfigXML Przestarzałe od BBB 2.4, usunięte w BBB 3.0. clientSettingsOverride
setConfigXML Przestarzałe od BBB 2.4, usunięte w BBB 3.0. clientSettingsOverride

Zachowanie scalania manifestów wtyczek

Manifesty wtyczek z trzech źródeł są scalane (a nie nadpisywane) podczas tworzenia spotkania:

  1. Konfiguracja serwera
  2. Parametr pluginManifests w wywołaniu create
  3. Parametr pluginManifestsFetchUrl

Duplikaty są usuwane automatycznie. Umożliwia to elastyczną konfigurację wtyczek na wielu poziomach.

Ważne opcje konfiguracji serwera

Następujące ustawienia z bigbluebutton.properties nie są sterowane przez API, ale bezpośrednio wpływają na działanie API:

Właściwość Domyślnie Opis
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Obsługiwane algorytmy sum kontrolnych do uwierzytelniania API.
maxUserConcurrentAccesses 3 Maksymalna liczba jednoczesnych sesji na użytkownika (według zewnętrznego ID).
allowOverrideClientSettingsOnCreateCall false Włącza parametr clientSettingsOverride w treści create.
allowRevealOfBBBVersion false Pokazuje wersję BBB w odpowiedzi głównego endpointu API.
allowFetchAllRecordings true Umożliwia getRecordings bez filtra identyfikatora spotkania.
maxFileSizeUpload 30000000 Maksymalny rozmiar pliku dla przesyłanych prezentacji (30 MB).
defaultHttpSessionTimeout 14400 Limit czasu sesji HTTP w sekundach (4 godziny).
sessionsCleanupDelayInMinutes 60 Sesje pozostają aktywne przez tyle minut po zakończeniu spotkania.
fetchUrlSupportedProtocols https Dozwolone protokoły do pobierania adresów URL (np. pobierania prezentacji).

Konfiguracja Media Bridge

BigBlueButton 3.0 wprowadza LiveKit jako alternatywny mostek mediów. Następujące parametry create kontrolują, który mostek jest używany:

Parametr Możliwe wartości Domyślnie
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Limit czasu konwersji prezentacji

Począwszy od BBB 3.0, parametr serwera maxPageConversionTime (domyślnie: 60 sekund) ogranicza czas konwersji na slajd. Złożone prezentacje z wieloma stronami lub ciężką grafiką mogą przekroczyć ten limit, powodując niepowodzenie konwersji slajdów.

Jeśli konwersja Twoich prezentacji często przekracza limit czasu, rozważ podzielenie ich na mniejsze pliki lub uproszczenie złożonych slajdów przed przesłaniem.

Najczęściej zadawane pytania

Jest to czwarta, mniej znana wartość parametru guestPolicy. Uwierzytelnieni użytkownicy dołączają natychmiast, natomiast nieuwierzytelnieni goście muszą czekać na akceptację moderatora. Jest to przydatne, gdy użytkownicy LMS powinni wchodzić bezpośrednio, ale zewnętrzni odwiedzający muszą zostać sprawdzeni.

Parametr meetingEndedURL jest callbackiem po stronie serwera, który nigdy nie jest ujawniany klientom ani przechowywany w nagraniach. Został zaprojektowany do integracji wewnętrznych, w których URL callbacku musi pozostać prywatny, na przykład w wdrożeniach Scalelite.

Nie. Suma kontrolna jest zawsze obliczana wyłącznie z ciągu zapytania URL. Treść POST (np. prezentacja XML) jest wysyłana oddzielnie i nie jest częścią hasha. To częste źródło błędów dla programistów nowych w tym API.

W BigBlueButton 3.0 parametr password dla wywołania join został zastąpiony parametrem role. Teraz przekazujesz role=MODERATOR lub role=VIEWER zamiast hasła uczestnika albo moderatora.

Dołączenie wartości createTime z odpowiedzi create zapewnia, że stare linki dołączania nie mogą zostać ponownie użyte dla nowego spotkania utworzonego z tym samym identyfikatorem spotkania. To ważny mechanizm bezpieczeństwa, który zapobiega nieautoryzowanemu dostępowi przez nieaktualne URL-e.

Oba endpointy zostały oznaczone jako przestarzałe w BBB 2.4 i usunięte w BBB 3.0. Zostały zastąpione przez parametr clientSettingsOverride w wywołaniu create, który zapewnia bardziej elastyczny sposób dostosowywania zachowania klienta dla każdego spotkania.