Domínios Personalizados no seu SaaS: Como Configurar o Cloudflare for SaaS

Se você está desenvolvendo uma plataforma SaaS multitenant (como um construtor de sites, plataforma e-commerce, portal de membros ou aplicativo de gestão), uma das funcionalidades mais solicitadas pelos clientes empresariais é poder utilizar o seu próprio domínio personalizado (ex: portal.empresa.com.br ou painel.cliente.com) ao invés do subdomínio padrão do seu SaaS (cliente.meusaas.com.br).

No passado, oferecer esse recurso exigia gerenciar servidores Nginx complexos, scripts de renovação do Let's Encrypt (Certbot), proxies reversos manuais e lidar constante com falhas de validação de SSL. Hoje, a solução padrão da indústria para este desafio é o Cloudflare for SaaS (SSL/TLS Custom Hostnames).

Painel do Cloudflare Worker em Build → Workers & Pages (ex: mailfy-domain-router) configurado para roteamento inteligente de domínios.

Passo 1: Transferir ou Adicionar o Domínio Principal do SaaS na Cloudflare

Para que a Cloudflare consiga gerenciar o roteamento e a emissão dos certificados SSL para os clientes do seu SaaS, o domínio principal do seu produto (ex: seudominio.com.br) precisa estar adicionado à sua conta na Cloudflare.

No painel da Cloudflare, acesse a opção Add a site ("Adicionar um site"). Você terá a opção de transferir/conectar um domínio já existente escolhendo Connect a domain ou comprar um novo domínio diretamente pela plataforma.

1. No painel da Cloudflare, clique em Add a site → Connect a domain e digite o seu domínio principal (ex: seudominio.com.br).
2. No seu provedor atual onde o domínio foi comprado (como Registro.br, GoDaddy ou Namecheap), altere os servidores de nome (Nameservers) para os servidores fornecidos pela Cloudflare (ex: clint.ns.cloudflare.com e iris.ns.cloudflare.com).
3. Aguarde a propagação do DNS até que, ao acessar a página Overview do seu domínio na Cloudflare, seja exibida a mensagem de sucesso: "Your domain is now protected by Cloudflare" com o status de zona DNS Setup: Full.

Tela 'Add a site' → 'Connect a domain' para conectar ou comprar o domínio no Cloudflare.

Passo 2: Criar o Registro DNS do Fallback Origin (Nuvem Laranja / Proxied)

Atenção: Antes de definir o subdomínio reservado do seu SaaS (ex: cname.seudominio.com.br) como seu Fallback Origin no painel da Cloudflare, você precisa primeiro criar o registro DNS desse subdomínio na sua tabela de DNS. A Cloudflare valida se o nome já resolve antes de aceitar a configuração.

1. Acesse a aba DNS → Records no painel do seu domínio na Cloudflare.
2. Adicione um novo registro:
   • Tipo: A (ou CNAME)
   • Nome: cname (ou fallback)
   • Conteúdo/IPv4: O IP público do seu servidor (ex: 192.0.2.1) ou o endereço CNAME da sua hospedagem.
   • Proxy Status: Proxied (Nuvem Laranja ativada 🧡).

Tabela DNS → Records exibindo o registro DNS criado para o Fallback Origin com Proxy Status: Proxied (Nuvem Laranja 🧡).

Passo 3: Ativar o Cloudflare for SaaS e Configurar o Fallback Origin

Com o registro DNS do Fallback Origin ativo na sua zona, você agora pode vinculá-lo como o destino padrão dos domínios dos seus clientes no módulo de Custom Hostnames.

1. No painel do seu domínio na Cloudflare, acesse o menu lateral SSL/TLS → Custom Hostnames (Domínios Personalizados).
2. Se for seu primeiro acesso, clique em Enable Cloudflare for SaaS (até 100 domínios o custo é $0/mês).
3. No campo Fallback Origin, digite o subdomínio criado no passo anterior: cname.seudominio.com.br (ou fallback.seudominio.com.br).
4. Clique em Add Fallback Origin para salvar até que o status confirme como Active.

Visualização e Gestão dos Domínios dos Clientes:
Nesta mesma página (SSL/TLS → Custom Hostnames), você — como administrador do SaaS — conseguirá visualizar a lista completa de todos os domínios personalizados dos seus clientes criados automaticamente pelo seu sistema (via API) ou adicioná-los manualmente através do botão Add Custom Hostname, permitindo acompanhar em tempo real o status de validação e a emissão do certificado SSL de cada um.

Tela SSL/TLS → Overview exibindo o estado da criptografia e o botão Configure.

Painel Configure com a opção Full selecionada para garantir criptografia ponta a ponta e funcionamento perfeito do SaaS.

Tela SSL/TLS → Custom Hostnames exibindo o Fallback Origin (ex: cname.zapy.pro com status Active) e o botão Add Custom Hostname.

Tabela de Custom Hostnames exibindo os domínios do cliente cadastrados com e sem www (ex: lojadasbonecas.com.br e www.lojadasbonecas.com.br) com status Certificate status: Active e Hostname status: Active.

Passo 4: Como o Cliente Configura o Domínio Dele (Instruções para o Usuário)

Para que o seu cliente (ex: Empresa ABC) consiga usar app.empresaabc.com.br no seu SaaS, ele precisará fazer um apontamento no painel de DNS onde ele comprou o domínio dele (Registro.br, GoDaddy, Cloudflare, etc.).

No painel do seu SaaS, exiba as seguintes instruções para o usuário:

Passo 5: Automatizando a Criação de Hostnames via API da Cloudflare

Você não quer ter que entrar manualmente no painel da Cloudflare toda vez que um novo assinante do seu SaaS quiser conectar um domínio. Para resolver isso, utilize a API REST da Cloudflare para cadastrar o Custom Hostname de forma 100% automatizada direto pelo backend do seu aplicativo!

Para conectar o backend do seu SaaS à API da Cloudflare, você precisará de duas credenciais essenciais:

1. Zone ID (ID da Zona): Encontrado na página Overview do seu domínio principal (seudominio.com.br) no Cloudflare. Role a página até o final da barra lateral direita para localizar e copiar o seu Zone ID.
2. API Token (Token da API): Acesse o perfil da sua conta em My Profile → API Tokens (ou acesse diretamente em dash.cloudflare.com/profile/api-tokens). Clique em Create Token, selecione a opção Create Custom Token e defina as permissões necessárias (ex: Zone - Custom Hostnames: Edit e Zone - Zone: Read).

Tela User API Tokens em dash.cloudflare.com/profile/api-tokens para gerenciamento e criação de tokens.

Formulário de criação de Custom Token configurando as permissões de escopo para a zona do seu SaaS.

Abaixo está um exemplo em Node.js / JavaScript (Fetch API) pronto para uso no seu backend:

// Exemplo de integração do Backend do SaaS com a API da Cloudflare
async function addCustomHostname(clientDomain) {
    const zoneId = "SEU_CLOUDFLARE_ZONE_ID";
    const apiToken = process.env.CLOUDFLARE_API_TOKEN;

    const response = await fetch(
        `https://api.cloudflare.com/client/v4/zones/${zoneId}/custom_hostnames`,
        {
            method: "POST",
            headers: {
                "Authorization": `Bearer ${apiToken}`,
                "Content-Type": "application/json"
            },
            body: JSON.stringify({
                hostname: clientDomain, // ex: "app.cliente.com.br"
                ssl: {
                    method: "http", // Validação automática via HTTP CNAME
                    type: "dv",
                    settings: {
                        http2: "on",
                        min_tls_version: "1.2"
                    }
                }
            })
        }
    );

    const data = await response.json();
    
    if (!data.success) {
        throw new Error(`Erro Cloudflare API: ${data.errors[0]?.message}`);
    }

    // Retorna o ID e o status (ex: "pending_validation" ou "active")
    return {
        id: data.result.id,
        hostname: data.result.hostname,
        status: data.result.status,
        sslStatus: data.result.ssl.status
    };
}

Resumo & Boas Práticas

Com a estrutura montada, quando o seu cliente aponta o CNAME dele para o seu Fallback Origin, a Cloudflare valida a requisição, emite o certificado SSL automaticamente (em 1 a 5 minutos) e passa a servir a aplicação do seu SaaS de forma transparente e segura.

• Preço: Os primeiros 100 domínios customizados no Cloudflare for SaaS são totalmente grátis. A partir do 101º domínio, o custo é de apenas $0,10 / mês por domínio ativo.
• Segurança: O endereço IP real da sua infraestrutura fica mascarado atrás da rede global da Cloudflare, prevenindo ataques diretos ao seu servidor.
• Multitenancy no Código: No seu servidor web (Express, Next.js, Fastify, Laravel, etc.), inspecione o cabeçalho Host da requisição para saber qual cliente está acessando e carregar os dados correspondentes da conta dele.