From e42d616acd3c708d1012db9a7598ef45be5f233b Mon Sep 17 00:00:00 2001 From: Tiago Ribeiro Date: Mon, 9 Mar 2026 16:05:48 -0300 Subject: [PATCH] docs: add zitadel and nextjs setup guidelines to replace legacy applications --- ZITADEL_SETUP.md | 225 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 ZITADEL_SETUP.md diff --git a/ZITADEL_SETUP.md b/ZITADEL_SETUP.md new file mode 100644 index 0000000..cfbf39c --- /dev/null +++ b/ZITADEL_SETUP.md @@ -0,0 +1,225 @@ +# Zitadel + Next.js App Router Integration Setup + +Guia corporativo atuando como Especialista em Engenharia de Software e DevOps para inicialização do ecossistema Zitadel on-premise (Baremetal/Binário direto) integrado à um ambiente moderno Next.js. + +## Parte 1: Setup do Serviço de Autenticação (Zitadel) + +### 1. Download e Instalação (Binário Oficial) +O Zitadel é distribuído em um binário em Go altamente otimizado. Para ambientes baseados em Linux/MacOS: + +```bash +# Definir a versão alvo +export ZITADEL_VERSION="v2.66.3" # ou a tag latest estável + +# Download macOS (usar darwin_arm64 para Apple Silicon ou darwin_amd64 para Intel) +# Download Linux (usar linux_amd64 ou linux_arm64) +curl -sLO "https://github.com/zitadel/zitadel/releases/download/${ZITADEL_VERSION}/zitadel_Linux_x86_64.tar.gz" + +# Extrair +tar -xvf zitadel_Linux_x86_64.tar.gz + +# Mover binário pro path +sudo mv zitadel /usr/local/bin/ +``` + +### 2. Configuração Básica e Local (Sem TLS / Insecure) +Crie um arquivo `config.yaml` voltado para acoplamento interno. Ele especifica conexões sem segredos e expõe a interface sem demandar certificados TLS para localhost. + +**`config.yaml`**: +```yaml +ExternalSecure: false +Port: 8080 + +# Conexão com sua base PostgreSQL limpa inicializada (Pode ser local/Docker) +Database: + postgres: + Host: localhost + Port: 5432 + Database: zitadel + User: + Username: "postgres" + Password: "your-password" + SSL: + Mode: disable + Admin: + Username: "postgres" + Password: "your-password" + SSL: + Mode: disable +``` + +### 3. Setup e Start +A injeção dos esquemas base e a inicialização do container de autenticação: + +```bash +# 1. Aplicar migrações ao PostgreSQL provisionado +zitadel setup --masterkey "a-32-byte-master-key-must-be-set" --config config.yaml + +# 2. Levantar o Listener HTTP +zitadel start --masterkey "a-32-byte-master-key-must-be-set" --config config.yaml +``` + +*O setup inicial gerará um log contendo as informações do usuário `machine` primário (`zitadel-admin`). Guarde este log/json.* + +### 4. Gerar chaves (Service User \/ Machine Key) +1. Acesse `http://localhost:8080/ui/console`. +2. Vá em **Projects** > (Seu projeto) > **Service Users**. +3. Crie um novo. Confirme. +4. Na página de gerenciar esse Service User, vá em **Keys** e adicione uma nova. +5. Selecione formato **JSON**. Ele fará o download da `machinekey.json`. Guarde esse documento num `secrets/` do Next. + +--- + +## Parte 2: Dashboard Next.js (App Router + Tailwind) + +### 1. Inicializando Projetos +```bash +npx create-next-app@latest admin-dashboard --typescript --tailwind --eslint --app +cd admin-dashboard +npm install @zitadel/nextjs @zitadel/server +``` + +### 2. Middleware de Proteção +Crie um arquivo em `src/middleware.ts` para capturar a sessão sem bloqueios pesados. + +```typescript +import { NextResponse } from "next/server"; +import type { NextRequest } from "next/server"; + +export function middleware(request: NextRequest) { + // A SDK usa os tokens armazenados em cookies. + const hasZitadelCookie = request.cookies.some((c) => c.name.includes("zitadel")); + + if (!hasZitadelCookie && request.nextUrl.pathname.startsWith("/dashboard")) { + return NextResponse.redirect(new URL("/api/auth/signin", request.url)); + } + + return NextResponse.next(); +} + +export const config = { + matcher: ["/dashboard/:path*"], +}; +``` + +### 3. Server Component de Dashboard +Interface estilizada de alto nível para exibição do IAM e profile contextual, injetante de tailwind corporativo de forma nativa e sem `use client`. + +`src/app/dashboard/page.tsx` +```tsx +import { getSession } from '@zitadel/nextjs'; +// A API Wrapper SDK para o client Admin gRPC/REST do Zitadel +import { createZitadelClient } from '@zitadel/server'; +import fs from 'fs/promises'; + +export default async function DashboardPage() { + const session = await getSession(); + + if (!session?.user) { + return

Não autorizado.

; + } + + // 1. Instanciando Client IAM via Machine JSON + const keyFile = await fs.readFile(process.cwd() + '/secrets/machinekey.json', 'utf8'); + const zitadelClient = createZitadelClient({ + token: keyFile, + apiUrl: process.env.ZITADEL_API_URL!, + }); + + // 2. Coletando Orgs + let organizations: any[] = []; + try { + const { orgs } = await zitadelClient.management.listOrgs({}); + organizations = orgs || []; + } catch (error) { + console.error("Falha ao buscar organizações", error); + } + + return ( +
+
+ +
+

Identity Control Plane

+

Visão Administrativa Zitadel

+
+ +
+

Perfil Atual

+
+
+ Usuário +

{session.user.name}

+
+
+ E-mail ID +

{session.user.email}

+
+
+
+ +
+

+ Organizações Service API +

+ +
    + {organizations.length === 0 ? ( +
  • Nenhuma organização encontrada sob este tenant.
    • + ) : ( + organizations.map((org) => ( +
  • +
    + {org.name} + ID: {org.id} +
    + Active +
    • + )) + )} +
+
+ +
+
+ ); +} +``` + +--- + +## Parte 3: Guia de Integração Ambiente Local + +### 1. Preparação Local Next.js (`.env.local`) +Adicione o endpoint do provedor OIDC e credenciais do dashboard para sua integração funcionar na rota cliente: + +```env +# SDK NextAuth +NEXTAUTH_URL="http://localhost:3000" +NEXTAUTH_SECRET="uma-string-secreta-gigante-aqui-random" + +# Zitadel Configuration (A porta que você mapeou no config.yaml) +ZITADEL_ISSUER="http://localhost:8080" +ZITADEL_CLIENT_ID="AQUI_VAI_O_CLIENT_ID_DO_SEU_WEB_APP" +ZITADEL_CLIENT_SECRET="AQUI_VAI_O_SECRET_DO_WEB_APP" + +# API Endpoint (Utilizado pelo Client JWT Server para as Orgs) +ZITADEL_API_URL="http://localhost:8080" +``` + +### 2. Rodando o Ecossistema Completamente Local + +Para rodar os serviços paralelos no seu ambiente de terminal: + +**No Terminal 1 (O IAM Authority Zitadel):** +```bash +./zitadel start --masterkey "a-32-byte-master-key-must-be-set" --config config.yaml +``` + +**No Terminal 2 (O Dashboard Edge-side):** +```bash +cd admin-dashboard +npm run dev +``` + +Essa arquitetura garante que a requisição de contexto do OIDC caia por trás dos painéis locais e que você utilize a `machinekey` (Service Account) internamente em rotas NodeJS sem jamais vazar a chave sensível da infraestrutura, além do Tailwind em Dark Mode proporcionar uma visualização profissional para auditoria de redes.