Présentation de l'Auth Relay

L’Auth Relay est un courtier multi-tenant qui permet à n’importe quel backend de pousser des invites d’approbation — TOTP, golden number, biométrie — vers l’application mobile Bloonio Authenticator, y compris lorsque l’application est fermée, sans jamais détenir les identifiants de push de la plateforme.

Le problème qu’il résout

Bloonio Authenticator est un authentificateur générique (comme Google Authenticator ou GitHub Mobile). Un même appareil peut être appairé avec un nombre quelconque de backends indépendants via un scan de QR code. Chaque backend veut pousser des invites d’approbation vers l’appareil.

Or les notifications push mobiles exigent des identifiants de plateforme (FCM sur Android, APNs sur iOS). Ces identifiants sont liés à l’application, pas au backend — on ne peut donc pas les distribuer à chaque backend tenant. Le relais détient ces identifiants de façon centralisée ; les backends s’authentifient par requêtes signées en HMAC et demandent au relais de pousser.

Backend A ─┐
Backend B ─┼─ HTTPS signé ─►  Auth Relay  ─ FCM ─►  Bloonio Authenticator (appareil)
Backend N ─┘                  (identifiants FCM, registre des tenants)

Le push iOS passe par APNs via le proxy FCM : la clé d’authentification APNs (.p8) est déposée une fois dans la console Firebase, puis FCM relaie vers Apple. Un identifiant, un chemin de code.

Le modèle d’identité

Tenant — un par backend. Provisionné une fois, reçoit un tenant_id et un tenant_secret. Le backend utilise le secret pour signer chaque requête en HMAC.
Appairage (pairing) — un par couple (tenant_id, user_socket_hash). Créé quand un utilisateur appaire l’application avec un backend. Le user_socket_hash existe déjà dans le système Bloonio ; le relais le réutilise.
Jetons d’appareil — les jetons FCM enregistrés contre un appairage. Un appairage peut porter plusieurs jetons (multi-appareils).

L’identifiant opaque relay_user_id est le validateur universel côté relais — c’est le pivot que vous stockez et passez aux dispatches sudo. Voir Multi-tenant & relay_user_id pour le modèle complet (inspiré de Stripe Connect).

Relation avec `bloonio_auth_api`

L’Auth Relay est un courtier de transport : pour les flux QR-login, sudo et WebAuthn, il valide la requête du tenant (HMAC #1), y attache le contexte du tenant authentifié, puis la transmet à bloonio_auth_api (signée en HMAC #2). auth_api est la source de vérité pour l’identité, les groupes de validation et les credentials passkey ; le relais ne stocke localement que le registre des tenants et les tables de routage de push (appairages + jetons d’appareil).

Tenant ── HMAC #1 ─►  Auth Relay  ── HMAC #2 ─►  bloonio_auth_api
                       (registre tenants,           (identité, groupes,
                        appairages, push FCM)         credentials passkey)

Carte des flux

Démarrage rapide Provisionnez un tenant et faites votre premier appel signé.

Gestion des tenants Cycle de vie admin : provision, mise à jour, rotation, suspension.

Appairage & appareils prepare-pairing → pairing_proof → device_session_token.

Push & alertes de sécurité Challenges d'approbation et notifications passives.

Connexion par QR Initier et interroger une session de connexion par QR code.

Sudo (élévation) Dispatch sudo et protocole en deux appels.

Passkeys (WebAuthn) Enrôlement, connexion et gestion des credentials.

SDK Python RelayClient, AsyncRelayClient et @sudo_required.

Avant de coder

Lisez Authentification (HMAC) — toutes les requêtes tenant /relay/* sont signées avec la même recette HMAC #1.
Comprenez le cycle de vie d’un tenant : provisionnement, secret affiché une seule fois, rotation, suspension.
Si vos appels arrivent depuis un backend Python, sautez l’implémentation manuelle de la signature et utilisez le SDK Python.