Connexion Atmosphere

Le paquet @emdash-cms/auth-atproto ajoute à EmDash une option de connexion par compte Atmosphere. Un compte Atmosphere est une identité portable, détenue par l’utilisateur, utilisée sur Bluesky et d’autres applis du réseau AT Protocol. Les utilisateurs se connectent avec leur handle (p. ex. alice.bsky.social) et s’authentifient chez leur propre fournisseur — EmDash ne voit jamais de mot de passe.

C’est pertinent lorsque :

• Vos contributeurs ont déjà un compte Atmosphere.
• Vous voulez restreindre un domaine contrôlé par l’organisation (*.votresociete.com) sans gérer d’applications OAuth ni d’invitations.
• Vous construisez quelque chose dans l’écosystème Atmosphere et vous voulez une identité cohérente avec le reste de votre stack.

Installation

pnpm add @emdash-cms/auth-atproto

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { atproto } from "@emdash-cms/auth-atproto";

export default defineConfig({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // obligatoire en dev local — voir « Développement local » ci-dessous
			},
		}),
	],
});

Cela suffit pour afficher Se connecter avec Atmosphere sur la page de connexion et dans l’assistant de configuration. Sans liste d’autorisation, le premier utilisateur devient administrateur et l’inscription libre se ferme pour les autres — voir les listes d’autorisation pour l’ouvrir.

Aucune variable d’environnement, secret client ni enregistrement d’appli OAuth n’est requis. Le fournisseur est un client OAuth public et publie son propre document de métadonnées à /.well-known/atproto-client-metadata.json.

Configuration

atproto({
	allowedDIDs: ["did:plc:abc123..."],
	allowedHandles: ["*.example.com", "alice.bsky.social"],
	defaultRole: 30, // Auteur
});

L’échelle complète des rôles est documentée dans le guide d’authentification principal.

Listes d’autorisation

Si ni allowedDIDs ni allowedHandles ne sont définis, seul le premier utilisateur peut s’inscrire — toute autre tentative de connexion est refusée avec signup_not_allowed. Les utilisateurs existants peuvent toujours se reconnecter quelle que soit la liste (vous ne vous bloquez donc pas en vous retirant de la liste, mais les nouvelles personnes non plus).

Dès qu’au moins une liste est configurée, un utilisateur est admis si l’une des conditions est remplie :

• Correspondance DID. Le DID de l’utilisateur figure dans allowedDIDs. Les DIDs sont des identifiants cryptographiques non déplaçables ni falsifiables — c’est la forme la plus stricte de filtrage.
• Correspondance handle. Le handle correspond à une entrée de allowedHandles, exactement ou via un joker en tête (*.example.com correspond à alice.example.com et bob.team.example.com).

Les listes par handle restent sûres même si les handles changent. Avant d’admettre via le handle, EmDash résout indépendamment l’enregistrement DNS/HTTP du handle et vérifie qu’il pointe vers le même DID que celui revendiqué par le fournisseur. Un fournisseur malveillant ne peut pas simplement prétendre posséder [email protected].

Rôle par défaut

Les utilisateurs autorisés reçoivent le rôle défini dans defaultRole. Seul le premier utilisateur — celui qui termine la configuration — est forcé en Admin. Il n’y a pas de mapping groupe/rôle pour les comptes Atmosphere ; pour des rôles plus fins, modifiez le rôle sous Paramètres → Utilisateurs après une première connexion.

Configuration du premier utilisateur

Lorsque vous démarrez un nouveau site avec le fournisseur Atmosphere, l’assistant de configuration le propose pour créer le compte administrateur initial.

Le même flux s’applique à chaque connexion ultérieure — handle, redirection vers le fournisseur, retour, session ouverte.

Développement local

Le profil OAuth du AT Protocol impose que les URI de redirection loopback utilisent un littéral IP (127.0.0.1 ou [::1]), pas localhost. EmDash réécrit ://localhost en ://127.0.0.1 lors de la génération de l’URI de redirection, ce qui impose aussi de démarrer la session de dev sur 127.0.0.1 — sinon le cookie de session posé sur localhost ne sera pas visible après redirection vers 127.0.0.1.

Le serveur de dev d’Astro est celui de Vite, et Vite écoute sur localhost par défaut. Configurez-le pour écouter aussi sur l’IP de loopback :

export default defineConfig({
	server: {
		host: "127.0.0.1",
	},
	// ...
});

Ouvrez ensuite http://127.0.0.1:4321/_emdash/admin pour tout le parcours.

Production

Rien de plus à configurer en production. Le fournisseur expose ses métadonnées client à :

https://votre-site.example.com/.well-known/atproto-client-metadata.json

Les serveurs d’autorisation récupèrent cette URL pendant la danse OAuth pour vérifier l’URI de redirection du client. Assurez-vous que l’URL publique du déploiement est joignable sur Internet en HTTPS — un déploiement interne derrière un VPN ne pourra pas terminer la connexion car le serveur d’autorisation de l’utilisateur ne pourra pas récupérer le document de métadonnées.

Si EmDash tourne derrière un proxy inverse qui termine le TLS, définissez siteUrl pour que EmDash construise la bonne URI de redirection. Sans cela, les requêtes ressemblent à http://internal-host:4321 et les métadonnées ne correspondront pas à ce que voit le serveur d’auth.

Dépannage

« Account is not in the allowlist »

Le handle ou DID avec lequel vous vous êtes connecté n’est pas dans allowedDIDs / allowedHandles. Vérifiez le motif joker (il doit commencer par *.) et rappelez-vous que la correspondance handle est validée via DNS/HTTP — si l’enregistrement DID du handle ne pointe pas actuellement vers le même DID que celui renvoyé par le fournisseur, la correspondance est rejetée.

« Self-signup is not allowed »

Le callback a réussi mais aucune liste n’est configurée et vous n’êtes pas le premier utilisateur. Ajoutez-vous dans allowedDIDs/allowedHandles, ou faites-vous inviter par un admin existant pour que l’utilisateur existe déjà à la connexion.

La connexion renvoie à la page de login sans erreur

C’est presque toujours le problème de cookie loopback décrit dans Développement local. Ouvrez l’admin sur http://127.0.0.1:4321 (après server.host: "127.0.0.1") et réessayez.

Échec de résolution pour un handle auto-hébergé

Le fournisseur vérifie les handles en faisant une course entre DNS over HTTPS (point de terminaison DoH Cloudflare) et une requête HTTP vers /.well-known/atproto-did. Les handles auto-hébergés nécessitent au moins l’un des éléments suivants :

• Un enregistrement DNS TXT _atproto.<handle> contenant did=<votre-did>, ou
• Un fichier https://<handle>/.well-known/atproto-did contenant le DID.

Si les deux méthodes échouent, la correspondance par handle est rejetée même si le compte sous-jacent est valide. Les DIDs dans allowedDIDs ne sont pas concernés — ils sont comparés directement.