Connexion Atmosphere

Le paquet @emdash-cms/auth-atproto ajoute une option de connexion avec un compte Atmosphere à EmDash. 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 (ex. alice.bsky.social) et s’authentifient auprès de leur propre fournisseur — EmDash ne voit jamais de mot de passe.

C’est adapté quand :

• Vos contributeurs ont déjà un compte Atmosphere.
• Vous voulez contrôler l’accès d’un domaine contrôlé par l’organisation (*.votreentreprise.com) sans gérer des apps OAuth ou des invitations.
• Vous construisez quelque chose qui fait partie de l’Atmosphere au sens large et 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", // requis pour le développement local ; voir ci-dessous
	},
	integrations: [
		emdash({
			authProviders: [atproto()],
		}),
	],
});

Cela suffit pour placer Sign in with Atmosphere sur la page de connexion et l’assistant de configuration. Sans liste d’autorisation configurée, le premier utilisateur devient Admin et l’inscription automatique est fermée pour tous ensuite — voir 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 configuration ci-dessus seule — pas de variables d’environnement, de secret client ou d’enregistrement d’app OAuth à configurer.

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, // 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 n’est défini, 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.

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

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

Les listes de handles autorisés sont sûres même si les handles sont mutables. 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 la même DID que le fournisseur prétend. Un fournisseur mal intentionné ne peut pas simplement affirmer qu’il possède vous.votreentreprise.com.

Rôle par défaut

Les utilisateurs autorisés arrivent avec le rôle défini dans defaultRole. Seul le premier utilisateur — celui qui complète la configuration — est forcé en Admin. Il n’y a pas de correspondance groupe/rôle pour les comptes Atmosphere ; si vous avez besoin de rôles plus fins, changez le rôle de l’utilisateur depuis Paramètres → Utilisateurs après sa première connexion.

Configurer le premier utilisateur

Quand vous démarrez un site neuf avec le fournisseur Atmosphere configuré, l’assistant de configuration l’offre comme option pour créer le compte admin initial.

Les connexions suivantes commencent par le handle, continuent chez le fournisseur de compte et reviennent avec une session EmDash. L’état OAuth et les tokens du fournisseur sont stockés séparément de cette session EmDash pour que le callback OAuth puisse se terminer et que le fournisseur puisse rafraîchir sa propre session.

Développement local

Le profil OAuth du AT Protocol exige que les URIs de redirection loopback utilisent un littéral IP (127.0.0.1 ou [::1]), pas localhost. EmDash réécrit transparemment ://localhost en ://127.0.0.1 lors de la génération de l’URI de redirection, mais cela signifie que votre session de dev doit aussi démarrer sur 127.0.0.1 — sinon le cookie de session défini sur localhost ne sera pas visible après que la redirection vous amène sur 127.0.0.1.

Le serveur de dev d’Astro utilise Vite, qui se lie à localhost par défaut. Définissez l’option server.host d’Astro sur l’IP loopback :

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

Puis ouvrez http://127.0.0.1:4321/_emdash/admin pour tout le flux.

Production

La même configuration fonctionne en production. Le fournisseur sert ses propres 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 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 via HTTPS — les déploiements internes uniquement derrière un VPN ne pourront pas terminer une connexion 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 terminant TLS, définissez siteUrl pour qu’EmDash construise la bonne URI de redirection. Sans cela, les requêtes ressemblent à http://hôte-interne:4321 et les métadonnées ne correspondront pas à ce que le serveur d’auth voit.

Dépannage

”Account is not in the allowlist”

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

”Self-signup is not allowed”

Vous avez atteint le callback avec succès, mais aucune liste d’autorisation n’est configurée et vous n’êtes pas le premier utilisateur. Ajoutez la DID du compte à allowedDIDs ou son handle vérifié à allowedHandles. Une invitation par email ne lie pas une 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 testant en parallèle DNS-sur-HTTPS (endpoint DoH de Cloudflare) et une recherche HTTP /.well-known/atproto-did. Les handles auto-hébergés ont besoin d’au moins un des deux :

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

Si les deux méthodes échouent, la correspondance de handle est rejetée même quand le compte sous-jacent est valide. Les DIDs dans allowedDIDs ne sont pas affectées — elles sont comparées directement.