Hantera Sophos Central API-autentiseringsuppgifter säkert

Sophos Fusion (tidigare Sophos Central) kan automatiseras via API:er och anslutas till SIEM-, RMM-, rapporterings- eller försäkringsplattformar. För detta används inte personliga administratörskonton, utan separata API Credentials som består av Client ID och Client Secret.

Dessa autentiseringsuppgifter är maskinidentiteter. Den som har tillgång till ett secret kan utföra alla API-åtgärder som den tilldelade Service Principal-rollen tillåter. Ett secret ska därför hanteras som ett privilegierat lösenord och får inte hamna i skript, ärenden, e-post eller Git-arkiv.

Skilja mellan API Credentials och Integration Credential Manager

Under Global Settings > Access Control finns två områden med liknande namn:

För ett eget skript, en SIEM-fråga eller en API-klient skapas API Credentials. Autentiseringsuppgifter för en tredjepartsprodukt som Sophos Fusion självt ska använda hör i stället hemma i Integration Credential Manager.

Alla automatiseringar kräver inte allmänna API Credentials: användare och grupper synkroniseras via en katalogtjänst och programvara kan distribueras med ett installationsskript som körs lokalt på varje enhet. Skapa bara en API-identitet för AD Sync om det planerade synkroniseringsflödet kräver det och tilldela uteslutande rollen Service Principal Directory Sync.

Förutsättningar och ansvar

Endast en Super Admin kan skapa och hantera API Credentials. Applikationen autentiserar sig med sitt eget Client ID och Client Secret, inte med administratörens personliga konto.

Före skapandet dokumenteras syfte, ägare, målsystem, nödvändig roll, utgångsdatum och nödkontakt. En separat autentiseringsuppgift används för varje applikation och miljö. Ett gemensamt secret för säkerhetskopieringsskript, SIEM och externa tjänsteleverantörer förhindrar riktad spärrning och försvårar orsaksanalysen.

Välja lämplig Service Principal-roll

Sophos tillhandahåller flera roller:

• Service Principal Read-Only läser klientorganisationsdata men får inte ändra dem eller köra Live Discover-frågor.
• Service Principal Management kan läsa, skapa, ändra och ta bort användare och användargrupper, läsa och hantera Alerts, läsa Endpoints och utlösa åtgärder som en genomsökning samt visa och ändra globala inställningar för Endpoint Protection. Rollen hanterar dessutom administratörer, roller och Security Policies, men har ingen åtkomst till Live Discover-frågor.
• Service Principal Forensics skapar, visar, kör och tar bort Live Discover-frågor.
• Service Principal Directory Sync är endast avsedd för Active Directory-synkronisering och får inte utföra andra API-uppgifter.
• Service Principal Firewall begränsar identiteten till Firewall-hantering och tillåter inga Central API-uppgifter utanför detta område.
• Service Principal Audit Log ger externa applikationer, SIEM-verktyg och integrationsskript skrivskyddad frågeåtkomst för att hämta Audit Log-händelser.
• Service Principal Super Admin har omfattande läs-, skriv- och borttagningsbehörigheter samt åtkomst till frågor.

Valet börjar alltid med den minsta rollen. En rapporterings- eller cyberförsäkringsintegration får Read-Only. AD Sync får den särskilt avsedda rollen. Super Admin används endast när dokumenterade API-endpoints faktiskt kräver omfattande skrivbehörigheter och ingen snävare roll fungerar.

Skapa en autentiseringsuppgift

Logga in på fusion.sophos.com och öppna Global Settings > Access Control > API Credentials. Vid första öppningen måste användningsvillkoren godkännas.

1. Öppna Add Credential.
2. Ange ett unikt namn och en beskrivning med applikation, miljö och ägare.
3. Välj den minsta nödvändiga Service Principal-rollen.
4. Skapa autentiseringsuppgiften och kopiera omedelbart Client ID och Client Secret.
5. Spara secret i organisationens secret store och rensa den tillfälliga lagringen.

Client Secret visas endast en gång. Det kan inte visas igen senare. Om det går förlorat återställs inget befintligt secret. I stället skapas en ny autentiseringsuppgift och den gamla tas bort efter en lyckad övergång.

API-kontrakt, autentisering och region

Följande förlopp beskriver de regionala REST-produkt-API:erna för Sophos Central: den globala Identity-värden utfärdar OAuth-token; den globala whoami-värden identifierar autentiseringsuppgiften. För REST-produktkontrakt med regional dirigering går tenantens produktanrop därefter till värden som returnerats för denna tenant. Följande HTTPS-mål måste därför kunna nås från administratörens arbetsstation eller integrationssystemet:

• POST https://id.sophos.com/api/v2/oauth2/token för OAuth2;
• GET https://api.central.sophos.com/whoami/v1 för identitet och värdidentifiering;
• GET https://api.central.sophos.com/partner/v1/tenants för partneruppgifter;
• GET https://api.central.sophos.com/organization/v1/tenants för Enterprise-uppgifter;
• HTTPS-värden från apiHosts.dataRegion eller tenantfältet apiHost för produkt-API:et.

Gissa inte en regional URL och kopiera den inte från en statisk tabell. Godta för detta REST-förlopp endast hela den returnerade HTTPS-värden och lägg till produktsökvägar först därefter. Värdkontrollen i skriptet nedan gäller detta kontrakt, inte universellt varje Sophos-API.

Search GraphQL API har ett eget målkontrakt: JSON-POST till https://api.taegis.sophos.com/graphql med bearer-token, X-Tenant-ID och X-GraphQL-Schema: default. Använd inte den regionala REST-värden och ersätt inte apiHosts.dataRegion globalt. Tokenhämtning och tenantkoppling krävs fortfarande; klarlägg nödvändiga rättigheter och avtalsmässig åtkomst separat för den aktuella operationen. De allmänna rollbeskrivningarna ovan bevisar ingen minsta Search GraphQL-roll. Körinstruktionen för historiska Search-QL-frågor beskriver hela sökförloppet. Enbart värdnamnet garanterar inte dataresidens.

Begär en åtkomsttoken på ett säkert sätt

Läs in hemligheten dolt och skicka formulärdata via standardindata. Då hamnar den varken i skalhistoriken eller som expanderat argument i processlistan:

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
)

Ett lyckat svar innehåller minst access_token, token_type: "bearer" och expires_in; även refresh_token, errorCode, message och trackingId kan förekomma. expires_in är giltighetstiden i sekunder. Begär i Client Credentials-flödet en ny åtkomsttoken när den gamla löper ut i stället för att förlita dig på valfria refresh_token. Logga aldrig svaret: båda tokenfälten är hemligheter.

Utvärdera whoami

Skicka bearer-huvudet till curl via standardindata och spara bara icke-hemliga discoveryfält. Värdena i exemplet på tenantsvar är platshållare, inte produktionsvärden.

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

Vid idType: "tenant" kontrolleras UUID och värd strikt innan de tas över. Vid idType: "partner" eller "organization" innehåller whoami normalt bara apiHosts.global; SOPHOS_ID är då inget tenant-ID. Den begränsade loopen använder nödvändigt kontexthuvud och följer pages.total. Varje tenantobjekt ger eget id och apiHost. Välj målet med ett UUID från en betrodd intern koppling, aldrig enbart efter ett liknande visningsnamn.

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 'Målklientorganisationens UUID från den godkända mappningen: ' 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

Varje produktbegäran för tenanten i detta regionala REST-förlopp kopplar sedan samman tre värden: bearer-token, X-Tenant-ID: <Tenant-UUID> och tenantens regionala apiHost. Använd inte den globala värden som ersättning för ett regionalt REST-produkt-API. En API-specifik GraphQL-målvärd är separat. scope=token auktoriserar ingen produktoperation; roll, tenantåtkomst, licens och aktuell endpoint avgör också.

Validering och kontrollerad återställning

Anropa före skrivning en ofarlig läsendpoint i mål-API:et och kontrollera förväntat idType, rätt tenant-UUID, tillåtet värdformat, giltig JSON, fullständig paginering och förväntade objekt. Bekräfta sedan ett uttryckligen otillåtet testfall med 403 utan att orsaka en produktionsändring. Ta bort åtkomsttoken, tenant-ID och värd vid sessionens slut:

unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE
unset SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI

Stoppa omedelbart körningen vid fel tenant eller värd, skicka inga skrivbegäranden och isolera sparade resultat som potentiellt tillhörande en annan tenant eller radera dem enligt reglerna. Ångra en redan utförd produktändring med den i förväg dokumenterade produktspecifika återställningen; borttagning av autentiseringsuppgiften återkallar bara framtida anrop och ångrar inga ändringar.

Felsök gemensam API-åtkomst

• 400: kontrollera formulärkodning, obligatoriska fält och exakt grant_type=client_credentials samt scope=token.
• 401: kontrollera att uppgiften finns och inte löpt ut, senaste hemlighetsuppsättning, token och bearer-syntax; autentisera sedan en gång till.
• 403: identiteten är autentiserad men roll, tenantåtkomst eller operationsspecifik behörighet saknas. Tilldela inte generellt Super Admin.
• 404: kontrollera global kontra regional värd, API-version och sökväg; sök inte region genom att prova dig fram.
• 429: följ Retry-After och upprepa begränsat med backoff och jitter.
• 5xx: spara begärande-ID eller trackingId, tidpunkt, metod och redigerad sökväg och upprepa begränsat; kopiera aldrig hemlighet eller token till ett supportärende.
• Oväntat idType eller saknad apiHost: skapa inga tenanthuvuden. Kontrollera uppgiftstypen och den fullständigt paginerade partner-/Enterprise-tenantlistan.

Testa autentiseringen kontrollerat

Det första testet är ingen produktionsskrivning. Hämta för det regionala REST-testet här först en OAuth-åtkomsttoken via Sophos Identity-endpointen. Därefter returnerar whoami identitet, kontotyp och för tenantuppgifter den regionala API-värden; partner- och organisationsuppgifter kräver tenantlistan. Gör först sedan ett ofarligt läsanrop till REST-API-värden som returnerats för tenanten.

Kopiera inte en regional REST-API-värd från ett exempel. Använd för detta kontrakt URL:en från whoami eller tenantlistan; för Search GraphQL gäller den separata målvärden ovan. Tenant-ID och organisations-ID är inte heller utbytbara.

Minst följande fall dokumenteras för testet:

• Autentisering med den nya identiteten fungerar.
• Den förväntade klientorganisationen returneras.
• Tillåtna läsåtgärder fungerar.
• En otillåten åtgärd nekas med 403 Forbidden.
• Målsystemet loggar testet på ett spårbart sätt utan att registrera Client Secret.

Hantera utgångsdatum och rotation

Sophos skickar ingen varning när en API-autentiseringsuppgift går ut. Efter utgångsdatumet kan den inte längre användas för autentisering och tas automatiskt bort från Sophos Fusion. Övervakningen måste därför ske utanför Sophos Fusion.

En korrekt rotationsprocess använder en kort överlappning:

1. Skapa en ny autentiseringsuppgift med samma eller en snävare roll.
2. Ställ om applikationen till den nya autentiseringsuppgiftens Client ID och secret.
3. Testa autentisering och verksamhetsfunktion.
4. Ta bort den gamla autentiseringsuppgiften.
5. Kontrollera ändringen i secret-registret och driftdokumentationen.

Den gamla autentiseringsuppgiften lämnas inte aktiv i flera månader för säkerhets skull. Om en applikation bara stöder en uppsättning autentiseringsuppgifter planeras ett underhållsfönster.

Ersätta gamla SIEM API-tokens

API Token Management är den tidigare autentiseringsmetoden för SIEM Integration API. Sophos utfärdar inte längre nya tokens där och förlänger inte heller befintliga giltighetstider. Befintliga tokens fungerar endast fram till sitt utgångsdatum.

En integration som fortfarande använder dem lämnas därför inte orörd till sista dagen. Inventera token, målsystem, utgångsdatum och använda endpoints, skapa en lämplig API-autentiseringsuppgift, ställ om applikationen och kontrollera hela dataflödet. Den gamla token tas bort först efter en lyckad parallellkontroll.

Bytet från en äldre token till API Credentials är inte bara ett namnbyte. OAuth-autentisering, whoami, regional host och rollmodell måste stödjas av integrationen. En SIEM-connector konfigureras därför enligt tillverkarens aktuella instruktioner och inte med ett gammalt token-exempel.

Externa tjänsteleverantörer och tredjepartsåtkomst

För en extern part skapas en separat identitet med rollen Service Principal Read-Only, förutsatt att rena läsbehörigheter räcker. Client ID och secret överförs via en separat, krypterad kanal. Åtkomsten får ett dokumenterat slutdatum och tas bort när projektet är avslutat.

En sådan tredjepartsåtkomst kan via API:et bland annat läsa Alerts and Events, resultat från Account Health Check, enhetsinformation och Policy-konfigurationer. Read-Only förhindrar att något läggs till, ändras eller tas bort i Sophos Fusion, men begränsar inte automatiskt vilka läsbara data tredjepartsplattformen faktiskt hämtar eller lagrar. Före aktiveringen regleras därför datamängd, användningssyfte, lagringsplats, lagringstid och radering i avtal.

Skapandet följer den normala sökvägen Global Settings > Access Control > API Credentials > Add Credential. Vid första öppningen godkänns användnings- och dataskyddsvillkoren, rollen Service Principal Read-Only väljs och Client ID samt det endast en gång synliga Client Secret kopieras omedelbart på ett säkert sätt. Överföringen sker via en godkänd krypterad kanal, till exempel leverantörens HTTPS-portal, inte via e-post eller ärendetext.

API-hosten kopieras inte från en statisk regiontabell. Applikationen hämtar via whoami den API-host som gäller för just denna klientorganisation. Därmed förblir integrationen korrekt dokumenterad även om Sophos ändrar regioner eller endpoints. Så snart tredjepartsleverantören inte längre behöver åtkomst tas autentiseringsuppgiften bort. API-behörigheten återkallas då omedelbart.

En export av det personliga Super Admin-kontot, en gemensam API-identitet för flera kunder eller ett secret i ett supportärende är inte acceptabelt. Tjänsteleverantören måste dessutom redovisa var secret lagras, hur det skyddas och när det raderas.

Felsöka målinriktat

401 Unauthorized

Vanligen är Client ID, secret, token-endpoint eller OAuth-request felaktig. Även en utgången och redan borttagen autentiseringsuppgift leder till detta fel. Kontrollera först om autentiseringsuppgiften fortfarande finns i Sophos Fusion och om applikationen verkligen använder den senaste secret-uppsättningen.

403 Forbidden

Autentiseringen lyckades, men rollen tillåter inte åtgärden. Tilldela inte omedelbart Super Admin. Matcha i stället den nödvändiga API-endpointen mot rätt Service Principal-roll.

Rätt token, fel dataregion

Enbart åtkomsttoken avgör inte produkt-API-värden. För ett regionalt dirigerat REST-produkt-API måste applikationen använda den regionala värden från whoami eller tenantlistan; Search GraphQL har ett eget målkontrakt. En fast angiven värd från en annan region orsakar fel eller frågor mot fel plattformsgräns.

Integrationen slutar fungera utan varning

Om Sophos Fusion inte visar någon aktiv Alert kontrolleras utgångsdatum, senaste lyckade API-anrop och secret-version i målsystemet. Övervakning av utgångsdatum hör hemma i den externa övervakningen.

Regelbunden kontroll

Minst varje kvartal kontrolleras namn, ägare, roll, senaste användning, utgångsdatum och målsystem för varje autentiseringsuppgift. Identiteter som inte kan kopplas till en ägare eller inte används tas bort. Vid misstanke om att ett secret har läckt tas den berörda autentiseringsuppgiften omedelbart bort och ersätts med en ny. Därefter granskas målsystemets och integrationens loggar efter ovanliga API-anrop.

Personliga administratörsbehörigheter kontrolleras separat enligt Tilldela rätt Sophos Fusion-administratörsroller. API Credentials ersätter varken MFA eller personlig, spårbar administratörsåtkomst.

Vanliga frågor