Chapitre 21

Conseils, bonnes pratiques et fonctionnalités cachées

Ce chapitre rassemble des fonctionnalités API moins connues, des recommandations de sécurité et des bonnes pratiques éprouvées pour l’intégration avec l’API BigBlueButton. Beaucoup de ces détails ne sont que partiellement documentés dans les sources officielles et ont été vérifiés par analyse du code source et recherche communautaire.

Valeur masquée de la politique des invités

En plus des trois valeurs bien connues du paramètre guestPolicy, il existe une quatrième valeur rarement documentée mais très utile pour les scénarios à audience mixte.

Valeur Comportement
ALWAYS_ACCEPT Tous les utilisateurs rejoignent immédiatement sans approbation.
ALWAYS_DENY Seuls les modérateurs peuvent rejoindre la réunion.
ASK_MODERATOR Les invités attendent dans le lobby jusqu’à ce qu’un modérateur les approuve.
ALWAYS_ACCEPT_AUTH Les utilisateurs authentifiés rejoignent directement. Seuls les invités non authentifiés nécessitent l’approbation d’un modérateur.

La politique ALWAYS_ACCEPT_AUTH est idéale lorsque des utilisateurs enregistrés provenant d’un LMS doivent rejoindre sans attendre, tandis que les invités externes doivent toujours être approuvés par un modérateur.

Callback côté serveur avec meetingEndedURL

Le paramètre meetingEndedURL fournit un rappel côté serveur qui diffère du meta_endCallbackUrl couramment utilisé sur des points importants :

  • Il n’est pas exposé au client et n’est pas stocké dans les enregistrements.
  • Il est utilisé en interne par des systèmes tels que Scalelite.
  • Il convient parfaitement aux intégrations côté serveur où l’URL de rappel doit rester masquée.
create?meetingID=replace-with-meeting-id&meetingEndedURL=https://api-guide.bbbserver.com/callbacks/internal&checksum=replace-with-checksum

Paramètres de capture des salles de sous-commission

Au-delà des paramètres standard des salles de répartition, BigBlueButton prend en charge des options supplémentaires pour réintégrer dans la réunion principale le contenu provenant des salles de répartition.

Paramètre Type Description
breakoutRoomsCaptureSlides Boolean Importer les diapositives des salles de sous-commission dans la réunion principale.
breakoutRoomsCaptureNotes Boolean Importer les notes partagées des salles de sous-commission dans la réunion principale.
breakoutRoomsCaptureNotesFilename String Nom de fichier personnalisé pour le fichier de notes capturées.

Paramètres d’annotation et d’image de marque

Le paramètre lockSettingsHideViewersAnnotation masque les annotations du tableau blanc effectuées par les autres spectateurs, de sorte que chaque participant ne voit que ses propres annotations et celles du présentateur. 

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

Le paramètre copyright définit un texte de copyright personnalisé dans le client BBB, ce qui peut être utile pour les déploiements en marque blanche : 

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

Le paramètre logo ne fonctionne que si displayBrandingArea=true est défini dans le fichier de configuration du serveur /etc/bigbluebutton/bbb-web.properties.

Bonnes pratiques de sécurité

Toujours inclure createTime dans les URL de jonction

Incluez toujours la valeur createTime de la réponse create dans votre URL join. Cela empêche la réutilisation d'anciens liens de jointure lorsqu'une nouvelle réunion est créée avec le même identifiant de réunion. 

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

Calcul du checksum pour les requêtes POST

Une erreur fréquente : le checksum est toujours calculé uniquement à partir de la chaîne de requête de l’URL, même pour les requêtes POST. Le corps de la requête (XML, JSON) n’est jamais inclus dans le calcul du checksum. 

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

Le corps POST (par ex. présentation XML) est envoyé séparément mais n’est pas haché.

Une vulnérabilité de sécurité passée (CVE GHSA-4m48-49h7-f3c4) permettait à des attaquants disposant d’une URL de jonction valide d’injecter des paramètres supplémentaires dans des liens de jonction signés. Validez et assainissez toujours tous les paramètres côté serveur avant de générer des URL API signées.

Changements incompatibles BBB 3.0

BigBlueButton 3.0 introduit plusieurs changements incompatibles qui affectent les intégrations API. Examinez attentivement le tableau suivant lors de la mise à niveau :

Changement Détails
password → role L'appel join utilise désormais role=MODERATOR ou role=VIEWER au lieu de mots de passe.
POST supprimé pour /join Seules les requêtes GET sont acceptées pour les appels join.
Content-Type requis Doit être spécifié pour toutes les requêtes POST.
Content-Types accepté pour /create application/x-www-form-urlencoded, multipart/form-data, application/xml, text/xml
Paramètres supprimés breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled ont été remplacés par le paramètre disabledFeatures.

Points de terminaison obsolètes

Les points de terminaison suivants sont obsolètes et ne doivent pas être utilisés dans les nouvelles intégrations :

Point de terminaison Statut Remplacement
getDefaultConfigXML Obsolète depuis BBB 2.4, supprimé dans BBB 3.0. clientSettingsOverride
setConfigXML Obsolète depuis BBB 2.4, supprimé dans BBB 3.0. clientSettingsOverride

Comportement de fusion du manifeste de plugin

Les manifestes de plugin provenant de trois sources sont fusionnés (et non écrasés) lorsqu'une réunion est créée :

  1. Configuration du serveur
  2. Paramètre pluginManifests dans l’appel create
  3. Paramètre pluginManifestsFetchUrl

Les doublons sont supprimés automatiquement. Cela permet une configuration flexible des plugins à plusieurs niveaux.

Options importantes de configuration du serveur

Les paramètres suivants de bigbluebutton.properties ne peuvent pas être contrôlés via l'API mais affectent directement le comportement de l'API :

Propriété Par défaut Description
supportedChecksumAlgorithms sha1,sha256,sha384,sha512 Algorithmes de somme de contrôle pris en charge pour l'authentification API.
maxUserConcurrentAccesses 3 Nombre maximal de sessions simultanées par utilisateur (par identifiant externe).
allowOverrideClientSettingsOnCreateCall false Active le paramètre clientSettingsOverride dans le corps de create.
allowRevealOfBBBVersion false Affiche la version BBB dans la réponse racine de l’API.
allowFetchAllRecordings true Autorise getRecordings sans filtre d'identifiant de réunion.
maxFileSizeUpload 30000000 Taille maximale de fichier pour les téléversements de présentation (30 Mo).
defaultHttpSessionTimeout 14400 Délai d'expiration de la session HTTP en secondes (4 heures).
sessionsCleanupDelayInMinutes 60 Les sessions restent actives pendant ce nombre de minutes après la fin d'une réunion.
fetchUrlSupportedProtocols https Protocoles autorisés pour la récupération d'URL (par ex. téléchargements de présentation).

Configuration du pont média

BigBlueButton 3.0 introduit LiveKit comme pont média alternatif. Les paramètres create suivants contrôlent quel pont est utilisé :

Paramètre Valeurs possibles Par défaut
cameraBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
screenShareBridge bbb-webrtc-sfu, livekit bbb-webrtc-sfu
audioBridge bbb-webrtc-sfu, livekit, freeswitch freeswitch

Délai d'expiration de conversion des présentations

À partir de BBB 3.0, le paramètre serveur maxPageConversionTime (par défaut : 60 secondes) limite le temps de conversion par diapositive. Les présentations complexes avec de nombreuses pages ou des graphismes lourds peuvent atteindre ce délai d’expiration, provoquant l’échec de la conversion des diapositives.

Si vos présentations dépassent fréquemment le délai de conversion, envisagez de les diviser en fichiers plus petits ou de simplifier les diapositives complexes avant le téléversement.

Foire aux questions

Il s’agit d’une quatrième valeur, moins connue, pour le paramètre guestPolicy. Les utilisateurs authentifiés rejoignent immédiatement, tandis que les invités non authentifiés doivent attendre l’approbation d’un modérateur. Cela est utile lorsque les utilisateurs d’un LMS doivent entrer directement mais que les visiteurs externes doivent être filtrés.

Le paramètre meetingEndedURL est un callback côté serveur qui n’est jamais exposé aux clients ni stocké dans les enregistrements. Il est conçu pour les intégrations internes où l’URL de callback doit rester privée, comme dans les déploiements Scalelite.

Non. Le checksum est toujours calculé uniquement à partir de la chaîne de requête de l’URL. Le corps POST (tel que la présentation XML) est envoyé séparément et ne fait pas partie du hachage. C’est une source fréquente d’erreurs pour les développeurs découvrant l’API.

Dans BigBlueButton 3.0, le paramètre password pour l’appel join a été remplacé par le paramètre role. Vous passez maintenant role=MODERATOR ou role=VIEWER au lieu du mot de passe participant ou modérateur.

Inclure la valeur createTime provenant de la réponse create garantit que les anciens liens de jonction ne peuvent pas être réutilisés pour une nouvelle réunion créée avec le même identifiant de réunion. C’est un mécanisme de sécurité important qui empêche les accès non autorisés via des URL périmées.

Les deux points de terminaison sont devenus obsolètes dans BBB 2.4 et ont été supprimés dans BBB 3.0. Ils ont été remplacés par le paramètre clientSettingsOverride dans l’appel create, qui offre un moyen plus flexible de personnaliser le comportement du client par réunion.