Autenticação

O EmDash usa autenticação com passkeys como método principal de login. Passkeys são resistentes a phishing, não exigem senhas e funcionam em todos os dispositivos pelo navegador ou gerenciador de senhas.

Além das passkeys, você pode adicionar provedores de login plugáveis. GitHub, Google e Microsoft vêm com o EmDash. O provedor Atmosphere instalado separadamente adiciona contas AT Protocol, e a mesma interface de provedor está aberta a outros pacotes. Os provedores documentados GitHub, Google, Microsoft e Atmosphere podem criar a primeira conta de administrador ou fazer login de um usuário EmDash vinculado.

Em implantações Cloudflare, o Cloudflare Access é um modo de autenticação separado e exclusivo em produção. Ele valida credenciais Access nas rotas EmDash protegidas em vez de mostrar os métodos de login do EmDash.

Escolher um modo de autenticação

Passkeys usam WebAuthn, um padrão web que cria credenciais de chave pública armazenadas no dispositivo ou sincronizadas pelo gerenciador de senhas. Ao fazer login, o dispositivo prova a posse da credencial sem nunca enviar uma senha pela rede.

Passkeys são o padrão. Os provedores GitHub, Google, Microsoft e Atmosphere são métodos de login adicionais: cada um autentica o usuário, vincula ou cria uma conta EmDash e estabelece a mesma sessão EmDash usada por um login com passkey.

A autenticação com passkeys oferece:

• Sem senhas para lembrar ou vazar
• Resistente a phishing — as credenciais estão vinculadas ao domínio do site
• Sincronização entre dispositivos — funciona com iCloud Keychain, Google Password Manager, 1Password etc.
• Login rápido — um toque com biometria ou PIN

O Cloudflare Access usa a opção auth em vez de authProviders. Em produção, torna-se a autoridade das rotas /_emdash protegidas. O EmDash ainda armazena um usuário local para que papéis, propriedade e verificações de usuários desabilitados continuem funcionando.

Configurar o primeiro usuário

Na primeira vez que você acessa o painel de administração, o assistente de configuração orienta a criação da conta de administrador.

Entrar com uma passkey

Após a configuração, voltar ao painel de administração aciona a autenticação com passkey:

Entrar com um magic link

Se não puder usar a passkey, um magic link oferece uma alternativa. O site precisa ter um provedor de e-mail configurado antes que o EmDash possa enviar o link — veja Configuração de e-mail.

Configurar provedores de login

Além das passkeys, o EmDash oferece suporte a provedores de login plugáveis que aparecem na página de login e no assistente de configuração. GitHub, Google e Microsoft vêm com o EmDash. Atmosphere e provedores de terceiros são pacotes separados que se registram pela mesma interface.

Os provedores são aditivos — as passkeys continuam funcionando quando os provedores estão habilitados. GitHub, Google e Microsoft vinculam automaticamente um usuário EmDash existente apenas quando o provedor fornece o mesmo endereço de e-mail verificado. Contas Atmosphere são vinculadas pelo identificador descentralizado (DID), porque o fluxo Atmosphere do EmDash não recebe um endereço de e-mail. Cada provedor incluído pode criar o primeiro usuário, então uma instalação nova pode pular as passkeys por completo.

Adicionar provedores ao Astro

Passe os provedores ao array authProviders da integração EmDash. O exemplo a seguir habilita GitHub, Google e Atmosphere:

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

export default defineConfig({
	integrations: [
		emdash({
			authProviders: [github(), google(), atproto()],
		}),
	],
});

A ordem importa na página de login: os provedores são renderizados na ordem em que você os lista, com provedores compactos só de botão primeiro e provedores que precisam de um formulário personalizado (como Atmosphere, que pede um handle) depois.

GitHub

O exemplo a seguir habilita o provedor GitHub:

import { github } from "emdash/auth/providers/github";

emdash({ authProviders: [github()] });

Defina as credenciais via variáveis de ambiente. O EmDash verifica primeiro os nomes com prefixo e recorre aos sem prefixo:

Configure a URL de callback do seu app OAuth do GitHub como https://your-site.example.com/_emdash/api/auth/oauth/github/callback.

Google

O exemplo a seguir habilita o provedor Google:

import { google } from "emdash/auth/providers/google";

emdash({ authProviders: [google()] });

Defina as credenciais via variáveis de ambiente. O EmDash verifica primeiro os nomes com prefixo e recorre aos sem prefixo:

Configure o URI de redirecionamento do cliente OAuth do Google como https://your-site.example.com/_emdash/api/auth/oauth/google/callback.

Microsoft

O exemplo a seguir habilita o provedor Microsoft:

import { microsoft } from "emdash/auth/providers/microsoft";

emdash({ authProviders: [microsoft()] });

Registre um aplicativo no centro de administração do Microsoft Entra, adicione um URI de redirecionamento Web https://your-site.example.com/_emdash/api/auth/oauth/microsoft/callback e crie um segredo do cliente. Em seguida, defina as três variáveis de ambiente. O EmDash verifica primeiro os nomes com prefixo e recorre aos sem prefixo:

Os segredos do cliente criados no centro de administração do Microsoft Entra expiram após no máximo 24 meses, e o login com a Microsoft deixa de funcionar quando o segredo expira. Crie um novo segredo e atualize EMDASH_OAUTH_MICROSOFT_CLIENT_SECRET antes disso.

Use o ID do diretório da página de visão geral do aplicativo. Um nome de domínio como contoso.onmicrosoft.com não é aceito como locatário. Para usar common, organizations ou consumers, registre o aplicativo para os tipos de conta compatíveis correspondentes, porque a Microsoft recusa um login que o registro não permite.

O EmDash obtém o endereço do e-mail da conta ou, quando a conta não tem endereço de e-mail, do nome de entrada dela. Ele vincula um usuário existente, aceita um convite e permite o auto-cadastro, incluindo a primeira conta de administrador, apenas para um endereço que trata como verificado.

Com um ID de diretório, o endereço de uma conta que entra por esse diretório conta como verificado quando está no mesmo domínio do nome de entrada da conta (nome principal do usuário, UPN), porque a Microsoft só permite um nome de entrada em um domínio que o diretório verificou. Endereços de contas que entram por outro diretório ou provedor de identidade, como convidados ou a conta pessoal da Microsoft que criou o diretório, não contam como verificados, e nenhum endereço conta como verificado quando o locatário é common, organizations ou consumers.

Se os endereços de e-mail dos seus usuários estiverem em um domínio diferente do de seus nomes de entrada, adicione xms_edov como declaração opcional do token de ID no registro do aplicativo. O EmDash passa então a tratar esse endereço como verificado quando a declaração confirma que o diretório verificou o domínio dele.

O exemplo a seguir trata todo endereço da Microsoft como verificado:

emdash({ authProviders: [microsoft({ emailVerified: true })] });

Defina emailVerified: true somente quando confiar em todos os diretórios cujas contas podem entrar. A Microsoft não verifica o endereço de e-mail que informa, e um administrador do diretório de uma conta pode alterá-lo. Defina emailVerified: false para tratar todo endereço como não verificado, de modo que só contas já vinculadas a um usuário EmDash possam entrar.

Gerenciar o acesso da Microsoft

Para permitir que apenas algumas contas do diretório entrem, defina Assignment required como Yes nas propriedades do aplicativo empresarial do app no Microsoft Entra e depois atribua os usuários ou grupos que precisam de acesso. A Microsoft recusa todos os outros antes que cheguem ao EmDash. A atribuição de grupos exige o Microsoft Entra ID P1 ou P2 e abrange apenas membros diretos.

O Microsoft Entra decide quem pode entrar com a Microsoft. O EmDash mantém seus próprios usuários, papéis e indicador de usuário desabilitado, e as alterações no diretório não chegam a ele:

• Se um usuário EmDash já tiver o endereço, o primeiro login com a Microsoft com um endereço verificado vincula-se a esse usuário e mantém o papel dele. Um login com um endereço não verificado é recusado.
• Se o usuário foi convidado, entrar com a Microsoft pelo link de convite dá a ele o papel convidado. Um login sem o link fica sujeito aos domínios permitidos.
• Quando alguém sai, desabilite o usuário EmDash dessa pessoa além da conta da Microsoft. Uma conta da Microsoft desabilitada ou excluída interrompe novos logins com a Microsoft, mas não uma sessão EmDash aberta nem as passkeys registradas no EmDash.
• Se uma nova conta da Microsoft receber mais tarde o mesmo endereço, ela se vincula ao usuário EmDash existente e recebe o papel desse usuário. Um usuário EmDash desabilitado continua desabilitado até que um administrador o habilite.
• Se uma conta da Microsoft excluída for restaurada no Microsoft Entra, ela entra no mesmo usuário EmDash de antes.

Atmosphere (AT Protocol)

Para sites cujos colaboradores já têm uma conta Atmosphere — a identidade de propriedade do usuário por trás do Bluesky e da rede AT Protocol mais ampla — instale o provedor Atmosphere:

pnpm add @emdash-cms/auth-atproto

O exemplo a seguir habilita o provedor Atmosphere com uma lista de handles permitidos:

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

emdash({
	authProviders: [
		atproto({
			allowedHandles: ["*.example.com"],
		}),
	],
});

Não é necessário segredo de cliente nem variável de ambiente. Consulte o guia de login Atmosphere para listas de permissão de handle/DID, mapeamento de papéis e a configuração de desenvolvimento local exigida pelo perfil OAuth do AT Protocol.

Criar um provedor

Um provedor é um AuthProviderDescriptor: um id, um rótulo legível e os componentes de administração, manipuladores de rotas, prefixos de rotas públicas e coleções de armazenamento de que seu fluxo de login precisa. Exporte um SetupStep de adminEntry se o provedor deve aparecer durante a configuração do primeiro usuário. A forma é exportada de emdash:

import type { AuthProviderDescriptor } from "emdash";

export function myProvider(): AuthProviderDescriptor {
	return {
		id: "my-provider",
		label: "My Provider",
		adminEntry: "my-provider/admin", // exports LoginButton / LoginForm / SetupStep
		routes: [
			{ pattern: "/_emdash/api/auth/my-provider/login", entrypoint: "my-provider/routes/login.ts" },
			{ pattern: "/_emdash/api/auth/my-provider/callback", entrypoint: "my-provider/routes/callback.ts" },
		],
		publicRoutes: ["/_emdash/api/auth/my-provider/"],
		storage: {
			sessions: {},
		},
	};
}

O pacote Atmosphere (@emdash-cms/auth-atproto) é a referência real mais completa de um provedor que precisa de um formulário de login personalizado, manipuladores de rotas OAuth e armazenamento persistente.

Papéis de usuário

O EmDash usa controle de acesso baseado em papéis com cinco níveis:

Cada papel herda permissões de todos os níveis inferiores. O primeiro usuário é sempre criado como Admin.

Assinantes e conteúdo em rascunho

Assinantes têm a permissão content:read para que conteúdo publicado só para membros possa ser servido a leitores autenticados. Eles não podem ver rascunhos, itens agendados, itens na lixeira, revisões nem URLs de pré-visualização — esses são controlados por content:read_drafts, concedido a Contributor e acima. Os endpoints list e get filtram de forma transparente para status=published para Subscribers; as visualizações só de editor (/compare, /revisions, /trash, /preview-url) rejeitam de imediato as solicitações de Subscribers.

Convidar usuários

Administradores podem convidar novos usuários pelo painel de administração:

Links de convite são de uso único e expiram após 7 dias.

Gerenciar passkeys

Os usuários podem gerenciar suas passkeys nas configurações da conta:

• Add passkey — Registrar passkeys adicionais como backup ou em outros dispositivos
• Remove passkey — Excluir passkeys que você não usa mais
• Rename passkey — Dar nomes descritivos às passkeys

Cada usuário pode ter até 10 passkeys registradas.

O EmDash não permite que um usuário remova sua última passkey. Adicione uma substituta antes de excluir a antiga.

Uma passkey só funciona no endereço em que foi criada. Depois de mover o site para um novo domínio, consulte Entrar depois da mudança.

Permitir que um grupo entre sem convites

Para permitir que um grupo entre sem convidar cada usuário, configure um provedor de login com uma lista de permissão. O provedor Atmosphere aceita allowedHandles e allowedDIDs (veja Login Atmosphere); o adaptador Cloudflare Access provisiona usuários do seu provedor de identidade via autoProvision e roleMapping. Os provedores documentados GitHub, Google, Microsoft e Atmosphere também podem criar a conta de administrador inicial.

Sessões

Os callbacks de passkey, magic link, convite e provedor de login armazenam o ID do usuário EmDash no armazenamento de sessões do Astro. O navegador recebe o identificador opaco astro-session do Astro; os registros de usuário e credenciais permanecem no banco de dados do EmDash.

O Cloudflare Access também grava o usuário EmDash resolvido na sessão do Astro. Isso permite que páginas públicas identifiquem um usuário logado ao ler Astro.locals.user. A sessão não substitui a autenticação Access nas rotas /_emdash protegidas: o EmDash valida novamente o JSON Web Token (JWT) Access nessas solicitações.

Limites de taxa de autenticação

O EmDash limita os endpoints não autenticados que iniciam login, cadastro ou registro de clientes OAuth. Os limites são separados para cada endpoint e IP de cliente confiável:

No Cloudflare, o EmDash lê o IP do cliente dos metadados de solicitação do Cloudflare. Um site auto-hospedado atrás de um proxy reverso deve configurar trustedProxyHeaders antes que o EmDash possa usar o cabeçalho de IP do cliente do proxy. Quando nenhum IP confiável está disponível, essas verificações por IP são ignoradas porque não há uma chave segura para contar.

Passkeys armazenam credenciais de chave pública; a chave privada permanece com o autenticador do usuário. Tokens de magic link são armazenados como hashes SHA-256 e excluídos após o uso.

Solução de problemas

”No passkeys registered”

Se você vir este erro ao entrar, sua passkey pode ter sido excluída do gerenciador de senhas. Peça a um administrador que envie um magic link de recuperação; o site precisa ter o e-mail configurado.

”Passkey authentication failed”

Isso geralmente significa que a passkey foi criada para um domínio diferente. Passkeys estão vinculadas ao domínio — uma passkey para localhost:4321 não funcionará em example.com. Registre uma nova passkey para cada domínio.

Todas as passkeys perdidas

Se você perdeu o acesso a todas as passkeys registradas:

1. Peça a outro administrador que envie um magic link de recuperação. O site precisa ter o e-mail configurado.
2. Abra o link em até 15 minutos e selecione Continue para entrar.
3. Registre uma nova passkey nas configurações da conta.

Se você for o único administrador e o e-mail não estiver configurado, precisará redefinir a autenticação do site pelo banco de dados.

Cloudflare Access

Ao implantar no Cloudflare, você pode usar o Cloudflare Access no lugar dos métodos de login integrados. O Access autentica o usuário na borda com seu provedor de identidade. O EmDash valida o JWT Access assinado, carrega a identidade e os grupos da pessoa e mapeia essa identidade para um usuário EmDash local.

Quando usar o Cloudflare Access

• Single Sign-On — Os usuários autenticam com o IdP da empresa
• Controle de acesso centralizado — Gerencie quem pode acessar o admin no painel Cloudflare
• Sem gerenciamento de passkeys — Não é necessário registrar ou gerenciar passkeys
• Papéis baseados em grupos — Mapeie grupos do IdP para papéis EmDash automaticamente

Configurar o Access

1. Crie um aplicativo e uma política Cloudflare Access para o caminho /_emdash/* do site. Proteger apenas /_emdash/admin/* deixa a API REST sem o JWT que o EmDash espera.
2. Copie a Application Audience (AUD) Tag do aplicativo.
3. Armazene a tag na variável de ambiente de runtime CF_ACCESS_AUDIENCE. Siga o guia de segredos do EmDash para valores locais e implantados.
4. Configure o EmDash para ler esse valor em runtime:

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, access } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			auth: access({
				teamDomain: "myteam.cloudflareaccess.com",
				audienceEnvVar: "CF_ACCESS_AUDIENCE",
			}),
		}),
	],
});

A audience do aplicativo identifica qual aplicativo Access emitiu o JWT. O EmDash a verifica junto com o emissor e a assinatura; um token de outro aplicativo Access é rejeitado.

Opções de configuração

Forneça audience ou um valor de ambiente sob audienceEnvVar.

Mapeamento de papéis

Mapeie seus grupos do IdP para papéis EmDash:

emdash({
	auth: access({
		teamDomain: "myteam.cloudflareaccess.com",
		audienceEnvVar: "CF_ACCESS_AUDIENCE",
		roleMapping: {
			Admins: 50, // Admin
			"Content Editors": 40, // Editor
			Writers: 30, // Author
		},
		defaultRole: 20, // Contributor for users not in any group
	}),
});

O primeiro grupo correspondente vence se um usuário pertencer a vários grupos. O primeiro usuário a acessar o site sempre se torna Admin, independentemente dos grupos.

Comportamento de sincronização de papéis

Por padrão (syncRoles: false), o papel de um usuário é definido no primeiro login e não muda depois. Isso permite que administradores ajustem papéis manualmente no EmDash.

Defina syncRoles: true se quiser que os grupos do IdP sejam autoritativos — o papel do usuário será atualizado a cada login com base nos grupos atuais.

Comportamento da sincronização de nomes

Por padrão (syncName: true), o EmDash substitui o nome de um usuário pelo nome vindo do Access a cada requisição autenticada. Quando a identidade do Access não tem nome, o EmDash usa a parte do endereço de e-mail antes do @. O editor de usuários do administrador mostra o nome como somente leitura, com uma dica para alterá-lo no Access.

Defina syncName: false para manter os nomes editáveis no EmDash. O nome vindo do Access passa então a ser usado apenas quando o usuário é provisionado pela primeira vez.

Fluxo de solicitação e sessão

1. O usuário visita um caminho protegido pelo aplicativo Access.
2. O Cloudflare Access redireciona o usuário ao provedor de identidade quando não existe uma sessão Access.
3. Após a autenticação, o Access envia um JWT assinado à origem em Cf-Access-Jwt-Assertion.
4. O EmDash valida a assinatura, o emissor e a audience do token e depois lê a identidade e os grupos Access.
5. O EmDash encontra ou provisiona o usuário local, aplica o comportamento de papel configurado e registra o usuário na sessão do Astro.
6. Solicitações posteriores a rotas EmDash protegidas repetem a validação Access. Páginas públicas podem usar a sessão EmDash para identificar o usuário sem tratá-la como prova de uma nova solicitação Access.

Recursos substituídos pelo Access

Quando o Access está habilitado, estes recursos ficam indisponíveis:

• Página de login (/_emdash/admin/login)
• Registro e gerenciamento de passkeys
• Login GitHub, Google, Microsoft e Atmosphere
• Login com magic link
• Auto-cadastro
• Convites de usuário

As políticas Access decidem quem chega ao EmDash. O EmDash continua dono dos papéis locais, da propriedade do conteúdo e do indicador de usuário desabilitado. Com syncRoles: false, administradores podem alterar o papel de um usuário provisionado no EmDash. Com syncRoles: true, os grupos Access mapeados substituem esse papel a cada login. Os nomes de usuário seguem o mesmo padrão com syncName, exceto que o valor padrão dele é true.

Solução de problemas

”No Access JWT present”

A solicitação chegou ao EmDash sem um JWT Access. Isso significa:

• O Access não está configurado para proteger seu aplicativo
• A política Access não corresponde às rotas de administração

Verifique se o aplicativo Access cobre o caminho completo /_emdash/* e se a política inclui o usuário.

”JWT audience mismatch”

O audience na configuração não corresponde ao JWT. Verifique novamente a Application Audience Tag nas configurações do aplicativo Access.

”User not authorized”

O usuário autenticou via Access, mas autoProvision é false e ele não existe no EmDash. Ou:

• Defina autoProvision: true, ou
• Crie o usuário manualmente antes que ele faça login