API de User

Visión General

La API de User es una API REST para gestionar cuentas de usuario de Fess. Permite crear, obtener, actualizar y eliminar usuarios, además de asignar roles y grupos.

Esta es una API de administración, y el acceso requiere autenticación con un token de acceso de administrador. Consulte Visión General de Admin API para conocer el método de autenticación y las especificaciones comunes.

Cada respuesta está envuelta en un objeto response e incluye los siguientes campos comunes:

  • version : La cadena de versión del producto Fess.

  • status : El código de estado del resultado (0 =éxito, 1 =solicitud incorrecta, 2 =error del sistema, 3 =no autorizado, 9 =fallo).

URL Base

/api/admin/user

Lista de Endpoints

Método Ruta Descripción
GET /settings Listar usuarios
GET /setting/{id} Obtener usuario
POST /setting Crear usuario
PUT /setting Actualizar usuario
DELETE /setting/{id} Eliminar usuario

Listar Usuarios

Solicitud

GET /api/admin/user/settings

Parámetros

Parámetro Tipo Requerido Descripción
size Integer No Número de elementos por página. El valor predeterminado es el valor configurado paging.page.size (predeterminado: 25).
page Integer No Número de página (comienza en 1). El valor predeterminado es 1.

Nota

En la implementación actual, el endpoint de lista de usuarios no aplica los parámetros size y page. Siempre devuelve la primera página, con el número de elementos definido por la configuración del servidor paging.page.size (predeterminado: 25), ordenado por nombre de usuario (name) en orden ascendente. El número total de usuarios coincidentes está disponible en response.total.

Respuesta

{
  "response": {
    "version": "15.7.0",
    "status": 0,
    "settings": [
      {
        "id": "YWRtaW4=",
        "name": "admin",
        "attributes": {
          "surname": "Administrator",
          "givenName": "System",
          "mail": "admin@example.com"
        },
        "roles": ["admin"],
        "groups": [],
        "versionNo": 1
      }
    ],
    "total": 10
  }
}

  • settings : El array de usuarios en la página actual.

  • total : El número total de usuarios coincidentes.

Obtener Usuario

Solicitud

GET /api/admin/user/setting/{id}

Especifique el ID de documento del usuario objetivo en {id}.

Respuesta

{
  "response": {
    "version": "15.7.0",
    "status": 0,
    "setting": {
      "id": "YWRtaW4=",
      "name": "admin",
      "attributes": {
        "surname": "Administrator",
        "givenName": "System",
        "mail": "admin@example.com",
        "telephoneNumber": "",
        "uidNumber": "",
        "gidNumber": "",
        "homeDirectory": ""
      },
      "roles": ["admin"],
      "groups": [],
      "versionNo": 1
    }
  }
}

Nota

attributes incluye todos los atributos almacenados para el usuario, excepto name, password, roles y groups. password no se incluye en la respuesta.

Crear Usuario

Solicitud

POST /api/admin/user/setting
Content-Type: application/json

Cuerpo de la Solicitud

{
  "name": "testuser",
  "password": "securepassword",
  "confirmPassword": "securepassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User",
    "mail": "testuser@example.com"
  },
  "roles": ["user"],
  "groups": ["group_id_1"]
}

Descripción de Campos

Campo Requerido Descripción
name Sí Nombre de usuario (ID de inicio de sesión)
password No Contraseña
confirmPassword No Contraseña de confirmación
attributes No Mapa de atributos (véase más adelante)
roles No Array de IDs de roles
groups No Array de IDs de grupos

Nota

La API REST no realiza la verificación de contraseña obligatoria, la verificación de coincidencia entre password y confirmPassword, ni la validación de política de contraseñas (estas se aplican únicamente en la interfaz de administración). En la práctica, se recomienda especificar una password válida cuyo valor coincida con confirmPassword.

Las claves de attributes son los nombres de atributos de la entidad de usuario (los nombres de elementos derivados del esquema LDAP). Las claves más comunes son:

  • surname, givenName, displayName, mail

  • telephoneNumber, mobile, homePhone

  • employeeNumber, title, description, homeDirectory

  • uidNumber, gidNumber

uidNumber y gidNumber deben ser numéricos (su tipo se valida en la actualización). También se pueden especificar muchas otras claves de atributos LDAP.

Nota

En la creación, el ID de usuario (ID de documento) se genera automáticamente como el valor codificado en Base64 URL del nombre de usuario (por ejemplo, el nombre de usuario admin se convierte en YWRtaW4=).

Respuesta

{
  "response": {
    "version": "15.7.0",
    "status": 0,
    "id": "new_user_id",
    "created": true
  }
}

  • id : El ID de documento del usuario creado.

  • created : true cuando se ha creado.

Actualizar Usuario

Solicitud

PUT /api/admin/user/setting
Content-Type: application/json

Cuerpo de la Solicitud

{
  "id": "existing_user_id",
  "name": "testuser",
  "password": "newpassword",
  "confirmPassword": "newpassword",
  "attributes": {
    "surname": "Test",
    "givenName": "User Updated",
    "mail": "testuser.updated@example.com"
  },
  "roles": ["user", "editor"],
  "groups": ["group_id_1", "group_id_2"],
  "versionNo": 1
}

Descripción de Campos

Campo Requerido Descripción
id Sí El ID de documento del usuario a actualizar.
name Sí Nombre de usuario (ID de inicio de sesión)
versionNo Sí Número de versión (para bloqueo optimista)
password No Nueva contraseña (se actualiza solo cuando se especifica)
confirmPassword No Contraseña de confirmación
attributes No Mapa de atributos (véase «Crear Usuario»)
roles No Array de IDs de roles
groups No Array de IDs de grupos

Nota

En la actualización, id, name y versionNo son obligatorios. versionNo es el valor devuelto al obtener el usuario objetivo (GET), y corresponde a la versión del documento de OpenSearch. Si no coincide con la versión actual, la solicitud se trata como un conflicto y la actualización es rechazada.

Respuesta

{
  "response": {
    "version": "15.7.0",
    "status": 0,
    "id": "existing_user_id",
    "created": false
  }
}

  • created : false para una actualización.

Eliminar Usuario

Solicitud

DELETE /api/admin/user/setting/{id}

Especifique el ID de documento del usuario a eliminar en {id}.

Nota

No es posible eliminar el usuario que tiene la sesión actualmente iniciada.

Respuesta

{
  "response": {
    "version": "15.7.0",
    "status": 0,
    "id": "deleted_user_id",
    "created": false
  }
}

  • id : El ID de documento del usuario eliminado.

Ejemplos de Uso

Crear Nuevo Usuario

curl -X POST "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "john.doe",
       "password": "SecureP@ss123",
       "confirmPassword": "SecureP@ss123",
       "attributes": {
         "surname": "Doe",
         "givenName": "John",
         "mail": "john.doe@example.com"
       },
       "roles": ["user"],
       "groups": []
     }'

Cambiar Roles de Usuario

curl -X PUT "http://localhost:8080/api/admin/user/setting" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "id": "user_id_123",
       "name": "john.doe",
       "roles": ["user", "editor", "admin"],
       "versionNo": 1
     }'

Referencia