Exiger des connexions autorisées

La clé d'application est publique. Toute personne capable de charger votre page peut l'utiliser pour ouvrir une connexion et s'abonner à des canaux publics.

Les connexions autorisées exigent que chaque nouvelle connexion prouve qu'elle est autorisée dans les 30 secondes. Le edge Realtime ferme les connexions qui ne s'autorisent pas à temps.

Exiger des connexions autorisées

Activez Authorized connections pour l'application sur la page Realtime apps. Vous pouvez aussi définir authorized_connections à true via l'API Realtime. Le paramètre s'applique à chaque connexion utilisant l'une des clés de l'application.

Mettez à jour les clients pour qu'ils s'autorisent avant d'activer le paramètre en production. Les connexions établies avant l'activation restent ouvertes, mais les connexions ultérieures provenant de clients plus anciens échouent après le délai d'autorisation.

Ce qui compte comme autorisé

Une nouvelle connexion démarre non autorisée. L'une ou l'autre de ces actions l'autorise :

Un abonnement privé ou de présence réussit. Le client envoie l'identifiant de connexion à votre authEndpoint, votre backend le signe, et le edge vérifie la signature. Voir Autoriser les canaux.
signin() réussit. Le client envoie l'identifiant de connexion à votre memberAuthEndpoint et reçoit une identité de membre signée. Voir Résilier les connexions d'un membre pour le flux complet de connexion.

Les deux chemins prouvent la même chose : quelque chose détenant le secret de l'application s'est porté garant de cette connexion. S'abonner à un canal public ne prouve rien et n'autorise rien.

Le cas des canaux publics uniquement

Un client qui s'abonne uniquement à des canaux publics ne contacte normalement pas votre backend. Après avoir exigé des connexions autorisées, appelez signin() pour que la connexion puisse s'autoriser sans abonnement privé :

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  memberAuthEndpoint: "/bird/auth/member",
});

await bird.signin();

const status = bird.subscribe("build-status");
status.bind("build-finished", (data) => render(data));

import BirdRealtime

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    memberAuthEndpoint: URL(string: "https://your-backend.example.com/bird/auth/member")
))

try await bird.signin()

let status = bird.subscribe("build-status")
status.bind("build-finished") { data in
    render(data)
}

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        memberAuthEndpoint = "https://your-backend.example.com/bird/auth/member",
    )
)

bird.signin() // suspending

val status = bird.subscribe("build-status")
status.bind("build-finished") { data ->
    render(data)
}

Appelez signin() une seule fois. Le client se reconnecte à chaque reconnexion car l'identité appartient à la connexion. Renvoyez 403 Forbidden depuis votre endpoint d'autorisation de membre lorsque l'appelant ne doit pas se connecter.

Si l'application s'abonne à un canal privé ou de présence au chargement, l'abonnement réussi autorise déjà la connexion.

Ce que le client voit lorsqu'il ne s'autorise pas

Le edge ferme la connexion avec le code 4009 et la raison Connection not authorized within timeout. Les clients ne réessayent pas les codes dans cette plage, donc la connexion passe à l'état failed.

bird.connection.bind("error", ({ code, message }) => {
  if (code === 4009) console.warn(message);
});

bird.onError { error in
    if error.code == 4009 { print(error.message) }
}

bird.onError { error ->
    if (error.code == 4009) println(error.message)
}

Le code 4009 identifie aussi un membre dont votre backend a résilié les connexions. Vérifiez la raison avant de choisir un état connecté ou déconnecté. Voir Résilier les connexions d'un membre et Cycle de vie des connexions et reconnexion.

Les connexions ne sont pas comptabilisées dans le quota de connexions de l'application tant qu'elles ne sont pas autorisées.

Portée de l'autorisation

Exiger des connexions autorisées contrôle qui peut maintenir une connexion ouverte. Cela ne remplace pas les vérifications d'autorisation et ne change pas qui peut lire un canal :

Un canal public reste public pour toute connexion autorisée. Si les événements appartiennent à un client spécifique, utilisez un canal privé et vérifiez le nom du canal dans votre endpoint.
Toute personne pour laquelle vos endpoints d'authentification signent est autorisée, donc un endpoint permissif distribue l'autorisation aussi librement que la clé d'application.

Étapes suivantes

Autoriser les canaux est la signature que votre backend calcule pour les abonnements privés et de présence.
Les canaux privés sont l'outil adapté lorsque les événements eux-mêmes appartiennent à quelqu'un.
Résilier les connexions d'un membre couvre signin() et l'autre utilisation de 4009.
Envoyer des événements à un membre adresse un événement à une identité connectée plutôt qu'à un canal.
Cycle de vie des connexions et reconnexion explique pourquoi 4009 est terminal.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Explorer la fonctionnalitéRealtime Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first realtime event

Essayez la pratique et obtenez un guide d'implémentation