Sophos Central API-Zugangsdaten sicher verwalten

Sophos Fusion (ehemals Sophos Central) lässt sich über APIs automatisieren und an SIEM-, RMM-, Reporting- oder Versicherungsplattformen anbinden. Dafür werden keine persönlichen Administratorkonten verwendet, sondern eigene API Credentials aus Client ID und Client Secret.

Diese Zugangsdaten sind Maschinenidentitäten. Wer ein Secret besitzt, kann alle API-Aktionen ausführen, welche die zugewiesene Service-Principal-Rolle erlaubt. Ein Secret gehört deshalb wie ein privilegiertes Kennwort behandelt und darf weder in Skripten, Tickets, E-Mails noch in Git-Repositories landen.

API Credentials und Integration Credential Manager unterscheiden

Unter Global Settings > Access Control gibt es zwei ähnlich klingende Bereiche:

Für ein eigenes Skript, eine SIEM-Abfrage oder einen API-Client werden API Credentials erstellt. Zugangsdaten eines Drittprodukts, die Sophos Fusion selbst benutzen soll, gehören dagegen in den Integration Credential Manager.

Nicht jede Automatisierung benötigt allgemeine API Credentials: Benutzer und Gruppen werden über einen Verzeichnisdienst synchronisiert, Software kann per lokal ausgeführtem Installer-Skript verteilt werden. Für AD Sync wird nur dann eine API-Identität angelegt, wenn der vorgesehene Synchronisationsablauf sie verlangt; sie erhält ausschliesslich die Rolle Service Principal Directory Sync.

Voraussetzungen und Verantwortlichkeit

Nur ein Super Admin kann API Credentials erstellen und verwalten. Die spätere Anwendung authentifiziert sich mit ihrer eigenen Client ID und ihrem eigenen Client Secret, nicht mit dem persönlichen Administratorkonto.

Vor der Erstellung werden Zweck, Eigentümer, Zielsystem, benötigte Rolle, Ablauftermin und Notfallkontakt dokumentiert. Pro Anwendung und Umgebung wird ein eigenes Credential verwendet. Ein gemeinsames Secret für Backup-Skript, SIEM und externe Dienstleister verhindert eine gezielte Sperrung und erschwert die Ursachenanalyse.

Passende Service-Principal-Rolle wählen

Sophos stellt mehrere Rollen bereit:

• Service Principal Read-Only liest Tenant-Daten, darf sie aber nicht verändern und keine Live-Discover-Abfragen ausführen.
• Service Principal Management kann Benutzer und Benutzergruppen abfragen, erstellen, ändern und löschen, Alerts abfragen und bearbeiten, Endpoints abfragen und Aktionen wie einen Scan auslösen sowie globale Endpoint-Protection-Einstellungen ansehen und ändern. Zusätzlich verwaltet die Rolle Administratoren, Rollen und Security Policies, hat aber keinen Live-Discover-Query-Zugriff.
• Service Principal Forensics erstellt, zeigt, startet und löscht Live-Discover-Abfragen.
• Service Principal Directory Sync ist ausschliesslich für die Active-Directory-Synchronisation vorgesehen und darf keine anderen API-Aufgaben ausführen.
• Service Principal Firewall beschränkt die Identität auf die Firewall-Verwaltung und darf ausserhalb davon keine Central-API-Aufgaben ausführen.
• Service Principal Audit Log erlaubt externen Anwendungen, SIEM-Systemen und Integrationsskripten, Audit-Log-Ereignisse mit schreibgeschütztem Abfragezugriff abzurufen.
• Service Principal Super Admin besitzt umfassende Lese-, Schreib- und Löschrechte sowie Query-Zugriff.

Die Auswahl beginnt immer bei der kleinsten Rolle. Eine Reporting- oder Cyber-Versicherungs-Integration erhält Read-Only. AD Sync erhält die eigens dafür vorgesehene Rolle. Super Admin wird nur eingesetzt, wenn dokumentierte API-Endpunkte tatsächlich umfassende Schreibrechte benötigen und keine engere Rolle funktioniert.

Credential erstellen

Unter fusion.sophos.com anmelden und Global Settings > Access Control > API Credentials öffnen. Beim ersten Aufruf müssen die Nutzungsbedingungen bestätigt werden.

1. Add Credential öffnen.
2. Einen eindeutigen Namen und eine Beschreibung mit Anwendung, Umgebung und Eigentümer erfassen.
3. Die minimal benötigte Service-Principal-Rolle auswählen.
4. Credential erstellen und Client ID sowie Client Secret unmittelbar übernehmen.
5. Secret in einem Unternehmens-Secret-Store ablegen und den temporären Zwischenspeicher leeren.

Das Client Secret wird nur einmal angezeigt. Es lässt sich später nicht erneut einblenden. Ist es verloren, wird kein bestehendes Secret wiederhergestellt, sondern ein neues Credential erstellt und das alte nach erfolgreicher Umstellung gelöscht.

API-Vertrag: Token, Identität und Datenregion

Für alle Sophos-Central-APIs gilt derselbe Einstieg. Der globale Identity-Host stellt das OAuth-Token aus; der globale whoami-Host identifiziert das Credential. Fachliche Tenant-Aufrufe gehen danach ausschliesslich an den für diesen Tenant gelieferten regionalen Host. Folgende HTTPS-Ziele müssen aus der Admin-Workstation beziehungsweise dem Integrationssystem erreichbar sein:

• POST https://id.sophos.com/api/v2/oauth2/token für OAuth2;
• GET https://api.central.sophos.com/whoami/v1 für Identität und Host-Ermittlung;
• bei Partner-Credentials GET https://api.central.sophos.com/partner/v1/tenants;
• bei Enterprise-Credentials GET https://api.central.sophos.com/organization/v1/tenants;
• der in apiHosts.dataRegion oder im Tenant-Feld apiHost zurückgegebene HTTPS-Host für die eigentliche Produkt-API.

Keine regionale URL raten oder aus einer statischen Tabelle übernehmen. Nur den vollständig gelieferten HTTPS-Host akzeptieren; Pfade aus einer API-Dokumentation werden erst danach angehängt.

Access-Token sicher anfordern

Das Secret verdeckt einlesen und als Formulardaten über die Standardeingabe senden. Damit landet es weder in der Shell-History noch als expandiertes Argument in der Prozessliste:

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

Eine erfolgreiche Antwort enthält mindestens access_token, token_type: "bearer" und expires_in; zusätzlich können refresh_token, errorCode, message und trackingId vorkommen. expires_in ist die Gültigkeitsdauer in Sekunden. Für den Client-Credentials-Flow bei Ablauf ein neues Access-Token anfordern, statt sich auf das optionale refresh_token zu verlassen. Die Antwort niemals protokollieren, weil beide Tokenfelder Secrets sind.

whoami auswerten

Den Bearer-Header über die Standardeingabe von curl übergeben und nur die nicht geheimen Discovery-Felder speichern:

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
)

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")

Eine Tenant-Antwort hat diesen Vertrag; Platzhalter sind keine produktiven Werte:

{
  "id": "<tenant-uuid>",
  "idType": "tenant",
  "apiHosts": {
    "global": "https://api.central.sophos.com",
    "dataRegion": "https://api-us03.central.sophos.com"
  }
}

Bei idType: "tenant" werden Tenant-UUID und Host streng geprüft und übernommen:

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}$'
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")

Bei idType: "partner" oder "organization" enthält whoami normalerweise nur apiHosts.global. Dann ist SOPHOS_ID keine Tenant-ID. Die folgende begrenzte Schleife liest die Liste mit dem erforderlichen Kontext-Header und folgt dem dokumentierten Wert pages.total. Jedes Tenant-Objekt liefert seine eigene id und sein eigenes apiHost. Das Ziel anhand einer UUID aus einer vertrauenswürdigen internen Zuordnung auswählen, nie nur anhand eines ähnlichen Anzeigenamens.

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}"
    ;;
  *) printf 'Diese Liste gilt nur für Partner- oder Organisations-Credentials.\n' >&2; 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" ]] || { printf 'Pagination hat sich während des Abrufs geändert.\n' >&2; 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 )) || { printf 'Tenant-Pagination überschreitet die Begrenzung.\n' >&2; exit 1; }
unset PAGE_RESPONSE

read -r -p 'Ziel-Tenant-UUID aus der freigegebenen Zuordnung: ' 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")
export SOPHOS_TENANT_ID SOPHOS_API_HOST
rm -f "$TENANTS_FILE"
unset TARGET_TENANT TARGET_TENANT_ID TENANTS_FILE TENANTS_URL CONTEXT_HEADER
unset page page_total expected_pages max_pages

Für jeden fachlichen Tenant-Request sind danach genau drei Werte gekoppelt: Authorization: Bearer <Access-Token>, X-Tenant-ID: <Tenant-UUID> und der zu diesem Tenant gehörende regionale apiHost. Den globalen Host nicht als Ersatz für eine regionale Produkt-API verwenden. scope=token autorisiert keine Fachoperation; Rolle, Tenant-Zugriff, Lizenz und der konkrete Endpoint entscheiden zusätzlich.

Validierung und kontrollierter Rückbau

Vor einer Schreiboperation einen harmlosen Lese-Endpoint der Ziel-API aufrufen und prüfen: erwarteter idType, richtige Tenant-UUID, erlaubtes Hostformat, valides JSON, vollständige Pagination und erwartete Objekte. Danach einen ausdrücklich nicht erlaubten Testfall mit 403 bestätigen, ohne eine produktive Änderung zu provozieren. Access-Token, Tenant-ID und Host am Sessionende entfernen:

unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE
unset SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI

Bei falschem Tenant oder Host den Lauf sofort stoppen, keine Schreibrequests senden und gespeicherte Ergebnisse als potenziell tenantfremde Daten isolieren beziehungsweise nach Vorgabe löschen. Eine bereits erfolgte Fachänderung wird mit dem vorab dokumentierten produktspezifischen Rollback zurückgenommen; das Löschen des Credentials widerruft nur künftige API-Aufrufe und macht keine Änderung rückgängig.

Fehlerdiagnose des gemeinsamen API-Zugangs

• 400: Form-Encoding, Pflichtfelder und genau grant_type=client_credentials sowie scope=token prüfen.
• 401: Credential-Existenz und Ablauf, neuesten Secret-Satz, Token und Bearer-Syntax prüfen; danach einmal neu authentifizieren.
• 403: Identität ist authentifiziert, aber Rolle, Tenant-Freigabe oder operationsspezifische Berechtigung fehlt. Nicht pauschal Super Admin vergeben.
• 404: globalen gegenüber regionalem Host, API-Version und Pfad prüfen; keine Region durch Probieren suchen.
• 429: Retry-After beachten und begrenzt mit Backoff und Jitter wiederholen.
• 5xx: Request-ID beziehungsweise trackingId, Zeitpunkt, Methode und redigierten Pfad sichern und begrenzt wiederholen; nie Secret oder Token in ein Supportticket kopieren.
• Unerwarteter idType oder fehlendes apiHost: keine Tenant-Header konstruieren. Credential-Typ und vollständig paginierte Partner-/Enterprise-Tenantliste prüfen.

Authentifizierung kontrolliert testen

Der erste Test besteht nicht aus einer produktiven Schreibaktion. Zuerst wird über den Sophos-Identity-Endpunkt ein OAuth-Access-Token bezogen. Danach liefert der whoami-Endpunkt Tenant-ID, API-Host und Datentyp des Kontos. Erst dann wird ein ungefährlicher Leseaufruf gegen den für den Tenant gelieferten API-Host ausgeführt.

Ein API-Host wird nicht aus einem Beispiel kopiert. Sophos betreibt mehrere Datenregionen, deshalb muss die von whoami gelieferte URL verwendet werden. Auch Tenant-ID und Organisation-ID sind nicht austauschbar.

Für den Test werden mindestens folgende Fälle dokumentiert:

• Authentifizierung mit der neuen Identität funktioniert.
• Der erwartete Tenant wird zurückgegeben.
• Erlaubte Leseoperationen funktionieren.
• Eine nicht erlaubte Operation wird mit 403 Forbidden abgewiesen.
• Das Zielsystem protokolliert den Test ohne Client Secret nachvollziehbar.

Ablauf und Rotation betreiben

Sophos sendet keine Warnung, wenn ein API Credential abläuft. Nach dem Ablauf kann es nicht mehr zur Authentifizierung verwendet werden und wird automatisch aus Sophos Fusion entfernt. Monitoring muss daher ausserhalb von Sophos Fusion stattfinden.

Ein sauberer Rotationsablauf arbeitet mit kurzer Überlappung:

1. Neues Credential mit identischer oder engerer Rolle erstellen.
2. Anwendung auf Client ID und Secret des neuen Credentials umstellen.
3. Authentifizierung und fachliche Funktion testen.
4. Altes Credential löschen.
5. Änderung in Secret-Register und Betriebsdokumentation prüfen.

Das alte Credential bleibt nicht vorsorglich monatelang aktiv. Wenn eine Anwendung nur einen Secret-Satz unterstützt, wird ein Wartungsfenster geplant.

Alte SIEM-API-Tokens ablösen

API Token Management ist die frühere Authentifizierung für die SIEM Integration API. Sophos stellt dort keine neuen Tokens mehr aus und verlängert bestehende Laufzeiten nicht mehr. Vorhandene Tokens funktionieren nur bis zu ihrem Ablauf.

Eine noch damit arbeitende Integration wird deshalb nicht bis zum letzten Tag belassen. Man inventarisiert Token, Zielsystem, Ablaufdatum und verwendete Endpunkte, erstellt ein passendes API Credential, stellt die Anwendung um und prüft den vollständigen Datenfluss. Erst nach erfolgreicher Parallelkontrolle wird der alte Token entfernt.

Der Wechsel von einem Legacy-Token auf API Credentials ist keine reine Umbenennung. OAuth-Authentifizierung, whoami, Regional-Host und Rollenmodell müssen von der Integration unterstützt werden. Ein SIEM-Connector wird daher anhand seiner aktuellen Herstelleranleitung und nicht mit einem alten Token-Beispiel konfiguriert.

Externe Dienstleister und Drittzugriff

Für eine externe Stelle wird eine eigene Service Principal Read-Only-Identität erstellt, sofern reine Leserechte genügen. Client ID und Secret werden über einen getrennten, verschlüsselten Kanal übertragen. Der Zugriff erhält einen festgehaltenen Endtermin und wird nach Projektende gelöscht.

Ein solcher Drittzugriff kann über die API insbesondere Alerts und Events, Ergebnisse des Account Health Check, Gerätedetails und Policy-Konfigurationen lesen. Read-Only verhindert das Hinzufügen, Ändern und Löschen in Sophos Fusion, begrenzt aber nicht automatisch, welche der lesbaren Daten die Drittplattform tatsächlich abruft oder speichert. Vor der Freigabe werden daher Datenumfang, Verwendungszweck, Speicherort, Aufbewahrung und Löschung vertraglich geklärt.

Die Erstellung folgt dem normalen Pfad Global Settings > Access Control > API Credentials > Add Credential. Beim ersten Aufruf werden die Nutzungs- und Datenschutzbedingungen bestätigt, als Rolle wird Service Principal Read-Only gewählt und Client ID sowie das nur einmal sichtbare Client Secret werden unmittelbar sicher übernommen. Die Übertragung erfolgt über einen freigegebenen verschlüsselten Kanal, beispielsweise das HTTPS-Portal des Anbieters, nicht per E-Mail oder Tickettext.

Der API-Host wird nicht aus einer statischen Regionaltabelle kopiert. Die Anwendung ermittelt über whoami den für genau diesen Tenant gültigen API-Host. Damit bleibt die Integration auch dann korrekt dokumentiert, wenn Sophos Regionen oder Endpunkte ändert. Sobald der Drittanbieter keinen Zugriff mehr benötigt, wird das Credential gelöscht; damit ist die API-Berechtigung unmittelbar widerrufen.

Ein Export des persönlichen Super-Admin-Kontos, eine gemeinsame API-Identität für mehrere Kunden oder ein Secret im Supportticket ist nicht vertretbar. Der Dienstleister muss zudem offenlegen, wo das Secret gespeichert, wie es geschützt und wann es gelöscht wird.

Fehler gezielt eingrenzen

401 Unauthorized

Meist sind Client ID, Secret, Token-Endpunkt oder OAuth-Request falsch. Auch ein abgelaufenes und bereits entferntes Credential führt zu diesem Fehler. Zuerst wird geprüft, ob das Credential in Sophos Fusion noch vorhanden ist und ob die Anwendung wirklich den neuesten Secret-Satz nutzt.

403 Forbidden

Die Authentifizierung war erfolgreich, aber die Rolle erlaubt die Aktion nicht. Statt sofort Super Admin zu vergeben, wird der benötigte API-Endpunkt der passenden Service-Principal-Rolle zugeordnet.

Richtiger Token, falsche Datenregion

Der Zugriffstoken allein bestimmt nicht den fachlichen API-Host. Die Anwendung muss den von whoami gelieferten Regional-Host verwenden. Ein fest eingetragener Host aus einer anderen Region verursacht Fehler oder Abfragen gegen die falsche Plattformgrenze.

Integration fällt ohne Warnung aus

Wenn Sophos Fusion keinen offenen Alert zeigt, werden Ablaufdatum, letzter erfolgreicher API-Aufruf und Secret-Version im Zielsystem geprüft. Ablaufüberwachung gehört in das externe Monitoring.

Regelmässige Kontrolle

Mindestens quartalsweise werden Name, Eigentümer, Rolle, letzter Gebrauch, Ablauf und Zielsystem jedes Credentials geprüft. Nicht zuordenbare oder ungenutzte Identitäten werden gelöscht. Nach einem Verdacht auf Secret-Abfluss wird das betroffene Credential sofort gelöscht und durch ein neues ersetzt. Anschliessend werden die Protokolle des Zielsystems und der Integration auf ungewöhnliche API-Aufrufe untersucht.

Die persönlichen Administratorrechte werden separat nach Sophos Fusion Administrationsrollen richtig zuweisen kontrolliert. API Credentials ersetzen weder MFA noch einen persönlichen, nachvollziehbaren Admin-Zugang.

Häufige Fragen