# 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 <p className="text-zinc-400 font-mono">Não autorizado.</p>;
  }

  // 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 (
    <div className="min-h-screen bg-zinc-950 text-zinc-100 flex flex-col p-8 font-sans">
      <div className="max-w-5xl w-full mx-auto space-y-6">
        
        <header className="border-b border-zinc-800 pb-4 mb-8">
          <h1 className="text-3xl font-bold tracking-tight">Identity Control Plane</h1>
          <p className="text-zinc-500 mt-2">Visão Administrativa Zitadel</p>
        </header>

        <section className="bg-zinc-900 rounded-xl border border-zinc-800 p-6 shadow-2xl">
          <h2 className="text-xl font-semibold mb-4 text-white">Perfil Atual</h2>
          <div className="grid grid-cols-2 gap-4">
            <div className="bg-black/50 p-4 rounded-lg">
              <span className="text-xs text-zinc-500 uppercase">Usuário</span>
              <p className="font-medium font-mono text-zinc-300 mt-1">{session.user.name}</p>
            </div>
            <div className="bg-black/50 p-4 rounded-lg">
              <span className="text-xs text-zinc-500 uppercase">E-mail ID</span>
              <p className="font-medium font-mono text-blue-400 mt-1">{session.user.email}</p>
            </div>
          </div>
        </section>

        <section className="bg-zinc-900 rounded-xl border border-zinc-800 p-6 shadow-2xl">
          <h2 className="text-xl font-semibold mb-4 flex items-center justify-between">
            <span>Organizações <span className="ml-2 text-xs bg-indigo-500/20 text-indigo-400 px-2 py-1 rounded-md">Service API</span></span>
          </h2>
          
          <ul className="space-y-3">
            {organizations.length === 0 ? (
              <li className="text-zinc-500 text-sm">Nenhuma organização encontrada sob este tenant.</li>
            ) : (
              organizations.map((org) => (
                <li key={org.id} className="flex justify-between items-center p-4 bg-black/40 rounded-lg border border-zinc-800 hover:border-indigo-500 transition-colors cursor-pointer">
                  <div className="flex flex-col">
                    <span className="font-medium text-zinc-200">{org.name}</span>
                    <span className="text-xs font-mono text-zinc-600 mt-1">ID: {org.id}</span>
                  </div>
                  <span className="text-xs px-3 py-1 bg-emerald-500/10 text-emerald-400 rounded-full border border-emerald-500/20">Active</span>
                </li>
              ))
            )}
          </ul>
        </section>

      </div>
    </div>
  );
}
```

---

## 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.