Automatizar el realm desde Go

// Package provision lleva la configuración de Keycloak a un estado deseado,
// descrito en un archivo: qué servicios internos existen, a qué APIs pueden
// llamar (audiencias) y con qué permisos (roles de client de esas APIs).
//
// Cada paso compara lo que hay con lo que debería haber y solo cambia la
// diferencia: aplicarlo dos veces no hace nada la segunda (idempotencia).
// Con Plan=true no cambia nada: solo dice lo que haría.
package provision

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"slices"

	"github.com/Nerzal/gocloak/v14"
)

// Service describe un servicio interno que llama a APIs con Client Credentials.
type Service struct {
	ClientID    string              `json:"clientId"`
	Description string              `json:"descripcion"`
	Audiences   []string            `json:"audiencias"` // client scopes de audiencia, como Default
	APIRoles    map[string][]string `json:"rolesDeAPI"` // client de la API → roles para la service account
}

// Desired es el contenido del archivo de estado deseado.
type Desired struct {
	Services []Service `json:"servicios"`
}

// Provisioner aplica (o planifica) el estado deseado en un realm.
type Provisioner struct {
	KC    *gocloak.GoCloak
	Token string // token de admin-tool (manage-clients, manage-users…)
	Realm string
	Plan  bool // true: no cambia nada, solo lista los cambios
}

// Result es lo que se hizo (o se haría) con un servicio.
type Result struct {
	Changes []string
	Secret  string // solo si se acaba de crear el client
}

// Apply lleva un servicio al estado deseado.
func (p *Provisioner) Apply(ctx context.Context, s Service) (Result, error) {
	var res Result
	change := func(format string, args ...any) { res.Changes = append(res.Changes, fmt.Sprintf(format, args...)) }

	// 1. El client: confidencial, solo con service account.
	client, err := p.findClient(ctx, s.ClientID)
	if err != nil {
		return res, err
	}
	if client == nil {
		change("crear client %s (confidencial, solo service account)", s.ClientID)
		if p.Plan {
			// Sin client no podemos mirar más: lo demás se crearía entero.
			for _, a := range s.Audiences {
				change("asignar el scope %s como Default", a)
			}
			for api, roles := range s.APIRoles {
				for _, r := range roles {
					exists, err := p.roleExists(ctx, api, r)
					if err != nil {
						return res, err
					}
					if !exists {
						change("crear el rol %s en %s", r, api)
					}
					change("dar a la service account el rol %s de %s", r, api)
				}
			}
			return res, nil
		}
		id, err := p.KC.CreateClient(ctx, p.Token, p.Realm, wantedClient(s))
		if err != nil {
			return res, fmt.Errorf("crear client %s: %w", s.ClientID, err)
		}
		if client, err = p.KC.GetClient(ctx, p.Token, p.Realm, id); err != nil {
			return res, err
		}
		cred, err := p.KC.GetClientSecret(ctx, p.Token, p.Realm, id)
		if err != nil {
			return res, err
		}
		res.Secret = gocloak.PString(cred.Value)
	} else if diffs := drift(client, s); len(diffs) > 0 {
		for _, d := range diffs {
			change("corregir %s", d)
		}
		if !p.Plan {
			fix(client, s)
			if err := p.KC.UpdateClient(ctx, p.Token, p.Realm, *client); err != nil {
				return res, fmt.Errorf("actualizar client %s: %w", s.ClientID, err)
			}
		}
	}
	clientID := gocloak.PString(client.ID)

	// 2. Audiencias: los client scopes, asignados como Default.
	assigned, err := p.KC.GetClientsDefaultScopes(ctx, p.Token, p.Realm, clientID)
	if err != nil {
		return res, err
	}
	for _, name := range s.Audiences {
		if slices.ContainsFunc(assigned, func(cs *gocloak.ClientScope) bool { return gocloak.PString(cs.Name) == name }) {
			continue
		}
		scopeID, err := p.scopeID(ctx, name)
		if err != nil {
			return res, err
		}
		change("asignar el scope %s como Default", name)
		if !p.Plan {
			if err := p.KC.AddDefaultScopeToClient(ctx, p.Token, p.Realm, clientID, scopeID); err != nil {
				return res, fmt.Errorf("asignar scope %s: %w", name, err)
			}
		}
	}

	// 3. Permisos: roles de client de cada API para la service account.
	sa, err := p.KC.GetClientServiceAccount(ctx, p.Token, p.Realm, clientID)
	if err != nil {
		return res, fmt.Errorf("service account de %s: %w", s.ClientID, err)
	}
	for api, roles := range s.APIRoles {
		apiClient, err := p.findClient(ctx, api)
		if err != nil {
			return res, err
		}
		if apiClient == nil {
			return res, fmt.Errorf("la API %s no existe como client", api)
		}
		apiID := gocloak.PString(apiClient.ID)
		have, err := p.KC.GetClientRolesByUserID(ctx, p.Token, p.Realm, apiID, gocloak.PString(sa.ID))
		if err != nil {
			return res, err
		}
		for _, roleName := range roles {
			if slices.ContainsFunc(have, func(r *gocloak.Role) bool { return gocloak.PString(r.Name) == roleName }) {
				continue
			}
			role, err := p.KC.GetClientRole(ctx, p.Token, p.Realm, apiID, roleName)
			if isNotFound(err) {
				change("crear el rol %s en %s", roleName, api)
				if p.Plan {
					change("dar a la service account el rol %s de %s", roleName, api)
					continue
				}
				if _, err = p.KC.CreateClientRole(ctx, p.Token, p.Realm, apiID, gocloak.Role{Name: gocloak.StringP(roleName)}); err != nil {
					return res, err
				}
				role, err = p.KC.GetClientRole(ctx, p.Token, p.Realm, apiID, roleName)
			}
			if err != nil {
				return res, err
			}
			change("dar a la service account el rol %s de %s", roleName, api)
			if !p.Plan {
				if err := p.KC.AddClientRolesToUser(ctx, p.Token, p.Realm, apiID, gocloak.PString(sa.ID), []gocloak.Role{*role}); err != nil {
					return res, err
				}
			}
		}
	}
	return res, nil
}

// wantedClient es el client tal como debe quedar al crearlo.
func wantedClient(s Service) gocloak.Client {
	c := gocloak.Client{ClientID: gocloak.StringP(s.ClientID)}
	fix(&c, s)
	return c
}

// fix pone en c la configuración que exige un servicio interno.
func fix(c *gocloak.Client, s Service) {
	c.Description = gocloak.StringP(s.Description)
	c.Enabled = gocloak.BoolP(true)
	c.PublicClient = gocloak.BoolP(false)
	c.ClientAuthenticatorType = gocloak.StringP("client-secret")
	c.ServiceAccountsEnabled = gocloak.BoolP(true)
	c.StandardFlowEnabled = gocloak.BoolP(false)
	c.ImplicitFlowEnabled = gocloak.BoolP(false)
	c.DirectAccessGrantsEnabled = gocloak.BoolP(false)
}

// drift lista en qué se aparta un client existente de lo deseado.
func drift(c *gocloak.Client, s Service) []string {
	want := wantedClient(s)
	var out []string
	check := func(name string, got, wanted *bool) {
		if gocloak.PBool(got) != gocloak.PBool(wanted) {
			out = append(out, fmt.Sprintf("%s: %v → %v", name, gocloak.PBool(got), gocloak.PBool(wanted)))
		}
	}
	check("enabled", c.Enabled, want.Enabled)
	check("publicClient", c.PublicClient, want.PublicClient)
	check("serviceAccountsEnabled", c.ServiceAccountsEnabled, want.ServiceAccountsEnabled)
	check("standardFlowEnabled", c.StandardFlowEnabled, want.StandardFlowEnabled)
	check("implicitFlowEnabled", c.ImplicitFlowEnabled, want.ImplicitFlowEnabled)
	check("directAccessGrantsEnabled", c.DirectAccessGrantsEnabled, want.DirectAccessGrantsEnabled)
	if gocloak.PString(c.Description) != s.Description {
		out = append(out, fmt.Sprintf("description: %q → %q", gocloak.PString(c.Description), s.Description))
	}
	return out
}

// findClient busca un client por su clientId; nil si no existe.
func (p *Provisioner) findClient(ctx context.Context, clientID string) (*gocloak.Client, error) {
	cs, err := p.KC.GetClients(ctx, p.Token, p.Realm, gocloak.GetClientsParams{ClientID: gocloak.StringP(clientID)})
	if err != nil {
		return nil, err
	}
	for _, c := range cs {
		if gocloak.PString(c.ClientID) == clientID {
			return c, nil
		}
	}
	return nil, nil
}

// scopeID busca el ID de un client scope por su nombre.
func (p *Provisioner) scopeID(ctx context.Context, name string) (string, error) {
	scopes, err := p.KC.GetClientScopes(ctx, p.Token, p.Realm)
	if err != nil {
		return "", err
	}
	for _, cs := range scopes {
		if gocloak.PString(cs.Name) == name {
			return gocloak.PString(cs.ID), nil
		}
	}
	return "", fmt.Errorf("el client scope %s no existe", name)
}

// roleExists indica si la API (un client) tiene el rol de client roleName.
func (p *Provisioner) roleExists(ctx context.Context, api, roleName string) (bool, error) {
	apiClient, err := p.findClient(ctx, api)
	if err != nil || apiClient == nil {
		return false, fmt.Errorf("la API %s no existe como client (%v)", api, err)
	}
	_, err = p.KC.GetClientRole(ctx, p.Token, p.Realm, gocloak.PString(apiClient.ID), roleName)
	if isNotFound(err) {
		return false, nil
	}
	return err == nil, err
}

func isNotFound(err error) bool {
	var apiErr *gocloak.APIError
	return errors.As(err, &apiErr) && apiErr.Code == http.StatusNotFound
}

// Command provision lleva los servicios internos de servicios.json a Keycloak:
// crea o corrige sus clients, audiencias y roles de API. Es idempotente.
//
// Uso (desde tienda/pasos/paso-10):
//
//	go run ./cmd/provision -plan     (solo muestra los cambios)
//	go run ./cmd/provision           (los aplica)
package main

import (
	"context"
	"encoding/json"
	"flag"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/Nerzal/gocloak/v14"

	"tienda/internal/provision"
)

func main() {
	log.SetFlags(0)
	file := flag.String("f", "servicios.json", "archivo con el estado deseado")
	plan := flag.Bool("plan", false, "no cambiar nada: solo listar los cambios")
	flag.Parse()

	raw, err := os.ReadFile(*file)
	if err != nil {
		log.Fatal(err)
	}
	var desired provision.Desired
	if err := json.Unmarshal(raw, &desired); err != nil {
		log.Fatalf("%s: %v", *file, err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	realm := env("KEYCLOAK_REALM", "tienda")
	kc := gocloak.NewClient(env("KEYCLOAK_URL", "http://localhost:8080"))
	jwt, err := kc.LoginClient(ctx, env("ADMIN_CLIENT_ID", "admin-tool"), env("ADMIN_CLIENT_SECRET", "admin-tool-secret"), realm)
	if err != nil {
		log.Fatalf("login de admin-tool: %v", err)
	}
	p := &provision.Provisioner{KC: kc, Token: jwt.AccessToken, Realm: realm, Plan: *plan}

	verb := "aplicado"
	if *plan {
		verb = "plan"
	}
	for _, s := range desired.Services {
		res, err := p.Apply(ctx, s)
		if err != nil {
			log.Fatalf("%s: %v", s.ClientID, err)
		}
		if len(res.Changes) == 0 {
			fmt.Printf("= %s: sin cambios\n", s.ClientID)
			continue
		}
		fmt.Printf("~ %s (%s):\n", s.ClientID, verb)
		for _, c := range res.Changes {
			fmt.Printf("    - %s\n", c)
		}
		if res.Secret != "" {
			// Se muestra una sola vez: guárdalo en tu gestor de secretos.
			fmt.Printf("    secreto del client: %s\n", res.Secret)
		}
	}
}

func env(key, def string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return def
}