Gestión de Usuarios

Auris proporciona un sistema completo de gestión del ciclo de vida de los usuarios accesible tanto a través de la Consola de Administración como de la API REST. Los administradores pueden listar, crear, actualizar, deshabilitar, eliminar de forma temporal y restaurar usuarios sin tocar la interfaz de administración nativa de Keycloak.

Listado de Usuarios

La lista de usuarios admite paginación, búsqueda de texto completo, filtrado por rol y filtrado por estado. Los resultados se devuelven en el sobre de paginación estándar de Auris.

Estructura de la respuesta:

{
  "data": [
    {
      "id": "usr_01HX...",
      "email": "[email protected]",
      "username": "alice",
      "firstName": "Alice",
      "lastName": "Rossi",
      "enabled": true,
      "roles": ["member"],
      "createdAt": "2025-03-01T10:00:00Z",
      "lastLogin": "2025-06-10T08:45:00Z",
      "metadata": {}
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Guía en la Consola: Navega a Consola de Administración → Usuarios. La tabla se actualiza automáticamente cuando cambias el término de búsqueda o aplicas filtros. Haz clic en cualquier fila para abrir el panel de detalle del usuario.

Creación de Usuarios

Los usuarios pueden crearse directamente con una contraseña, o sin una para activar un email de invitación que solicita al usuario que establezca sus propias credenciales.

Cuerpo de la solicitud:

{
  "email": "[email protected]",
  "username": "bob",
  "firstName": "Bob",
  "lastName": "Marley",
  "password": "ContraseñaSegura123!",
  "sendInvite": false,
  "roles": ["member"],
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421"
  }
}

Referencia de campos:

Guía en la Consola: Haz clic en el botón “Nuevo Usuario” en la página de Usuarios. El diálogo presenta un formulario con pestañas: General (nombre, email), Credenciales (contraseña o selector de invitación) y Roles (selección múltiple).

Actualización de Usuarios

Campos actualizables:

{
  "firstName": "Roberto",
  "lastName": "Marley",
  "enabled": true,
  "roles": ["member", "billing-admin"],
  "metadata": {
    "department": "leadership"
  }
}

Actualizar roles reemplaza completamente el conjunto de roles del usuario — incluye todos los roles previstos, no solo los que se añaden. Para añadir un único rol sin afectar a los demás, lee primero la lista de roles actual, agrega el nuevo rol y luego envía el conjunto completo.

Actualizar enabled: false deshabilita inmediatamente al usuario en Keycloak, invalidando todas las sesiones activas.

Eliminación Temporal y Restauración

Auris utiliza la eliminación temporal para preservar los registros de auditoría. Eliminar un usuario marca el registro con deletedAt en lugar de eliminarlo de la base de datos o de Keycloak.

Restaurar un usuario:

Guía en la Consola: La página de Usuarios tiene una pestaña de filtro “Eliminados” que muestra los usuarios eliminados temporalmente. Cada fila de usuario eliminado tiene una acción “Restaurar” en el menú desplegable.

Sesiones de Usuario

Auris rastrea las sesiones activas de Keycloak por usuario. Los administradores pueden ver los detalles de las sesiones y revocar sesiones individuales para forzar la re-autenticación — útil cuando el dispositivo de un usuario se pierde o se ve comprometido.

Guía en la Consola: Abre el panel de detalle de un usuario y selecciona la pestaña “Sesiones”. Cada sesión muestra el navegador/SO, la dirección IP, la hora de inicio de sesión y un botón “Revocar”.

Metadatos de Usuario

Los metadatos te permiten almacenar datos JSON arbitrarios en un usuario sin modificar el esquema de Auris. Se devuelven en cada objeto de usuario y son accesibles en el SDK de Gestión.

Casos de uso comunes:

• Preferencias específicas de la aplicación (theme, language, timezone)
• Identificadores internos (employeeId, costCenter, managerId)
• Indicadores de funcionalidades o datos de permisos
• Seguimiento del progreso de incorporación

Los metadatos se almacenan como un objeto JSON plano o anidado. No hay un esquema obligatorio — la estructura es completamente definida por la aplicación.

{
  "metadata": {
    "department": "engineering",
    "employeeId": "EMP-4421",
    "onboarding": {
      "completed": true,
      "completedAt": "2025-04-15T09:00:00Z"
    }
  }
}

SDK de Gestión

Usa el SDK de Gestión para la administración de usuarios del lado del servidor. El SDK de Gestión se autentica mediante credenciales de cliente M2M — no está diseñado para su uso en código del navegador.

import { AurisClient } from '@auris/js'
 
const auris = new AurisClient({
  domain: 'https://auth.tuapp.com',
  clientId: process.env.AURIS_CLIENT_ID,
  clientSecret: process.env.AURIS_CLIENT_SECRET,
})
 
// Crear un cliente de gestión autenticado con credenciales M2M
const mgmt = auris.createManagementClient({
  clientId: process.env.AURIS_MGMT_CLIENT_ID,
  clientSecret: process.env.AURIS_MGMT_CLIENT_SECRET,
})
 
// Listar usuarios con paginación
const result = await mgmt.users.list({ page: 1, limit: 20 })
console.log(result.data)       // User[]
console.log(result.pagination) // { page, limit, total, totalPages }
 
// Obtener un usuario específico
const user = await mgmt.users.get('usr_01HX...')
 
// Crear un usuario
const nuevoUsuario = await mgmt.users.create({
  email: '[email protected]',
  firstName: 'Carol',
  roles: ['member'],
  sendInvite: true,
})
 
// Actualizar un usuario
await mgmt.users.update('usr_01HX...', {
  metadata: { department: 'product' },
})
 
// Deshabilitar un usuario
await mgmt.users.update('usr_01HX...', { enabled: false })
 
// Eliminar un usuario (temporal)
await mgmt.users.delete('usr_01HX...')

import { createServerManagementClient } from '@auris/nextjs/server'
 
// En un Route Handler o Server Component
export async function GET() {
  // Lee automáticamente AURIS_MGMT_CLIENT_ID y AURIS_MGMT_CLIENT_SECRET del entorno
  const mgmt = createServerManagementClient()
 
  const user = await mgmt.users.get('usr_01HX...')
 
  return Response.json(user)
}
 
// Listado de usuarios en un Server Component
async function PaginaAdminUsuarios() {
  const mgmt = createServerManagementClient()
  const { data: usuarios, pagination } = await mgmt.users.list({
    page: 1,
    limit: 50,
    search: '',
  })
 
  return (
    <ul>
      {usuarios.map((u) => (
        <li key={u.id}>{u.email}</li>
      ))}
    </ul>
  )
}

Permisos Requeridos

Páginas Relacionadas

• Consola: Usuarios y Roles — Guía visual de la interfaz de gestión de usuarios de la Consola de Administración
• Importación y Exportación de Usuarios — Importación masiva de usuarios desde CSV o JSON
• Aprovisionamiento SCIM 2.0 — Aprovisionamiento automatizado desde Okta, Azure AD y proveedores similares
• Claims JWT Personalizados — Inyectar metadatos de usuario en los access tokens