Connexion Atmosphere

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

C’est un bon choix lorsque :

• Vos contributeurs ont déjà un compte Atmosphere.
• Vous voulez restreindre l’accès à un domaine contrôlé par une organisation (*.yourcompany.com) sans gérer d’applications OAuth ni d’invitations.
• Vous développez quelque chose qui fait partie de l’écosystème Atmosphere au sens large et vous voulez une identité cohérente avec le reste de votre stack.

Installer

Installez le paquet du fournisseur :

pnpm add @emdash-cms/auth-atproto

Ajoutez le fournisseur à l’intégration EmDash :

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

export default defineConfig({
	server: {
		host: "127.0.0.1", // required for local development; see below
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

Cela suffit pour afficher Sign in with Atmosphere sur la page de connexion et dans l’assistant de configuration. Sans liste d’autorisation configurée, le premier utilisateur devient Admin et l’inscription libre est ensuite fermée pour tous — voir les listes d’autorisation pour l’ouvrir.

Le fournisseur est un client OAuth public et sert son propre document de métadonnées à /.well-known/atproto-client-metadata.json. Il fonctionne donc avec la seule configuration ci-dessus — aucune variable d’environnement, aucun secret client ni aucune inscription d’application OAuth à mettre en place.

Configurer l’accès

Le fournisseur atproto() accepte une liste d’autorisation et un rôle par défaut :

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

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. Les comptes déjà liés à un utilisateur EmDash peuvent continuer à se connecter, tandis qu’un nouveau compte est rejeté avec signup_not_allowed.

Lorsqu’au moins une liste d’autorisation est configurée, chaque connexion doit y correspondre, y compris celles des utilisateurs existants. Retirer le DID et le handle d’un utilisateur existant des listes configurées l’empêche de se connecter. Un utilisateur est admis si l’une ou l’autre des listes correspond :

• Correspondance de DID. L’identifiant de compte stable de l’utilisateur correspond exactement à une valeur de allowedDIDs.
• Correspondance de handle. Le handle de l’utilisateur correspond à une entrée de allowedHandles, exactement ou via un motif à joker en début de valeur (*.example.com correspond à alice.example.com et à bob.team.example.com).

Les listes d’autorisation de handles sont sûres bien que les handles soient modifiables. Avant d’admettre un utilisateur via une correspondance de 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 défaillant ne peut pas simplement affirmer qu’il possède you.yourcompany.com.

Rôle par défaut

Les utilisateurs autorisés reçoivent le rôle que vous définissez dans defaultRole. Seul le premier utilisateur — celui qui termine la configuration — est forcé en Admin. Il n’existe pas de correspondance groupe/rôle pour les comptes Atmosphere ; si vous avez besoin de rôles plus fins, modifiez le rôle de l’utilisateur sur la page Users de la barre latérale de l’administration une fois qu’il s’est connecté une première fois.

Configurer le premier utilisateur

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

Les connexions suivantes commencent par le handle, se poursuivent chez le fournisseur du compte et reviennent avec une session EmDash. L’état OAuth et les jetons du fournisseur sont stockés séparément de cette session EmDash, afin que le callback OAuth puisse aboutir et que le fournisseur puisse renouveler sa propre session.

Développement local

Le profil OAuth d’AT Protocol exige que les URI de redirection loopback utilisent un littéral IP (127.0.0.1 ou [::1]), et non localhost. EmDash réécrit de manière transparente ://localhost en ://127.0.0.1 lors de la génération de l’URI de redirection, mais cela signifie que votre session de développement doit elle aussi démarrer sur 127.0.0.1 — sinon le cookie de session défini sur localhost ne sera pas visible une fois la redirection arrivée sur 127.0.0.1.

Le serveur de développement d’Astro utilise Vite, qui se lie par défaut à localhost. Définissez l’option server.host de niveau supérieur d’Astro 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

La même configuration fonctionne en production. Le fournisseur sert ses propres métadonnées client à l’adresse :

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

Les serveurs d’autorisation récupèrent cette URL pendant la connexion pour vérifier l’URI de redirection du client. Assurez-vous que l’URL du site de votre déploiement est accessible sur l’internet public en HTTPS — les déploiements uniquement internes, derrière un VPN, ne pourront pas mener une connexion à terme, car le serveur d’autorisation de l’utilisateur ne peut pas récupérer le document de métadonnées.

Si vous exécutez EmDash derrière un proxy inverse qui termine TLS, définissez siteUrl pour qu’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’autorisation.

Dépannage

”Account is not in the allowlist”

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

”Self-signup is not allowed”

Vous avez bien atteint le callback, mais aucune liste d’autorisation n’est configurée et vous n’êtes pas le premier utilisateur. Ajoutez le DID du compte à allowedDIDs ou son handle vérifié à allowedHandles. Une invitation par e-mail ne lie pas un DID Atmosphere à un utilisateur EmDash.

La connexion redirige vers la page de connexion sans erreur

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

La résolution de handle échoue pour un handle auto-hébergé

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

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

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