API del agente de Active Directory

La API de cola de tareas que el agente local de Active Directory consulta para crear y deshabilitar cuentas de AD.

ClockEU no puede acceder directamente al controlador de dominio de una empresa, ya que está detrás de su firewall. En su lugar, el agente (un pequeño servicio de Windows instalado en un equipo dentro de esa red) consulta periódicamente estos dos endpoints mediante HTTPS de salida, de modo que nunca es necesario abrir ningún puerto de entrada.

Authentication

Genere un token de agente desde Configuración → Active Directory; se muestra una sola vez. Péguelo en el asistente de configuración del agente.

POST /api/ad-agent-poll.php

Devuelve las tareas pendientes para esta empresa (create_user / disable_user) y las marca como "sent" para que una segunda consulta antes de que esta termine no entregue la misma tarea dos veces.

curl -X POST https://acme.clockeu.eu/api/ad-agent-poll.php \
  -H "Authorization: Bearer <agent_token>" \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "DC01"}'
{
  "ok": true,
  "jobs": [
    {
      "job_id": 42,
      "type": "create_user",
      "payload": {
        "samAccountName": "j.smith",
        "upn": "j.smith@corp.local",
        "givenName": "Jane",
        "surname": "Smith",
        "displayName": "Jane Smith",
        "email": "j.smith@corp.local",
        "password": "T3mp-Pass!92x",
        "ou": null
      }
    }
  ]
}

POST /api/ad-agent-result.php

Informa que una tarea se ha completado o ha fallado. La contraseña de un solo uso de una tarea create_user se elimina de la base de datos en el momento en que esto se realiza correctamente; no se puede volver a leer después.

curl -X POST https://acme.clockeu.eu/api/ad-agent-result.php \
  -H "Authorization: Bearer <agent_token>" \
  -H "Content-Type: application/json" \
  -d '{"job_id": 42, "ok": true, "account": "j.smith"}'

Example: a minimal agent loop

import time, requests

BASE = "https://acme.clockeu.eu"
HEADERS = {"Authorization": "Bearer <agent_token>"}

while True:
    r = requests.post(f"{BASE}/api/ad-agent-poll.php", headers=HEADERS,
                      json={"agent_name": "DC01"}, timeout=30)
    for job in r.json().get("jobs", []):
        try:
            account = create_or_disable_in_ad(job)      # your code: LDAP / PowerShell
            result = {"job_id": job["job_id"], "ok": True, "account": account}
        except Exception as e:
            result = {"job_id": job["job_id"], "ok": False, "error": str(e)}
        requests.post(f"{BASE}/api/ad-agent-result.php", headers=HEADERS, json=result, timeout=30)
    time.sleep(60)

Descargue el agente ya preparado (código fuente e instrucciones de instalación) desde Software.