Autenticação

Configuração obrigatória

BETTER_AUTH_SECRET=<openssl rand -hex 32>
BETTER_AUTH_URL=https://studio.yourdomain.com
NEXT_PUBLIC_APP_URL=https://studio.yourdomain.com

BETTER_AUTH_URL e NEXT_PUBLIC_APP_URL precisam ser exatamente a sua origem pública — esquema correto, sem barra no final. Deixar qualquer uma delas como localhost em uma instância implantada quebra o login, e a falha se parece com um loop de redirecionamento, não com um erro de configuração.

O BETTER_AUTH_SECRET precisa ser idêntico nos serviços app e realtime. Eles compartilham sessões pelo banco de dados; se houver divergência, o realtime rejeita toda conexão de socket autenticada.

Se as pessoas acessam o Studio por mais de uma origem — um domínio raiz e o www, ou um domínio alternativo — liste as adicionais:

TRUSTED_ORIGINS=https://www.example.com,https://app.example.com

E-mail e senha

Habilitado por padrão. As pessoas se cadastram com um endereço de e-mail e uma senha.

EMAIL_VERIFICATION_ENABLED=true

Exige um provedor de e-mail configurado — veja E-mail. Sem um deles, o serviço de envio não faz nada silenciosamente, então ninguém consegue verificar o e-mail nem entrar. Não habilite isso antes de o e-mail funcionar.

Login social

Três provedores são suportados para entrar no próprio Studio.

ProvedorVariáveisURL de callback
GoogleGOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECREThttps://<host>/api/auth/callback/google
GitHubGITHUB_CLIENT_ID / GITHUB_CLIENT_SECREThttps://<host>/api/auth/callback/github
MicrosoftMICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECREThttps://<host>/api/auth/callback/microsoft

Um provedor aparece na tela de login assim que suas credenciais são definidas. A Microsoft exige, além disso, que as duas variáveis estejam presentes para ser registrada.

Desligue um provedor sem remover as credenciais dele — útil quando o mesmo app do Google ou da Microsoft alimenta as integrações, mas você não quer usá-lo como método de login:

DISABLE_GOOGLE_AUTH=true
DISABLE_GITHUB_AUTH=true
DISABLE_MICROSOFT_AUTH=true

GOOGLE_CLIENT_ID e MICROSOFT_CLIENT_ID são compartilhados com os conectores de integração. Um único registro de app pode servir tanto o login quanto as integrações — basta registrar os dois conjuntos de URIs de redirecionamento. Veja Integrações e OAuth.

SSO (SAML e OIDC)

O single sign-on por SAML e OIDC é um recurso enterprise, disponível em implantações auto-hospedadas por configuração, e não por cobrança:

ENTERPRISE_ENABLED=true
NEXT_PUBLIC_ENTERPRISE_ENABLED=true

Ou habilite apenas o SSO:

SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

Depois disso, os provedores são registrados na aplicação em Settings → Enterprise → Single Sign-On. Um provedor pode ter escopo em uma organização ou ser registrado sem nenhuma. A maioria dos outros recursos enterprise lê suas configurações da organização proprietária de um workspace, então uma implantação que os use ainda precisa de um modelo de organização — defina INSTANCE_ORG_NAME para colocar todos os usuários em uma única organização compartilhada, ou provisione organizações pela Admin API.

Veja o guia de SSO para a configuração do provedor de identidade e o guia enterprise auto-hospedado para os padrões de organização.

Controlando quem pode se cadastrar

VariávelEfeito
DISABLE_REGISTRATION=trueBloqueia todas as novas contas — e-mail/senha, OTP por e-mail e login social. Só contas existentes conseguem entrar, inclusive para aceitar um convite de workspace. O SSO não é afetado
DISABLE_EMAIL_SIGNUP=trueBloqueia novos cadastros por e-mail/senha; o login por e-mail existente continua funcionando
ALLOWED_LOGIN_DOMAINSLista de domínios permitidos, separados por vírgula, por exemplo acme.com,acme.co.uk. Controla tanto a entrada por e-mail quanto o cadastro
ALLOWED_LOGIN_EMAILSLista de endereços permitidos, separados por vírgula, aplicada da mesma forma
BLOCKED_SIGNUP_DOMAINSLista de domínios bloqueados, separados por vírgula
SIGNUP_MX_VALIDATION_ENABLED=trueRejeita domínios sem registro MX ou com um backend de e-mail em lista de bloqueio
BLOCKED_EMAIL_MX_HOSTSTrechos de nomes de host MX a bloquear; usado apenas junto com a variável acima

ALLOWED_LOGIN_DOMAINS, ALLOWED_LOGIN_EMAILS e SIGNUP_MX_VALIDATION_ENABLED controlam apenas o caminho de e-mail/senha. Uma primeira entrada via Google, GitHub ou Microsoft cria a conta pelo provedor social e não passa por esses filtros. Para restringir quem pode entrar por um provedor social, desabilite os que você não validou (DISABLE_GOOGLE_AUTH, DISABLE_GITHUB_AUTH, DISABLE_MICROSOFT_AUTH) ou restrinja a participação no provedor de identidade e use SSO.

DISABLE_REGISTRATION e BLOCKED_SIGNUP_DOMAINS valem para todos os caminhos, inclusive o social.

Para uma implantação corporativa, a combinação usual é cadastro restrito por domínio mais SSO:

ALLOWED_LOGIN_DOMAINS=acme.com
DISABLE_EMAIL_SIGNUP=true
SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

As duas flags de SSO são necessárias: a do lado do servidor concede o acesso, e a NEXT_PUBLIC_ faz a tela de login renderizar o ponto de entrada do SSO.

Atrás de um load balancer

Diga ao Better Auth em quais saltos de encaminhamento confiar ao resolver o IP do cliente:

AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10

O Better Auth percorre o X-Forwarded-For da direita para a esquerda, ignora esses saltos e usa o primeiro endereço não confiável como IP do cliente nos registros de sessão e nas próprias verificações baseadas em IP. Use os endereços reais dos seus proxies — uma faixa privada ampla que também cubra o tráfego dos clientes anula o propósito. Veja Segurança.

Desativando a autenticação por completo

DISABLE_AUTH=true

Ignora a autenticação e cria uma sessão anônima para cada requisição.

Todo mundo que alcança a instância se torna um usuário com privilégios totais — inclusive qualquer coisa que a alcance por uma falha de SSRF em outro ponto da sua rede. Use isso apenas em uma instância de um único usuário em rede privada, nunca atrás de um ingress exposto à internet.

Outros controles

VariávelEfeito
DISABLE_INVITATIONS=true / NEXT_PUBLIC_DISABLE_INVITATIONS=trueDesativa os convites de workspace globalmente
DISABLE_PUBLIC_API=true / NEXT_PUBLIC_DISABLE_PUBLIC_API=trueDesativa a API pública globalmente
ADMIN_API_KEYHabilita a Admin API para operações de GitOps e provisionamento de organizações

A variável gêmea NEXT_PUBLIC_ controla o que a interface mostra; a do lado do servidor é quem aplica a regra. Defina as duas.

Common Questions

BETTER_AUTH_URL ou NEXT_PUBLIC_APP_URL não corresponde à origem que as pessoas estão acessando. As duas precisam ser exatamente a URL pública, incluindo o esquema e sem barra no final. Essa é de longe a configuração incorreta de autenticação mais comum.
O BETTER_AUTH_SECRET é diferente entre os serviços app e realtime. Eles compartilham sessões pelo banco de dados, então o secret precisa ser idêntico byte a byte nos dois.
Sim. GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET servem para os dois. Registre o callback de login (/api/auth/callback/google) junto com os callbacks dos conectores (/api/auth/oauth2/callback/google-email e afins) no mesmo cliente OAuth.
A variável do lado do servidor aplica o comportamento; a NEXT_PUBLIC_ diz ao navegador o que renderizar. Definir só uma produz uma interface que discorda do servidor, então defina as duas.
Integrações & OAuthJobs em segundo plano