Sophos Central API-credentials veilig beheren

Sophos Fusion (voorheen Sophos Central) kan via API’s worden geautomatiseerd en met SIEM-, RMM-, rapportage- of verzekeringsplatforms worden verbonden. Gebruik hiervoor aparte API Credentials met Client ID en Client Secret, niet persoonlijke beheerdersaccounts.

Deze credentials zijn machine-identiteiten. Wie het secret bezit, kan elke door de rol toegestane API-actie uitvoeren. Behandel het als een privileged wachtwoord en plaats het nooit in scripts, tickets, e-mails of Git-repositories.

API Credentials en Integration Credential Manager onderscheiden

Onder Global Settings > Access Control vindt u twee onderdelen met vergelijkbare namen:

Gebruik API Credentials voor eigen scripts, SIEM-query’s en API-clients. Externe productcredentials die Sophos Fusion zelf nodig heeft, horen in Integration Credential Manager.

Niet elke automatisering vereist algemene API Credentials: synchroniseer gebruikers en groepen via een directoryservice en distribueer software met een installerscript dat lokaal op elk apparaat wordt uitgevoerd. Maak alleen een API-identiteit voor AD Sync aan als de beoogde synchronisatieworkflow dit vereist en wijs uitsluitend Service Principal Directory Sync toe.

Vereisten en eigenaarschap

Alleen een Super Admin kan API-credentials aanmaken en beheren. De applicatie authenticeert zich met haar eigen Client ID en Client Secret, niet met het persoonlijke beheerdersaccount.

Documenteer vóór het aanmaken het doel, de eigenaar, het doelsysteem, de vereiste rol, de vervaldatum en het noodcontact. Gebruik voor iedere applicatie en omgeving een afzonderlijke credential. Eén secret delen tussen een back-upscript, SIEM en externe dienstverlener verhindert gerichte intrekking en maakt oorzaakanalyse moeilijk.

De juiste service-principalrol kiezen

• Service Principal Read-Only leest tenantdata, maar wijzigt niets en voert geen Live Discover-query’s uit.
• Service Principal Management kan gebruikers en gebruikersgroepen opvragen, aanmaken, wijzigen en verwijderen; alerts opvragen en behandelen; endpoints opvragen en acties zoals scans starten; en globale Endpoint Protection-instellingen bekijken of wijzigen. De rol beheert ook beheerders, rollen en beveiligingspolicies, maar heeft geen toegang tot Live Discover-query’s.
• Service Principal Forensics maakt, bekijkt, voert uit en verwijdert Live Discover-query’s.
• Service Principal Directory Sync is uitsluitend bedoeld voor Active Directory-synchronisatie en kan geen andere API-taken uitvoeren.
• Service Principal Firewall beperkt de identiteit tot firewallbeheer en voorkomt Central API-taken buiten dit bereik.
• Service Principal Audit Log geeft externe applicaties, SIEM-tools en integratiescripts alleen-lezen querytoegang om Audit Log-events op te halen.
• Service Principal Super Admin heeft brede lees-, schrijf-, verwijder- en queryrechten.

Begin altijd met de smalste rol. Een rapportage- of cyberverzekeringsintegratie krijgt Read-Only. AD Sync krijgt de daarvoor bestemde rol. Gebruik Super Admin alleen wanneer gedocumenteerde API-endpoints werkelijk brede schrijfrechten vereisen en geen smallere rol werkt.

Een credential aanmaken

Meld u aan bij fusion.sophos.com, ga naar Global Settings > Access Control > API Credentials en accepteer bij het eerste gebruik de voorwaarden.

1. Open Add Credential.
2. Voer een unieke naam en beschrijving met applicatie, omgeving en eigenaar in.
3. Selecteer de minimaal vereiste rol.
4. Maak aan en noteer direct Client ID en Client Secret.
5. Bewaar het secret in een bedrijfsbrede secret store en wis tijdelijke kopieën.

Het Client Secret wordt slechts eenmaal getoond en kan later niet opnieuw zichtbaar worden gemaakt. Probeer bij verlies niet het bestaande secret te herstellen. Maak een nieuwe credential, voer een succesvolle omschakeling uit en verwijder daarna de oude.

API-contract, authenticatie en regio

Het volgende proces beschrijft de regionale Sophos Central REST-product-API’s: de globale Identity-host geeft het OAuth-token uit; de globale whoami-host identificeert de credential. Voor REST-productcontracten met regionale routering gaan tenantproductaanroepen daarna naar de voor die tenant ontvangen host. Hiervoor moeten de volgende HTTPS-doelen bereikbaar zijn vanaf het beheerwerkstation of integratiesysteem:

• POST https://id.sophos.com/api/v2/oauth2/token voor OAuth2;
• GET https://api.central.sophos.com/whoami/v1 voor identiteit en hostdetectie;
• GET https://api.central.sophos.com/partner/v1/tenants voor partnercredentials;
• GET https://api.central.sophos.com/organization/v1/tenants voor Enterprise-credentials;
• de HTTPS-host uit apiHosts.dataRegion of het tenantveld apiHost voor de product-API.

Raad geen regionale URL en neem die niet over uit een statische tabel. Accepteer voor dit REST-proces uitsluitend de volledig ontvangen HTTPS-host en voeg pas daarna productpaden toe. De hostcontrole in het script hieronder geldt voor dit contract, niet universeel voor elke Sophos-API.

De Search GraphQL API heeft een eigen doelcontract: JSON-POST naar https://api.taegis.sophos.com/graphql met bearer-token, X-Tenant-ID en X-GraphQL-Schema: default. Gebruik daarvoor niet de regionale REST-host en vervang apiHosts.dataRegion niet globaal. Tokenophaling en tenantkoppeling blijven nodig; verduidelijk rechten en entitlements afzonderlijk voor de specifieke bewerking. De algemene rolbeschrijvingen hierboven bewijzen geen minimale Search GraphQL-rol. Het runbook voor historische Search-QL-query’s behandelt het volledige zoekproces. De hostnaam alleen garandeert geen dataresidentie.

Veilig een toegangstoken aanvragen

Lees het secret verborgen in en verstuur de formuliergegevens via standaardinvoer. Zo belandt het niet in de shellgeschiedenis of als geëxpandeerd argument in de proceslijst:

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' \
  "$(printf '%s' "$SOPHOS_CLIENT_ID" | jq -sRr '@uri')" \
  "$(printf '%s' "$SOPHOS_CLIENT_SECRET" | jq -sRr '@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
)

Een geslaagd antwoord bevat minimaal access_token, token_type: "bearer" en expires_in; ook refresh_token, errorCode, message en trackingId kunnen voorkomen. expires_in is de geldigheidsduur in seconden. Vraag bij de Client Credentials-flow na verval een nieuw access-token aan in plaats van op het optionele refresh_token te vertrouwen. Log het antwoord nooit: beide tokenvelden zijn secrets.

whoami beoordelen

Geef de bearer-header via standaardinvoer door aan curl en bewaar alleen niet-geheime discoveryvelden. De waarden in het tenantantwoordvoorbeeld zijn placeholders, geen productiewaarden.

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

Controleer bij idType: "tenant" UUID en host strikt voordat je ze overneemt. Bij idType: "partner" of "organization" bevat whoami normaal alleen apiHosts.global; SOPHOS_ID is dan geen tenant-ID. De begrensde lus gebruikt de vereiste contextheader en volgt pages.total. Elk tenantobject levert een eigen id en apiHost. Kies het doel via een UUID uit een betrouwbare interne koppeling, nooit alleen op een vergelijkbare weergavenaam.

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 van de doeltenant uit de goedgekeurde toewijzing: ' 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

Elke tenantproductrequest in dit regionale REST-proces koppelt daarna drie waarden: het bearer-token, X-Tenant-ID: <Tenant-UUID> en de regionale apiHost van die tenant. Gebruik de globale host niet als vervanging voor een regionale REST-product-API. Een API-specifieke GraphQL-doelhost staat hiervan los. scope=token autoriseert geen productbewerking; ook rol, tenanttoegang, licentie en het specifieke endpoint zijn bepalend.

Validatie en gecontroleerd herstel

Roep vóór een schrijfbewerking een onschadelijk leesendpoint van de doel-API aan en controleer verwacht idType, juiste tenant-UUID, toegestaan hostformaat, geldig JSON, volledige paginering en verwachte objecten. Bevestig vervolgens een uitdrukkelijk verboden testgeval met 403, zonder een productiewijziging uit te lokken. Verwijder access-token, tenant-ID en host aan het einde van de sessie:

unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE
unset SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI

Stop bij een verkeerde tenant of host onmiddellijk de uitvoering, verstuur geen schrijfrequests en isoleer opgeslagen resultaten als mogelijk tenantvreemde gegevens of verwijder ze volgens de regels. Draai een al uitgevoerde productwijziging terug met de vooraf gedocumenteerde productspecifieke rollback; het verwijderen van de credential trekt alleen toekomstige API-aanroepen in en maakt geen wijziging ongedaan.

Problemen met gemeenschappelijke API-toegang oplossen

• 400: controleer formuliercodering, verplichte velden en exact grant_type=client_credentials en scope=token.
• 401: controleer bestaan en verval van de credential, nieuwste secretset, token en bearer-syntaxis; authenticeer daarna één keer opnieuw.
• 403: de identiteit is geauthenticeerd, maar rol, tenanttoestemming of bewerkingsspecifieke machtiging ontbreekt. Ken niet standaard Super Admin toe.
• 404: controleer globale versus regionale host, API-versie en pad; zoek geen regio door te proberen.
• 429: respecteer Retry-After en herhaal begrensd met backoff en jitter.
• 5xx: bewaar request-ID of trackingId, tijdstip, methode en geredigeerd pad en herhaal begrensd; kopieer nooit een secret of token naar een supportticket.
• Onverwacht idType of ontbrekende apiHost: construeer geen tenantheaders. Controleer credentialtype en de volledig gepagineerde partner-/Enterprise-tenantlijst.

Authenticatie gecontroleerd testen

De eerste test is geen schrijfactie in productie. Haal voor de hier getoonde regionale REST-test eerst een OAuth-access-token op bij het Sophos Identity-endpoint. Het whoami-endpoint levert daarna identiteit, accounttype en bij tenantcredentials de regionale API-host; partner- en organisatiecredentials vereisen de tenantlijst. Voer pas daarna een onschadelijke leesaanroep uit tegen de voor de tenant ontvangen REST-API-host.

Kopieer geen regionale REST-API-host uit een voorbeeld. Gebruik voor dit contract de URL uit whoami of de tenantlijst; voor Search GraphQL geldt de hierboven afgebakende doelhost. Tenant-ID en organisatie-ID zijn evenmin uitwisselbaar.

Documenteer minstens deze testgevallen:

• Authenticatie met de nieuwe identiteit slaagt.
• De verwachte tenant wordt geretourneerd.
• Toegestane leesacties slagen.
• Een verboden actie wordt met 403 Forbidden geweigerd.
• Het doelsysteem registreert de test traceerbaar zonder het Client Secret vast te leggen.

Verval en rotatie beheren

Sophos stuurt geen waarschuwing wanneer een API-credential verloopt. Na expiratie kan deze niet meer authenticeren en wordt ze automatisch uit Sophos Fusion verwijderd. Bewaking van de vervaldatum moet daarom buiten Sophos Fusion plaatsvinden.

Een zorgvuldig rotatieproces houdt de overlap kort:

1. Maak een nieuwe credential met dezelfde of smallere rol.
2. Zet de applicatie over op nieuwe Client ID en secret.
3. Test authenticatie en bedrijfsfunctie.
4. Verwijder de oude credential.
5. Controleer de wijziging in het secretregister en de beheerdocumentatie.

Laat de oude identiteit niet maanden als voorzorg actief. Plan bij één secretset een onderhoudsvenster.

Legacy SIEM API-tokens vervangen

API Token Management is de oude SIEM Integration API-methode. Sophos geeft geen nieuwe tokens uit en verlengt ze niet; bestaande werken tot hun vervaldatum.

Wacht niet tot de laatste dag met de migratie. Inventariseer token, doelsysteem, vervaldatum en endpoints, maak een passende API-credential, migreer de applicatie en controleer de volledige datastroom. Verwijder het oude token pas na een geslaagde parallelle verificatie.

De overstap van een legacy-token naar API-credentials is meer dan een naamswijziging. De integratie moet OAuth-authenticatie, whoami, de regionale host en het rollenmodel ondersteunen. Configureer een SIEM-connector volgens de actuele instructies van de leverancier en niet volgens een oud tokenvoorbeeld.

Externe dienstverleners en toegang van derden

Gebruik voor een externe partij een aparte Service Principal Read-Only-identiteit wanneer leestoegang volstaat. Draag Client ID en secret via een apart, versleuteld kanaal over. Leg een vaste einddatum vast en verwijder de toegang zodra het project eindigt.

Via de API kan deze externe toegang Alerts and Events, resultaten van Account Health Check, apparaatdetails en policyconfiguraties lezen. Read-Only voorkomt dat gegevens in Sophos Fusion worden toegevoegd, gewijzigd of verwijderd, maar beperkt niet welke leesbare gegevens het externe platform ophaalt of opslaat. Leg vóór goedkeuring contractueel de gegevensomvang, het doel, de opslaglocatie, de bewaartermijn en de verwijdering vast.

Het aanmaken verloopt via Global Settings > Access Control > API Credentials > Add Credential. Accepteer bij eerste toegang de gebruiks- en privacyvoorwaarden, selecteer Service Principal Read-Only en beveilig Client ID en het eenmalig getoonde Client Secret onmiddellijk. Draag beide via een goedgekeurd versleuteld kanaal over, bijvoorbeeld het HTTPS-portal van de dienstverlener, en nooit per e-mail of in tickettekst.

Kopieer de API-host niet uit een statische regiotabel. De applicatie moet met whoami de API-host voor precies deze tenant bepalen. Zo blijft de integratie correct wanneer Sophos regio’s of endpoints wijzigt. Verwijder de credential zodra de externe partij geen toegang meer nodig heeft; daarmee wordt de API-autorisatie onmiddellijk ingetrokken.

Een persoonlijk Super Admin-account exporteren, één API-identiteit tussen klanten delen of een secret in een supportticket plaatsen is onacceptabel. De dienstverlener moet bovendien bekendmaken waar het secret wordt opgeslagen, hoe het wordt beschermd en wanneer het wordt verwijderd.

Methodisch problemen oplossen

401 Unauthorized

Meestal zijn Client ID, secret, tokenendpoint of OAuth-verzoek onjuist. Een verlopen en reeds verwijderde credential veroorzaakt dezelfde fout. Controleer eerst of de credential nog in Sophos Fusion bestaat en of de applicatie de nieuwste secretset gebruikt.

403 Forbidden

Authenticatie werkt, maar de rol staat de actie niet toe. Koppel het endpoint aan de passende rol in plaats van direct Super Admin te geven.

Juist token, verkeerde gegevensregio

Het access-token alleen bepaalt de product-API-host niet. Voor een regionaal gerouteerde REST-product-API moet de toepassing de regionale host uit whoami of de tenantlijst gebruiken; Search GraphQL heeft een eigen doelcontract. Een vast ingestelde host uit een andere regio veroorzaakt fouten of query’s over de verkeerde platformgrens.

Integratie valt zonder waarschuwing uit

Controleer wanneer Sophos Fusion geen open Alert toont de vervaldatum, de laatste geslaagde API-request en de secretversie in het doelsysteem. De expiratiebewaking hoort in externe monitoring thuis.

Regelmatige controle

Controleer minstens elk kwartaal de naam, eigenaar, rol, het laatste gebruik, de vervaldatum en het doelsysteem van iedere credential. Verwijder identiteiten die niet kunnen worden toegewezen of niet meer worden gebruikt. Verwijder bij een vermoedelijk gelekt secret de betrokken credential onmiddellijk en vervang deze door een nieuwe. Onderzoek daarna de logs van het doelsysteem en de integratie op ongebruikelijke API-aanroepen.

Beoordeel persoonlijke beheerdersrechten afzonderlijk volgens Sophos Fusion-beheerdersrollen correct toewijzen. API-credentials vervangen noch MFA noch persoonlijke, herleidbare beheerderstoegang.

Veelgestelde vragen