Atmosphere Login

Le package @emdash-cms/auth-atproto ajoute une option de connexion avec compte Atmosphere à EmDash. Un compte Atmosphere est une identité portable appartenant à l’utilisateur, utilisée sur Bluesky et d’autres applications du réseau du protocole AT. 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 une bonne option lorsque :

• Vos contributeurs ont déjà un compte Atmosphere.
• Vous souhaitez contrôler l’accès à un domaine contrôlé par l’organisation (*.votreentreprise.com) sans gérer d’applications OAuth ou d’invitations.
• Vous construisez quelque chose qui fait partie de l’Atmosphere plus large et souhaitez une identité cohérente avec le reste de votre stack.

Installation

Installez le package 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({
	integrations: [
		emdash({
			authProviders: [atproto()],
			server: {
				host: "127.0.0.1", // required for local dev — see "Local development" below
			},
		}),
	],
});

Cela suffit pour afficher Se connecter avec Atmosphere sur la page de connexion et l’assistant de configuration. Sans liste d’autorisation configurée, le premier utilisateur devient Admin et l’auto-inscription est fermée pour tous les autres — consultez 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’application OAuth à configurer.

Configuration

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 — toute autre personne tentant de se connecter sera rejetée avec signup_not_allowed. Les utilisateurs existants peuvent toujours se reconnecter indépendamment de la liste d’autorisation (donc vous retirer de la liste ne vous bloquera pas, mais ne laissera pas entrer de nouvelles personnes non plus).

Lorsqu’au moins une liste d’autorisation est configurée, un utilisateur est admis si l’une ou l’autre liste correspond :

• Correspondance DID. Le DID de l’utilisateur est dans allowedDIDs. Les DIDs sont des identifiants cryptographiques qui ne peuvent pas être déplacés ou usurpés, c’est donc la forme la plus stricte de contrôle d’accès.
• Correspondance de handle. Le handle de l’utilisateur correspond à une entrée dans allowedHandles, exactement ou via un motif de joker initial (*.example.com correspond à alice.example.com et bob.team.example.com).

Les listes d’autorisation de handles 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 le même DID que le fournisseur prétend. Un fournisseur malveillant ne peut pas simplement affirmer qu’il possède vous@votreentreprise.com.

Rôle par défaut

Les utilisateurs autorisés atterrissent sur le rôle que vous définissez dans defaultRole. Seul le premier utilisateur — celui qui termine la configuration — est forcé à Admin. Il n’y a pas de mappage groupe/rôle pour les comptes Atmosphere ; si vous avez besoin de rôles plus précis, modifiez le rôle de l’utilisateur depuis Paramètres → Utilisateurs après qu’ils se soient connectés une fois.

Configuration du premier utilisateur

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

Le même flux s’exécute pour chaque connexion ultérieure : entrez votre handle, authentifiez-vous auprès de votre fournisseur et revenez à EmDash connecté.

Développement local

Le profil OAuth du protocole AT nécessite que les URIs de redirection en boucle locale utilisent un littéral IP (127.0.0.1 ou [::1]), pas 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 également 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 ramène sur 127.0.0.1.

Le serveur de développement d’Astro est le serveur de développement de Vite, et Vite se lie à localhost par défaut. Dites-lui d’écouter également sur l’IP de bouclage :

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

Ensuite, 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://your-site.example.com/.well-known/atproto-client-metadata.json

Les serveurs d’autorisation récupèrent cette URL lors de 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 internet public via HTTPS — les déploiements uniquement internes 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://internal-host:4321 et les métadonnées ne correspondront pas à ce que voit le serveur d’authentification.

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 de joker (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 se résout pas actuellement au même DID que celui renvoyé par le fournisseur, 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. Soit ajoutez-vous à allowedDIDs/allowedHandles, soit faites en sorte qu’un administrateur existant vous invite pour que l’utilisateur existe déjà lorsque vous vous connectez.

La connexion redirige vers la page de connexion sans erreur

C’est presque toujours le problème de cookie de bouclage 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 faisant la course entre DNS-over-HTTPS (point de terminaison DoH de Cloudflare) et une recherche HTTP /.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 de handle est rejetée même lorsque le compte sous-jacent est valide. Les DIDs dans allowedDIDs ne sont pas affectés — ils sont comparés directement.