Configuração

Variáveis de ambiente

Uso

O Logto lida com variáveis de ambiente na seguinte ordem:

• Variáveis de ambiente do sistema
• O arquivo .env na raiz do projeto, que está em conformidade com o formato dotenv

Assim, as variáveis de ambiente do sistema irão sobrescrever os valores em .env.

Variáveis

cuidado:

Se você executar o Logto via npm start na raiz do projeto, NODE_ENV sempre será production.

Nos valores padrão, protocol será http ou https de acordo com sua configuração de HTTPS.

Key	Valor padrão	Tipo	Descrição
NODE_ENV	undefined	'production' | 'test' | undefined	Qual tipo de ambiente em que o Logto está rodando.
PORT	3001	number	A porta local na qual o Logto escuta.
ADMIN_PORT	3002	number	A porta local na qual o Logto Admin Console escuta.
ADMIN_DISABLE_LOCALHOST	N/A	string | boolean | number	Defina como 1 ou true para desabilitar a porta do Admin Console. Com ADMIN_ENDPOINT não definido, irá desabilitar completamente o Admin Console.
DB_URL	N/A	string	O Postgres DSN para o banco de dados do Logto.
DATABASE_STATEMENT_TIMEOUT	N/A	string	(v1.36.0+) statement_timeout do PostgreSQL em milissegundos. Use uma string numérica (ex: 5000) para definir, ou DISABLE_TIMEOUT para omitir o parâmetro de inicialização (recomendado para PgBouncer/RDS Proxy). Se não definido ou inválido, o padrão do cliente é 60000 ms.
HTTPS_CERT_PATH	undefined	string | undefined	Veja Habilitando HTTPS para detalhes.
HTTPS_KEY_PATH	undefined	string | undefined	Idem.
TRUST_PROXY_HEADER	false	boolean	Idem.
ENDPOINT	'protocol://localhost:$PORT'	string	Você pode especificar uma URL com seu domínio personalizado para testes online ou produção. Isso também afetará o valor do identificador do emissor OIDC.
ADMIN_ENDPOINT	'protocol://localhost:$ADMIN_PORT'	string	Você pode especificar uma URL com seu domínio personalizado para produção (Ex: ADMIN_ENDPOINT=https://admin.dominio.com). Isso também afetará o valor dos URIs de redirecionamento do Admin Console.
CASE_SENSITIVE_USERNAME	true	boolean	Especifica se o nome de usuário diferencia maiúsculas de minúsculas. Tenha cautela ao modificar este valor; alterações não ajustarão automaticamente os dados existentes no banco de dados, exigindo gerenciamento manual.
SECRET_VAULT_KEK	undefined	string	A Key Encryption Key (KEK) usada para criptografar as Data Encryption Keys (DEK) no Secret Vault. Necessária para o funcionamento adequado do Secret Vault. Deve ser uma string codificada em base64. Recomenda-se AES-256 (32 bytes). Exemplo: crypto.randomBytes(32).toString('base64')
PRIVATE_KEY_ROTATION_GRACE_PERIOD	0	number	Período de carência em segundos para rotação de chave privada OIDC em estágio. Quando definido como um valor positivo, a nova chave privada é criada como Next primeiro e só se torna efetiva após o período de carência.
OIDC_PROVIDER_SSRF_PROTECTION_DISABLED	false	boolean	Apenas para auto-hospedado. Defina como true apenas quando endpoints confiáveis de relying-party OIDC precisarem resolver para endereços de rede privada. Veja Proteção SSRF do provedor OIDC.

Proteção SSRF do provedor OIDC

O Logto protege as requisições de saída do provedor OIDC contra server-side request forgery (SSRF) por padrão. Requisições para endereços de uso especial, incluindo loopback e endereços de rede privada, são bloqueadas. Essa proteção cobre endpoints de relying-party como URIs de logout back-channel, jwks_uri e sector_identifier_uri, assim como os documentos de metadados de client ID buscados para aplicativo dinâmico.

Se sua implantação auto-hospedada precisar intencionalmente acessar um endpoint confiável de relying-party em uma rede privada, defina OIDC_PROVIDER_SSRF_PROTECTION_DISABLED=true e reinicie cada instância do Logto.

cuidado:

Esta configuração desativa a proteção SSRF para todas as requisições de saída do provedor OIDC, não apenas para um endpoint. Só desative se todos os endpoints de relying-party configurados forem confiáveis e seus controles de rede impedirem o acesso a serviços internos sensíveis.

Aplicativo dinâmico não pode ser habilitado enquanto essa proteção estiver desativada, pois busca documentos de metadados de URLs fornecidos pelos próprios clientes.

Habilitando HTTPS

Usando Node

O Node suporta HTTPS nativamente. Forneça AMBOS HTTPS_CERT_PATH e HTTPS_KEY_PATH para habilitar HTTPS via Node.

HTTPS_CERT_PATH indica o caminho para seu certificado HTTPS, enquanto HTTPS_KEY_PATH indica o caminho para sua chave HTTPS.

Usando um proxy HTTPS

Outra prática comum é ter um proxy HTTPS na frente do Node (Ex: Nginx).

Nesse caso, provavelmente você vai querer definir TRUST_PROXY_HEADER como true, o que indica se os campos de cabeçalho do proxy devem ser confiáveis. O Logto irá passar o valor para as configurações do app Koa.

Veja Confiando em proxies de TLS offloading para saber quando configurar este campo.

Configurações do banco de dados

Gerenciar muitas variáveis de ambiente não é eficiente nem flexível, então a maioria das nossas configurações gerais são armazenadas na tabela do banco de dados logto_configs.

A tabela é um armazenamento simples de chave-valor, e a chave é enumerável conforme abaixo:

Key	Tipo	Descrição
oidc.cookieKeys	string[]	O array de strings das chaves de assinatura de cookie.
oidc.privateKeys	string[]	O array de strings do conteúdo da chave privada para assinatura JWT OIDC.

Tipos de chave privada suportados

• EC (curvas P-256, secp256k1, P-384 e P-521)
• RSA
• OKP (subtipos Ed25519, Ed448, X25519, X448)