Gestionar de forma segura las credenciales de API de Sophos Central
Sophos Fusion (antes Sophos Central) puede automatizarse mediante API y conectarse a plataformas SIEM, RMM, de reporting o de seguros. Para ello no se utilizan cuentas personales de administrador, sino API Credentials propias formadas por una Client ID y un Client Secret.
Estas credenciales son identidades de máquina. Quien posea un secreto puede ejecutar todas las acciones de API permitidas por el rol de Service Principal asignado. Por eso, un secreto debe tratarse como una contraseña privilegiada y no debe almacenarse en scripts, tickets, correos electrónicos ni repositorios Git.
Diferenciar API Credentials e Integration Credential Manager
En Global Settings > Access Control hay dos áreas con nombres similares:
| Área | Función |
|---|---|
| API Credentials | Identidad técnica con la que una aplicación llama a las API de Sophos Central |
| Integration Credential Manager | Credenciales de productos externos que Sophos utiliza para integraciones como Data Ingestion o Response Actions |
Para un script propio, una consulta SIEM o un cliente de API se crean API Credentials. En cambio, las credenciales de un producto externo que deba utilizar el propio Sophos Fusion pertenecen al Integration Credential Manager.
No todas las automatizaciones requieren API Credentials generales: los usuarios y grupos se sincronizan mediante un servicio de directorio, y el software puede distribuirse con un script de instalación ejecutado localmente en cada dispositivo. Solo se crea una identidad de API para AD Sync si el proceso de sincronización previsto la requiere, y se le asigna exclusivamente el rol Service Principal Directory Sync.
Requisitos y responsabilidad
Solo un Super Admin puede crear y administrar API Credentials. La aplicación se autentica con su propia Client ID y su propio Client Secret, no con la cuenta personal del administrador.
Antes de crearla se documentan el propósito, el propietario, el sistema de destino, el rol necesario, la fecha de vencimiento y el contacto de emergencia. Se utiliza una credencial propia para cada aplicación y entorno. Un secreto compartido para el script de copia de seguridad, el SIEM y proveedores externos impide un bloqueo selectivo y dificulta el análisis de la causa.
Elegir el rol de Service Principal adecuado
Sophos ofrece varios roles:
- Service Principal Read-Only lee datos del tenant, pero no puede modificarlos ni ejecutar consultas de Live Discover.
- Service Principal Management puede consultar, crear, modificar y eliminar usuarios y grupos de usuarios; consultar y editar alertas; consultar endpoints y activar acciones como un análisis; además de ver y modificar configuraciones globales de Endpoint Protection. También administra administradores, roles y Security Policies, pero no tiene acceso a consultas de Live Discover.
- Service Principal Forensics crea, visualiza, ejecuta y elimina consultas de Live Discover.
- Service Principal Directory Sync está previsto exclusivamente para la sincronización de Active Directory y no puede ejecutar ninguna otra tarea de API.
- Service Principal Firewall limita la identidad a la administración del firewall y no permite tareas de la API de Central fuera de ella.
- Service Principal Audit Log permite que aplicaciones externas, herramientas SIEM y scripts de integración recuperen eventos del Audit Log mediante consultas de solo lectura.
- Service Principal Super Admin posee amplios permisos de lectura, escritura y eliminación, además de acceso a consultas.
La selección siempre comienza por el rol más limitado. Una integración de reporting o de ciberseguro recibe Read-Only. AD Sync recibe el rol creado específicamente para ello. Super Admin solo se utiliza si los endpoints de API documentados necesitan realmente amplios permisos de escritura y no funciona ningún rol más restringido.
Crear una credencial
Inicie sesión en fusion.sophos.com y abra Global Settings > Access Control > API Credentials. En el primer acceso deben aceptarse las condiciones de uso.
- Abrir Add Credential.
- Registrar un nombre inequívoco y una descripción con la aplicación, el entorno y el propietario.
- Seleccionar el rol de Service Principal mínimo necesario.
- Crear la credencial y copiar inmediatamente la Client ID y el Client Secret.
- Guardar el secreto en un almacén empresarial de secretos y vaciar el portapapeles temporal.
El Client Secret solo se muestra una vez. No se puede volver a visualizar más adelante. Si se pierde, no se recupera el secreto existente; se crea una credencial nueva y se elimina la antigua después de completar correctamente la migración.
Contrato de API, autenticación y región
El contrato común usa POST https://id.sophos.com/api/v2/oauth2/token para OAuth2 y GET https://api.central.sophos.com/whoami/v1 para identificar la credencial. Las credenciales Partner y Enterprise consultan después GET https://api.central.sophos.com/partner/v1/tenants y GET https://api.central.sophos.com/organization/v1/tenants, respectivamente. Para la API de producto solo se usa el host HTTPS devuelto en apiHosts.dataRegion o apiHost; nunca se deduce la región.
Solicitar un token de acceso de forma segura
read -r -p "Client ID: " SOPHOS_CLIENT_ID
read -r -s -p "Client Secret: " SOPHOS_CLIENT_SECRET; printf '\n'
TOKEN_RESPONSE=$(printf 'grant_type=client_credentials&client_id=%s&client_secret=%s&scope=token' \
"$(jq -rn --arg v "$SOPHOS_CLIENT_ID" '$v|@uri')" \
"$(jq -rn --arg v "$SOPHOS_CLIENT_SECRET" '$v|@uri')" |
curl --fail-with-body --silent --show-error --request POST \
--header 'Content-Type: application/x-www-form-urlencoded' --data-binary @- \
https://id.sophos.com/api/v2/oauth2/token)
unset SOPHOS_CLIENT_SECRET
SOPHOS_ACCESS_TOKEN=$(jq -er '
select(.token_type == "bearer") |
select((.expires_in | type) == "number" and .expires_in > 0) |
.access_token | select(type == "string" and length > 0)
' <<<"$TOKEN_RESPONSE")
unset TOKEN_RESPONSE
WHOAMI=$(printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
curl --fail-with-body --silent --show-error --config - \
https://api.central.sophos.com/whoami/v1
)
Una respuesta correcta contiene access_token, token_type: "bearer" y un expires_in numérico y positivo. Puede incluir también refresh_token, errorCode, message y trackingId. No se registra la respuesta; al caducar se solicita un token nuevo.
Evaluar whoami
El contrato de respuesta whoami para un tenant y la resolución de otros tipos son:
{
"id": "<tenant-uuid>",
"idType": "tenant",
"apiHosts": {
"global": "https://api.central.sophos.com",
"dataRegion": "https://api-us03.central.sophos.com"
}
}
SOPHOS_ID=$(jq -er '.id | select(type == "string" and length > 0)' <<<"$WHOAMI")
SOPHOS_ID_TYPE=$(jq -er '.idType | select(. == "tenant" or . == "partner" or . == "organization")' <<<"$WHOAMI")
UUID_RE='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$'
if [[ "$SOPHOS_ID_TYPE" == tenant ]]; then
SOPHOS_TENANT_ID=$(jq -er --arg re "$UUID_RE" '.id | select(type == "string" and test($re))' <<<"$WHOAMI")
SOPHOS_API_HOST=$(jq -er '.apiHosts.dataRegion | select(type == "string" and test("^https://api-[a-z0-9-]+\\.central\\.sophos\\.com$"))' <<<"$WHOAMI")
else
case "$SOPHOS_ID_TYPE" in
partner) TENANTS_URL='https://api.central.sophos.com/partner/v1/tenants'; CONTEXT_HEADER="X-Partner-ID: ${SOPHOS_ID}" ;;
organization) TENANTS_URL='https://api.central.sophos.com/organization/v1/tenants'; CONTEXT_HEADER="X-Organization-ID: ${SOPHOS_ID}" ;;
*) exit 1 ;;
esac
TENANTS_FILE=$(mktemp); printf '[]\n' >"$TENANTS_FILE"
page=1; max_pages=1000; expected_pages=
while (( page <= max_pages )); do
PAGE_RESPONSE=$(printf 'header = "Authorization: Bearer %s"\n' "$SOPHOS_ACCESS_TOKEN" |
curl --fail-with-body --silent --show-error --get --config - \
--header "$CONTEXT_HEADER" --data-urlencode "page=${page}" \
--data-urlencode 'pageSize=100' --data-urlencode 'pageTotal=true' "$TENANTS_URL")
page_total=$(jq -er 'select((.items|type)=="array") | .pages.total | select(type=="number" and floor==. and .>=1 and .<=1000)' <<<"$PAGE_RESPONSE")
if [[ -z "$expected_pages" ]]; then expected_pages=$page_total; fi
[[ "$page_total" == "$expected_pages" ]] || exit 1
jq -e --argjson page "$PAGE_RESPONSE" '. + $page.items' "$TENANTS_FILE" >"${TENANTS_FILE}.new"
mv "${TENANTS_FILE}.new" "$TENANTS_FILE"
(( page >= expected_pages )) && break
((page++))
done
(( page == expected_pages )) || exit 1
read -r -p 'UUID del tenant de destino según la asignación aprobada: ' TARGET_TENANT_ID
TARGET_TENANT=$(jq -cer --arg id "$TARGET_TENANT_ID" --arg re "$UUID_RE" '[.[] | select((.id|type)=="string" and (.id|test($re)) and (.id|ascii_downcase)==($id|ascii_downcase)) | select((.apiHost|type)=="string" and (.apiHost|test("^https://api-[a-z0-9-]+\\.central\\.sophos\\.com$")))] | select(length==1) | .[0]' "$TENANTS_FILE")
SOPHOS_TENANT_ID=$(jq -r '.id' <<<"$TARGET_TENANT")
SOPHOS_API_HOST=$(jq -r '.apiHost' <<<"$TARGET_TENANT")
rm -f "$TENANTS_FILE"
fi
export SOPHOS_TENANT_ID SOPHOS_API_HOST
Cada solicitud de producto del tenant acopla exactamente Authorization: Bearer <token-de-acceso>, X-Tenant-ID: <uuid-del-tenant> y el apiHost regional de ese mismo tenant. El host global no sustituye a una API de producto regional.
whoami devuelve id, idType y apiHosts. Para Partner o Enterprise, el ID no es un Tenant ID: el bucle exige los encabezados de autorización y contexto, limita el recorrido a 1000 páginas, sigue el valor real pages.total y solo exporta una coincidencia UUID única cuyo apiHost regional sea válido.
Validación y recuperación controlada
Antes de escribir, verificar idType, UUID, formato HTTPS del host, JSON, paginación y objetos esperados mediante una lectura inocua. scope=token no concede permisos funcionales: también mandan rol, acceso al tenant, licencia y operación. Para 400, revisar formulario; 401, credencial/caducidad/secreto; 403, rol y acceso; 404, host/versión/ruta; 429, Retry-After y Backoff; 5xx, Request ID o trackingId y reintentos limitados. Nunca enviar Token ni secreto al soporte.
Si tenant u host son incorrectos, detener las escrituras y aislar los datos recibidos. Eliminar la credencial bloquea futuras llamadas, pero no revierte cambios: aplicar el Rollback específico preparado. Terminar con unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI.
unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE
unset SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI
Resolver problemas del acceso común a la API
Para 400, revisar formulario y campos; 401, credencial, caducidad, secreto, token y sintaxis Bearer; 403, rol, acceso al tenant y operación; 404, host global o regional, versión y ruta; 429, respetar Retry-After y reintentar de forma limitada con backoff y jitter; 5xx, conservar Request ID o trackingId y reintentar dentro de un límite. Ante un idType inesperado o un apiHost ausente, no construir encabezados de tenant. Nunca enviar token ni secreto al soporte.
Probar la autenticación de forma controlada
La primera prueba no consiste en una acción de escritura productiva. Primero se obtiene un OAuth Access Token mediante el endpoint de identidad de Sophos. Después, el endpoint whoami devuelve el Tenant ID, el host de API y el tipo de datos de la cuenta. Solo entonces se realiza una llamada de lectura no peligrosa al host de API proporcionado para el tenant.
El host de API no se copia de un ejemplo. Sophos opera varias regiones de datos, por lo que debe utilizarse la URL proporcionada por whoami. El Tenant ID y el Organization ID tampoco son intercambiables.
Para la prueba se documentan, como mínimo, estos casos:
- La autenticación con la nueva identidad funciona.
- Se devuelve el tenant esperado.
- Las operaciones de lectura permitidas funcionan.
- Una operación no permitida se rechaza con
403 Forbidden. - El sistema de destino registra la prueba de forma trazable sin guardar el Client Secret.
Gestionar el vencimiento y la rotación
Sophos no envía ninguna advertencia cuando caduca una API Credential. Tras el vencimiento ya no puede utilizarse para autenticarse y Sophos Fusion la elimina automáticamente. Por tanto, la supervisión debe realizarse fuera de Sophos Fusion.
Un procedimiento de rotación correcto utiliza un solapamiento breve:
- Crear una nueva credencial con un rol idéntico o más restringido.
- Cambiar la aplicación a la Client ID y el secreto de la nueva credencial.
- Probar la autenticación y la función técnica.
- Eliminar la credencial antigua.
- Revisar el cambio en el registro de secretos y la documentación operativa.
La credencial antigua no permanece activa durante meses por precaución. Si una aplicación solo admite un juego de secretos, se planifica una ventana de mantenimiento.
Sustituir los antiguos tokens de la API SIEM
API Token Management es el método de autenticación anterior para la SIEM Integration API. Sophos ya no emite allí tokens nuevos ni prolonga la vigencia de los existentes. Los tokens actuales solo funcionan hasta su vencimiento.
Por eso no se deja hasta el último día una integración que todavía los utilice. Se registran en un inventario el token, el sistema de destino, la fecha de vencimiento y los endpoints utilizados; se crea una API Credential adecuada, se migra la aplicación y se comprueba el flujo de datos completo. El token antiguo solo se elimina después de una comprobación paralela satisfactoria.
El cambio de un token heredado a API Credentials no es un simple cambio de nombre. La integración debe ser compatible con la autenticación OAuth, whoami, el host regional y el modelo de roles. Por eso, un conector SIEM se configura conforme a las instrucciones actuales de su fabricante, no con un ejemplo antiguo basado en tokens.
Proveedores externos y acceso de terceros
Para una entidad externa se crea una identidad Service Principal Read-Only propia si bastan permisos de lectura. La Client ID y el secreto se transmiten por un canal independiente y cifrado. Se fija una fecha de finalización para el acceso y se elimina al terminar el proyecto.
Este acceso de terceros puede leer mediante la API, en particular, Alerts and Events, resultados del Account Health Check, detalles de dispositivos y configuraciones de políticas. Read-Only impide añadir, modificar y eliminar contenido en Sophos Fusion, pero no limita automáticamente qué datos legibles consulta o almacena realmente la plataforma externa. Por eso, antes de habilitar el acceso se acuerdan contractualmente el alcance de los datos, su finalidad, el lugar de almacenamiento, la retención y la eliminación.
La creación sigue la ruta habitual Global Settings > Access Control > API Credentials > Add Credential. En el primer acceso se aceptan las condiciones de uso y protección de datos, se elige Service Principal Read-Only como rol y se copian de inmediato y de forma segura la Client ID y el Client Secret, que solo se muestra una vez. La transmisión se realiza por un canal cifrado autorizado, por ejemplo, el portal HTTPS del proveedor, no por correo electrónico ni en el texto de un ticket.
El host de API no se copia de una tabla regional estática. La aplicación determina mediante whoami el host de API válido para ese tenant concreto. De este modo, la integración sigue correctamente documentada aunque Sophos cambie regiones o endpoints. En cuanto el proveedor externo deje de necesitar acceso, se elimina la credencial; así se revoca de inmediato el permiso de API.
No es aceptable exportar la cuenta personal de Super Admin, utilizar una identidad de API compartida para varios clientes ni incluir un secreto en un ticket de soporte. El proveedor también debe indicar dónde se almacena el secreto, cómo se protege y cuándo se elimina.
Delimitar los errores de forma específica
401 Unauthorized
Por lo general, la Client ID, el secreto, el endpoint de token o la solicitud OAuth son incorrectos. Una credencial caducada y ya eliminada también produce este error. Primero se comprueba si la credencial sigue existiendo en Sophos Fusion y si la aplicación utiliza realmente el juego de secretos más reciente.
403 Forbidden
La autenticación se ha realizado correctamente, pero el rol no permite la acción. En lugar de asignar inmediatamente Super Admin, se relaciona el endpoint de API necesario con el rol de Service Principal apropiado.
Token correcto, región de datos incorrecta
El Access Token por sí solo no determina el host de API funcional. La aplicación debe utilizar el host regional proporcionado por whoami. Un host fijo de otra región provoca errores o consultas contra el límite de plataforma equivocado.
La integración falla sin advertencia
Si Sophos Fusion no muestra ninguna alerta abierta, se comprueban en el sistema de destino la fecha de vencimiento, la última llamada de API correcta y la versión del secreto. La supervisión del vencimiento forma parte del monitoring externo.
Revisión periódica
Al menos cada trimestre se revisan el nombre, el propietario, el rol, el último uso, el vencimiento y el sistema de destino de cada credencial. Las identidades que no puedan asignarse o no se utilicen se eliminan. Si se sospecha que un secreto se ha filtrado, la credencial afectada se elimina inmediatamente y se sustituye por una nueva. Después se examinan los registros del sistema de destino y de la integración en busca de llamadas de API inusuales.
Los permisos personales de administrador se revisan por separado conforme a Asignar correctamente los roles de administración de Sophos Fusion. Las API Credentials no sustituyen ni MFA ni un acceso de administrador personal y trazable.