Capitolo 21

Suggerimenti, best practice e funzionalità nascoste

Questo capitolo raccoglie funzionalità API meno note, raccomandazioni di sicurezza e best practice comprovate per l'integrazione con l'API BigBlueButton. Molti di questi dettagli sono documentati solo parzialmente nelle fonti ufficiali e sono stati verificati tramite analisi del codice sorgente e ricerche della community.

Valore nascosto della policy degli ospiti

Oltre ai tre valori ben noti per il parametro guestPolicy, esiste un quarto valore raramente documentato ma molto utile per scenari con pubblico misto.

Valore Comportamento
ALWAYS_ACCEPT Tutti gli utenti entrano immediatamente senza approvazione.
ALWAYS_DENY Solo i moderatori possono entrare nella riunione.
ASK_MODERATOR Gli ospiti attendono nella lobby finché un moderatore non li approva.
ALWAYS_ACCEPT_AUTH Gli utenti autenticati entrano direttamente. Solo gli ospiti non autenticati richiedono l'approvazione di un moderatore.

La policy ALWAYS_ACCEPT_AUTH è ideale quando gli utenti registrati provenienti da un LMS devono entrare senza attendere, mentre gli ospiti esterni devono comunque essere approvati da un moderatore.

Callback lato server con meetingEndedURL

Il parametro meetingEndedURL fornisce un callback lato server che differisce in modo importante dal più comune meta_endCallbackUrl:

  • Non è esposto al client e non viene memorizzato nelle registrazioni.
  • Viene usato internamente da sistemi come Scalelite.
  • È molto adatto per integrazioni lato server in cui l'URL di callback deve rimanere nascosto.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Parametri di acquisizione delle breakout room

Oltre ai parametri standard delle breakout room, BigBlueButton supporta opzioni aggiuntive per acquisire contenuti dalle breakout room e riportarli nella riunione principale.

Parametro Tipo Descrizione
breakoutRoomsCaptureSlides Boolean Importa le diapositive dalle breakout room nella riunione principale.
breakoutRoomsCaptureNotes Boolean Importa le note condivise dalle breakout room nella riunione principale.
breakoutRoomsCaptureNotesFilename String Nome file personalizzato per il file delle note acquisite.

Parametri di annotazione e branding

Il parametro lockSettingsHideViewersAnnotation nasconde le annotazioni sulla lavagna fatte dagli altri visualizzatori, in modo che ogni partecipante veda solo le proprie annotazioni e quelle del presentatore. 

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

Il parametro copyright imposta un testo di copyright personalizzato nel client BBB, che può essere utile per deployment white-label: 

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

Il parametro logo funziona solo se displayBrandingArea=true è impostato nel file di configurazione del server /etc/bigbluebutton/bbb-web.properties.

Migliori pratiche di sicurezza

Includi sempre createTime negli URL di join

Includi sempre il valore createTime della risposta create nel tuo URL join. Questo impedisce il riutilizzo di vecchi link di join quando viene creata una nuova riunione con lo stesso ID riunione. 

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

Calcolo del checksum per richieste POST

Un errore comune: il checksum viene sempre calcolato solo sulla query string dell'URL, anche per le richieste POST. Il corpo della richiesta (XML, JSON) non viene mai incluso nel calcolo del checksum. 

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

Il corpo POST (ad es. presentazione XML) viene inviato separatamente ma non viene sottoposto ad hash.

Una vulnerabilità di sicurezza passata (CVE GHSA-4m48-49h7-f3c4) permetteva agli attaccanti con un URL di join valido di iniettare parametri aggiuntivi nei link di join firmati. Valida e sanifica sempre tutti i parametri lato server prima di generare URL API firmati.

BBB 3.0 Modifiche incompatibili

BigBlueButton 3.0 introduce diverse modifiche incompatibili che influenzano le integrazioni API. Esamina attentamente la seguente tabella durante l'aggiornamento:

Modifica Dettagli
password → role La chiamata join ora usa role=MODERATOR o role=VIEWER invece delle password.
POST rimosso per /join Sono accettate solo richieste GET per le chiamate join.
Content-Type obbligatorio Deve essere specificato per tutte le richieste POST.
Content-Types accettato per /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Parametri rimossi breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled sono stati sostituiti dal parametro disabledFeatures.

Endpoint deprecati

I seguenti endpoint sono deprecati e non dovrebbero essere usati nelle nuove integrazioni:

Endpoint Stato Sostituzione
getDefaultConfigXML Deprecato da BBB 2.4, rimosso in BBB 3.0. clientSettingsOverride
setConfigXML Deprecato da BBB 2.4, rimosso in BBB 3.0. clientSettingsOverride

Comportamento di unione del manifest dei plugin

I manifest dei plugin provenienti da tre fonti vengono uniti (non sovrascritti) quando viene creata una riunione:

  1. Configurazione del server
  2. Parametro pluginManifests nella chiamata create
  3. Parametro pluginManifestsFetchUrl

I duplicati vengono rimossi automaticamente. Questo consente una configurazione flessibile dei plugin su più livelli.

Opzioni importanti di configurazione del server

Le seguenti impostazioni di bigbluebutton.properties non sono controllabili tramite API, ma influiscono direttamente sul comportamento dell'API:

Proprietà Predefinito Descrizione
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Algoritmi di checksum supportati per l'autenticazione API.
maxUserConcurrentAccesses 3 Numero massimo di sessioni simultanee per utente (per ID esterno).
allowOverrideClientSettingsOnCreateCall false Abilita il parametro clientSettingsOverride nel corpo di create.
allowRevealOfBBBVersion false Mostra la versione BBB nella risposta della radice API.
allowFetchAllRecordings true Consente getRecordings senza un filtro per ID riunione.
maxFileSizeUpload 30000000 Dimensione massima del file per i caricamenti di presentazioni (30 MB).
defaultHttpSessionTimeout 14400 Timeout della sessione HTTP in secondi (4 ore).
sessionsCleanupDelayInMinutes 60 Le sessioni rimangono attive per questo numero di minuti dopo la fine di una riunione.
fetchUrlSupportedProtocols https Protocolli consentiti per il recupero degli URL (ad es. download delle presentazioni).

Configurazione del Media Bridge

BigBlueButton 3.0 introduce LiveKit come bridge multimediale alternativo. I seguenti parametri create controllano quale bridge viene usato:

Parametro Valori possibili Predefinito
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Timeout di conversione della presentazione

A partire da BBB 3.0, il parametro server maxPageConversionTime (predefinito: 60 secondi) limita il tempo di conversione per diapositiva. Presentazioni complesse con molte pagine o grafica pesante possono raggiungere questo timeout, causando il fallimento della conversione delle diapositive.

Se le tue presentazioni vanno frequentemente in timeout durante la conversione, valuta la possibilità di suddividerle in file più piccoli o di semplificare le diapositive complesse prima del caricamento.

Domande frequenti

È un quarto valore, meno noto, per il parametro guestPolicy. Gli utenti autenticati entrano immediatamente, mentre gli ospiti non autenticati devono attendere l'approvazione del moderatore. Questo è utile quando gli utenti LMS devono entrare direttamente ma i visitatori esterni devono essere controllati.

Il parametro meetingEndedURL è una callback lato server che non viene mai esposta ai client né memorizzata nelle registrazioni. È progettato per integrazioni interne in cui l'URL di callback deve rimanere privato, come nei deployment Scalelite.

No. Il checksum viene sempre calcolato solo sulla query string dell'URL. Il corpo POST (come la presentazione XML) viene inviato separatamente e non fa parte dell'hash. Questa è una fonte comune di errori per gli sviluppatori nuovi all'API.

In BigBlueButton 3.0, il parametro password per la chiamata join è stato sostituito dal parametro role. Ora passi role=MODERATOR o role=VIEWER invece della password del partecipante o del moderatore.

Includere il valore createTime dalla risposta create assicura che i vecchi link di join non possano essere riutilizzati per una nuova riunione creata con lo stesso ID riunione. È un importante meccanismo di sicurezza che impedisce accessi non autorizzati tramite URL obsoleti.

Entrambi gli endpoint sono stati deprecati in BBB 2.4 e rimossi in BBB 3.0. Sono stati sostituiti dal parametro clientSettingsOverride nella chiamata create, che fornisce un modo più flessibile per personalizzare il comportamento del client per riunione.