@adatechnology/keycloak-admin
Cliente do Keycloak Admin API autenticado como service account (client_credentials).
Agnóstico de framework e de runtime: só depende de fetch e de zod.
Diferença deliberada para o @adatechnology/nestjs-keycloak-admin: aquele obtém token com
grant_type=password usando o usuário administrador do realm master. Este nunca envia senha
nem usuário — a identidade é do client confidencial, com manage-users do realm-management.
Uso
import { createKeycloakAdminClient } from '@adatechnology/keycloak-admin'
const keycloak = createKeycloakAdminClient({
config: {
baseUrl: process.env.KEYCLOAK_URL,
clientId: process.env.KEYCLOAK_ADMIN_CLIENT_ID,
clientSecret: process.env.KEYCLOAK_ADMIN_CLIENT_SECRET,
realm: process.env.KEYCLOAK_REALM,
},
})
const { id } = await keycloak.createUser({
attributes: { company_id: companyId },
email: '[email protected]',
enabled: true,
firstName: 'Ada',
lastName: 'Lovelace',
password: { temporary: false, value: chosenPassword },
username: '[email protected]',
})
Operações de usuário: createUser, findUserByEmail, listUsers, updateUser, setEnabled,
updateAttributes, deleteUser, setPassword, setTemporaryPassword.
⚠️ updateAttributes e setProfilePicture leem a conta antes de gravar (GET + PUT da
representação completa). O Keycloak 26 com perfil de usuário declarativo trata o PUT com
attributes como a ficha inteira: só { attributes } responde 400 "User name is missing", e
{ username, attributes } apaga e-mail e nome. updateAttributes substitui o conjunto de atributos;
setProfilePicture troca só o picture. updateUser e setEnabled seguem parciais, sem leitura.
Foto de perfil: setProfilePicture({ userId, pictureUrl }). O atributo é picture, o nome que o
OIDC reserva — com um mapeador no realm ele chega ao token, e a tela desenha o avatar sem uma
consulta por pessoa.
⚠️ O Keycloak não hospeda imagem: o valor é uma URL e o arquivo é do produto. Base64 no atributo
cresce o token até ele parar de caber no cabeçalho, e o sintoma aparece longe — login que funciona
no navegador e falha no curl. A operação lê os atributos antes de gravar, porque o Admin API
substitui o conjunto: mandar só a foto apagaria company_id e o resto.
Operações de grupo: createGroup, updateGroup, deleteGroup, listGroups, addUserToGroup,
removeUserFromGroup. Só o primeiro nível — grupo aninhado muda o significado de "pertencer",
porque quem está no filho herda o pai, e um produto que não modela hierarquia não deve criá-la por
acidente. A filiação é endereçada pelo usuário (/users/{id}/groups/{id}), não pelo grupo.
listUsers({ first, limit, search }) devolve { users, hasMore }. O realm não informa total, então
a página pede um registro a mais que o limite e descarta-o: é assim que hasMore sai sem uma
segunda chamada.
Token
Obtido sob demanda, guardado em memória e renovado 30s antes de expirar
(KEYCLOAK_ADMIN_TOKEN_RENEWAL_SKEW_MS). Chamadas concorrentes compartilham a mesma requisição em
voo — o Keycloak recebe uma, não N.
Injeção
fetch e now são injetáveis, o que torna rede e relógio observáveis em teste:
createKeycloakAdminClient({ config, fetch: stubFetch, now: clock.now })
Erros
Toda falha vira KeycloakAdminError com code estável (KEYCLOAK_ADMIN_ERROR_CODE), status e
context. O contexto é montado por allowlist e passa por um redator que substitui clientSecret,
access token e senha por [REDACTED] — nem a mensagem nem o erro serializado carregam segredo.
Configuração inválida falha na construção do cliente, com o caminho do campo no contexto e nunca o valor.