Hoofdstuk 21

Tips, best practices & verborgen functies

Dit hoofdstuk verzamelt minder bekende API-functies, beveiligingsaanbevelingen en beproefde best practices voor integratie met de BigBlueButton-API. Veel van deze details zijn slechts gedeeltelijk gedocumenteerd in de officiële bronnen en zijn geverifieerd via broncodeanalyse en onderzoek door de community.

Verborgen waarde voor gastbeleid

Naast de drie bekende waarden voor de parameter guestPolicy is er een vierde waarde die zelden wordt gedocumenteerd maar zeer nuttig is voor scenario's met een gemengd publiek.

Waarde Gedrag
ALWAYS_ACCEPT Alle gebruikers nemen direct deel zonder goedkeuring.
ALWAYS_DENY Alleen moderators kunnen deelnemen aan de vergadering.
ASK_MODERATOR Gasten wachten in de lobby totdat een moderator hen goedkeurt.
ALWAYS_ACCEPT_AUTH Geverifieerde gebruikers nemen direct deel. Alleen niet-geverifieerde gasten hebben goedkeuring van een moderator nodig.

Het beleid ALWAYS_ACCEPT_AUTH is ideaal wanneer geregistreerde gebruikers vanuit een LMS zonder te wachten moeten kunnen deelnemen, terwijl externe gasten nog steeds door een moderator moeten worden goedgekeurd.

Server-side callback met meetingEndedURL

De parameter meetingEndedURL biedt een server-side callback die op belangrijke punten verschilt van de veelgebruikte meta_endCallbackUrl:

  • Deze wordt niet aan de client blootgesteld en niet in opnames opgeslagen.
  • Dit wordt intern gebruikt door systemen zoals Scalelite.
  • Deze is zeer geschikt voor server-side integraties waarbij de callback-URL verborgen moet blijven.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Capture-parameters voor breakout rooms

Naast de standaardparameters voor breakout rooms ondersteunt BigBlueButton extra opties om inhoud uit breakout rooms terug te halen naar de hoofdvergadering.

Parameter Type Beschrijving
breakoutRoomsCaptureSlides Boolean Importeer slides uit breakout rooms in de hoofdvergadering.
breakoutRoomsCaptureNotes Boolean Importeer gedeelde notities uit breakout rooms in de hoofdvergadering.
breakoutRoomsCaptureNotesFilename String Aangepaste bestandsnaam voor het vastgelegde notitiebestand.

Parameters voor annotatie en branding

De parameter lockSettingsHideViewersAnnotation verbergt whiteboardannotaties die door andere kijkers zijn gemaakt, zodat elke deelnemer alleen zijn of haar eigen annotaties en die van de presentator ziet. 

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

De parameter copyright stelt een aangepaste copyrighttekst in de BBB-client in, wat nuttig kan zijn voor white-label-deployments: 

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

De parameter logo werkt alleen als displayBrandingArea=true is ingesteld in het serverconfiguratiebestand /etc/bigbluebutton/bbb-web.properties.

Beveiligingsbest practices

Neem createTime altijd op in join-URL's

Neem de waarde createTime uit het antwoord van create altijd op in je join-URL. Dit voorkomt dat oude join-links opnieuw worden gebruikt wanneer een nieuwe vergadering met dezelfde meeting-ID wordt aangemaakt. 

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

Checksum-berekening voor POST-requests

Een veelgemaakte fout: de checksum wordt altijd alleen berekend op basis van de URL-querystring, zelfs voor POST-requests. De requestbody (XML, JSON) wordt nooit meegenomen in de checksum-berekening. 

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

De POST-body (bijv. presentatie-XML) wordt apart verzonden maar niet gehasht.

Een eerdere beveiligingskwetsbaarheid (CVE GHSA-4m48-49h7-f3c4) maakte het mogelijk voor aanvallers met een geldige join-URL om extra parameters in ondertekende join-links te injecteren. Valideer en saneer altijd alle parameters server-side voordat je ondertekende API-URL's genereert.

BBB 3.0 Incompatibele wijzigingen

BigBlueButton 3.0 introduceert verschillende incompatibele wijzigingen die API-integraties beïnvloeden. Bekijk de volgende tabel zorgvuldig bij het upgraden:

Wijziging Details
password → role De aanroep join gebruikt nu role=MODERATOR of role=VIEWER in plaats van wachtwoorden.
POST verwijderd voor /join Alleen GET-requests worden geaccepteerd voor join-calls.
Content-Type vereist Moet worden opgegeven voor alle POST-requests.
Content-Types geaccepteerd voor /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Verwijderde parameters breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled zijn vervangen door de parameter disabledFeatures.

Verouderde endpoints

De volgende endpoints zijn verouderd en moeten niet worden gebruikt in nieuwe integraties:

Endpoint Status Vervanging
getDefaultConfigXML Verouderd sinds BBB 2.4, verwijderd in BBB 3.0. clientSettingsOverride
setConfigXML Verouderd sinds BBB 2.4, verwijderd in BBB 3.0. clientSettingsOverride

Samenvoeggedrag van pluginmanifesten

Pluginmanifesten uit drie bronnen worden samengevoegd (niet overschreven) wanneer een vergadering wordt aangemaakt:

  1. Serverconfiguratie
  2. Parameter pluginManifests in de create-call
  3. parameter pluginManifestsFetchUrl

Duplicaten worden automatisch verwijderd. Dit maakt flexibele pluginconfiguratie op meerdere niveaus mogelijk.

Belangrijke serverconfiguratieopties

De volgende instellingen uit bigbluebutton.properties kunnen niet via de API worden aangestuurd, maar hebben wel direct invloed op het API-gedrag:

Eigenschap Standaard Beschrijving
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Ondersteunde checksumalgoritmen voor API-authenticatie.
maxUserConcurrentAccesses 3 Maximum aantal gelijktijdige sessies per gebruiker (op externe ID).
allowOverrideClientSettingsOnCreateCall false Schakelt de parameter clientSettingsOverride in de body van create in.
allowRevealOfBBBVersion false Toont de versie van BBB in de API-rootresponse.
allowFetchAllRecordings true Staat getRecordings toe zonder filter op meeting-ID.
maxFileSizeUpload 30000000 Maximale bestandsgrootte voor presentatie-uploads (30 MB).
defaultHttpSessionTimeout 14400 HTTP-sessietime-out in seconden (4 uur).
sessionsCleanupDelayInMinutes 60 Sessies blijven zoveel minuten actief nadat een vergadering is beëindigd.
fetchUrlSupportedProtocols https Toegestane protocollen voor het ophalen van URL's (bijv. presentatiedownloads).

Configuratie van de mediabrug

BigBlueButton 3.0 introduceert LiveKit als alternatieve mediabrug. De volgende create-parameters bepalen welke brug wordt gebruikt:

Parameter Mogelijke waarden Standaard
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Time-out voor presentatieconversie

Vanaf BBB 3.0 beperkt de serverparameter maxPageConversionTime (standaard: 60 seconden) de conversietijd per slide. Complexe presentaties met veel pagina's of zware graphics kunnen deze timeout bereiken, waardoor slides niet worden geconverteerd.

Als je presentaties vaak een time-out krijgen tijdens de conversie, overweeg dan om ze op te splitsen in kleinere bestanden of complexe dia's te vereenvoudigen voordat je ze uploadt.

Veelgestelde vragen

Het is een vierde, minder bekende waarde voor de parameter guestPolicy. Geauthenticeerde gebruikers nemen direct deel, terwijl niet-geauthenticeerde gasten moeten wachten op goedkeuring van een moderator. Dit is nuttig wanneer LMS-gebruikers direct moeten kunnen binnenkomen, maar externe bezoekers eerst moeten worden gescreend.

De parameter meetingEndedURL is een server-side callback die nooit aan clients wordt blootgesteld en niet in opnames wordt opgeslagen. Deze is ontworpen voor interne integraties waarbij de callback-URL privé moet blijven, zoals bij Scalelite-deployments.

Nee. De checksum wordt altijd alleen berekend op basis van de URL-querystring. De POST-body (zoals presentatie-XML) wordt apart verzonden en maakt geen deel uit van de hash. Dit is een veelvoorkomende foutbron voor ontwikkelaars die nieuw zijn met de API.

In BigBlueButton 3.0 is de parameter password voor de call join vervangen door de parameter role. Je geeft nu role=MODERATOR of role=VIEWER door in plaats van het deelnemer- of moderatorwachtwoord.

Door de createTime-waarde uit de response van create op te nemen, zorg je ervoor dat oude join-links niet opnieuw kunnen worden gebruikt voor een nieuwe vergadering die met dezelfde meeting-ID is aangemaakt. Dit is een belangrijk beveiligingsmechanisme dat ongeautoriseerde toegang via verouderde URL's voorkomt.

Beide endpoints zijn verouderd verklaard in BBB 2.4 en verwijderd in BBB 3.0. Ze zijn vervangen door de parameter clientSettingsOverride in de call create, die een flexibelere manier biedt om clientgedrag per vergadering aan te passen.