Bezpieczne zarządzanie danymi uwierzytelniającymi API Sophos Central

Sophos Fusion (dawniej Sophos Central) można automatyzować przez API oraz integrować z platformami SIEM, RMM, raportowania lub ubezpieczeniowymi. Nie używa się do tego osobistych kont administratorów, lecz osobnych API Credentials, składających się z Client ID i Client Secret.

Te dane uwierzytelniające są tożsamościami maszynowymi. Osoba posiadająca Secret może wykonywać wszystkie operacje API dozwolone przez przypisaną rolę Service Principal. Secret należy więc traktować jak uprzywilejowane hasło i nie wolno umieszczać go w skryptach, zgłoszeniach, wiadomościach e-mail ani repozytoriach Git.

Różnica między API Credentials a Integration Credential Manager

W sekcji Global Settings > Access Control znajdują się dwa podobnie brzmiące obszary:

Dla własnego skryptu, zapytania SIEM lub klienta API tworzy się API Credentials. Dane uwierzytelniające produktu zewnętrznego, z których ma korzystać samo Sophos Fusion, należą natomiast do Integration Credential Manager.

Nie każda automatyzacja wymaga ogólnych API Credentials: użytkowników i grupy synchronizuje się przez usługę katalogową, a oprogramowanie można wdrażać za pomocą skryptu instalatora uruchamianego lokalnie na każdym urządzeniu. Tożsamość API dla AD Sync tworzy się tylko wtedy, gdy wymaga jej przewidziany proces synchronizacji, i przypisuje się jej wyłącznie rolę Service Principal Directory Sync.

Wymagania i odpowiedzialność

Tylko Super Admin może tworzyć i zarządzać API Credentials. Aplikacja uwierzytelnia się za pomocą własnych Client ID i Client Secret, a nie osobistego konta administratora.

Przed utworzeniem dokumentuje się cel, właściciela, system docelowy, wymaganą rolę, termin wygaśnięcia i kontakt awaryjny. Dla każdej aplikacji i środowiska używa się osobnego Credential. Wspólny Secret dla skryptu kopii zapasowej, SIEM i zewnętrznego usługodawcy uniemożliwia selektywne zablokowanie i utrudnia analizę przyczyny.

Wybór właściwej roli Service Principal

Sophos udostępnia kilka ról:

• Service Principal Read-Only odczytuje dane Tenanta, ale nie może ich zmieniać ani wykonywać zapytań Live Discover.
• Service Principal Management może odczytywać, tworzyć, zmieniać i usuwać użytkowników oraz grupy użytkowników, odczytywać i edytować Alerts, odczytywać Endpoints i uruchamiać działania, takie jak skanowanie, a także wyświetlać i zmieniać globalne ustawienia Endpoint Protection. Ponadto rola zarządza administratorami, rolami i Security Policies, ale nie ma dostępu do zapytań Live Discover.
• Service Principal Forensics tworzy, wyświetla, uruchamia i usuwa zapytania Live Discover.
• Service Principal Directory Sync jest przeznaczona wyłącznie do synchronizacji Active Directory i nie może wykonywać innych zadań API.
• Service Principal Firewall ogranicza tożsamość do zarządzania Firewallem i nie pozwala wykonywać poza tym innych zadań API Central.
• Service Principal Audit Log umożliwia aplikacjom zewnętrznym, narzędziom SIEM i skryptom integracyjnym pobieranie zdarzeń Audit Log za pomocą zapytań tylko do odczytu.
• Service Principal Super Admin ma szerokie uprawnienia do odczytu, zapisu i usuwania oraz dostęp do zapytań.

Wybór zawsze zaczyna się od najmniejszej roli. Integracja raportowa lub ubezpieczeniowa otrzymuje Read-Only. AD Sync otrzymuje rolę przeznaczoną specjalnie do tego celu. Super Admin stosuje się tylko wtedy, gdy udokumentowane punkty końcowe API rzeczywiście wymagają szerokich uprawnień do zapisu i nie działa żadna węższa rola.

Tworzenie Credential

Zaloguj się w fusion.sophos.com, a następnie otwórz Global Settings > Access Control > API Credentials. Przy pierwszym otwarciu należy zaakceptować warunki użytkowania.

1. Otworzyć Add Credential.
2. Wprowadzić jednoznaczną nazwę i opis zawierający aplikację, środowisko i właściciela.
3. Wybrać minimalną wymaganą rolę Service Principal.
4. Utworzyć Credential i natychmiast przejąć Client ID oraz Client Secret.
5. Zapisać Secret w firmowym Secret Store i wyczyścić tymczasowy schowek.

Client Secret jest wyświetlany tylko raz. Później nie można go ponownie wyświetlić. Jeśli zostanie utracony, nie odzyskuje się istniejącego Secretu, lecz tworzy nowe Credential, a stare usuwa po udanej migracji.

Kontrakt API, uwierzytelnianie i region

Wspólny kontrakt używa POST https://id.sophos.com/api/v2/oauth2/token dla OAuth2 oraz GET https://api.central.sophos.com/whoami/v1 do identyfikacji Credential. Credential Partner i Enterprise odczytują następnie odpowiednio GET https://api.central.sophos.com/partner/v1/tenants i GET https://api.central.sophos.com/organization/v1/tenants. Dla API produktu używa się wyłącznie hosta HTTPS zwróconego w apiHosts.dataRegion lub apiHost; regionu nie wolno zgadywać.

Bezpieczne pobieranie tokenu dostępu

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
)

Prawidłowa odpowiedź zawiera access_token, token_type: "bearer" i dodatnie numeryczne expires_in; może też zawierać refresh_token, errorCode, message i trackingId. Nie wolno jej logować, a po wygaśnięciu trzeba pobrać nowy token.

Ocena whoami

Kontrakt odpowiedzi whoami dla tenantu i rozwiązanie innych typów:

{
  "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 tenantu docelowego z zatwierdzonego mapowania: ' 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

Każde żądanie produktowe tenantu łączy dokładnie Authorization: Bearer <token-dostępu>, X-Tenant-ID: <uuid-tenantu> i regionalny apiHost tego samego tenantu. Host globalny nie zastępuje regionalnego API produktu.

whoami zwraca id, idType i apiHosts. Dla Partner/Enterprise ID nie jest Tenant ID: pętla wymaga nagłówków autoryzacji i kontekstu, ma limit 1000 stron, używa rzeczywistej wartości pages.total i eksportuje tylko jednoznaczne dopasowanie UUID z prawidłowym regionalnym apiHost.

Walidacja i kontrolowane odtwarzanie

Przed zapisem należy nieszkodliwym odczytem sprawdzić idType, UUID, format HTTPS hosta, JSON, paginację i oczekiwane obiekty. scope=token nie nadaje praw produktowych; nadal decydują rola, dostęp do tenantu, licencja i operacja. Przy 400 sprawdzić formularz; 401 Credential/wygaśnięcie/Secret; 403 rolę i dostęp; 404 host/wersję/ścieżkę; 429 Retry-After i Backoff; 5xx Request ID lub trackingId oraz ograniczone ponawianie. Nigdy nie przekazywać Tokenu ani Secretu do pomocy technicznej.

Przy błędnym tenancie lub hoście zatrzymać zapisy i odizolować pobrane dane. Usunięcie Credential blokuje przyszłe wywołania, ale nie cofa zmian: użyć przygotowanego rollbacku produktu i usunąć token, identyfikatory, tenant, host oraz WHOAMI poleceniem unset.

unset SOPHOS_ACCESS_TOKEN SOPHOS_CLIENT_ID SOPHOS_ID SOPHOS_ID_TYPE
unset SOPHOS_TENANT_ID SOPHOS_API_HOST WHOAMI

Rozwiązywanie problemów ze wspólnym dostępem API

Dla 400 sprawdzić formularz i pola; 401 Credential, wygaśnięcie, Secret, token i składnię Bearer; 403 rolę, dostęp do tenantu i operację; 404 host globalny/regionalny, wersję i ścieżkę; 429 respektować Retry-After i ponawiać w ograniczony sposób z backoffem i jitterem; 5xx zachować Request ID lub trackingId i ponawiać w ustalonym limicie. Przy nieoczekiwanym idType albo braku apiHost nie tworzyć nagłówków tenantu. Nigdy nie wysyłać tokenu ani Secretu do pomocy technicznej.

Kontrolowany test uwierzytelniania

Pierwszy test nie powinien polegać na operacji zapisu w środowisku produkcyjnym. Najpierw pobiera się OAuth Access Token z punktu końcowego Sophos Identity. Następnie punkt końcowy whoami zwraca Tenant ID, API Host i typ danych konta. Dopiero wtedy wykonuje się nieszkodliwe wywołanie odczytu do API Host zwróconego dla danego Tenanta.

API Host nie jest kopiowany z przykładu. Sophos obsługuje wiele regionów danych, dlatego trzeba użyć adresu URL zwróconego przez whoami. Tenant ID i Organization ID również nie są zamienne.

W ramach testu dokumentuje się co najmniej następujące przypadki:

• Uwierzytelnianie nową tożsamością działa.
• Zwracany jest oczekiwany Tenant.
• Dozwolone operacje odczytu działają.
• Niedozwolona operacja zostaje odrzucona kodem 403 Forbidden.
• System docelowy rejestruje test w sposób możliwy do prześledzenia, bez zapisywania Client Secret.

Zarządzanie wygaśnięciem i rotacją

Sophos nie wysyła ostrzeżenia o wygaśnięciu API Credential. Po wygaśnięciu nie można go już użyć do uwierzytelniania i zostaje automatycznie usunięte z Sophos Fusion. Monitoring musi więc odbywać się poza Sophos Fusion.

Prawidłowa rotacja wykorzystuje krótkie nakładanie się okresów ważności:

1. Utworzyć nowe Credential z identyczną lub węższą rolą.
2. Przełączyć aplikację na Client ID i Secret nowego Credential.
3. Przetestować uwierzytelnianie i działanie merytoryczne.
4. Usunąć stare Credential.
5. Sprawdzić zmianę w rejestrze sekretów i dokumentacji operacyjnej.

Stare Credential nie pozostaje zapobiegawczo aktywne przez wiele miesięcy. Jeśli aplikacja obsługuje tylko jeden zestaw sekretów, planuje się okno serwisowe.

Zastępowanie starych tokenów API SIEM

API Token Management to wcześniejsza metoda uwierzytelniania dla SIEM Integration API. Sophos nie wydaje już nowych tokenów i nie przedłuża ważności istniejących. Istniejące tokeny działają tylko do wygaśnięcia.

Integracji, która nadal ich używa, nie pozostawia się więc do ostatniego dnia. Należy zinwentaryzować token, system docelowy, datę wygaśnięcia i używane punkty końcowe, utworzyć odpowiednie API Credential, przełączyć aplikację i sprawdzić pełny przepływ danych. Stary token usuwa się dopiero po udanej kontroli równoległej.

Przejście z Legacy Token na API Credentials nie jest zwykłą zmianą nazwy. Integracja musi obsługiwać uwierzytelnianie OAuth, whoami, Regional Host i model ról. Dlatego SIEM Connector konfiguruje się na podstawie aktualnej instrukcji producenta, a nie starego przykładu z tokenem.

Zewnętrzni usługodawcy i dostęp stron trzecich

Dla podmiotu zewnętrznego tworzy się osobną tożsamość Service Principal Read-Only, jeśli wystarczają prawa odczytu. Client ID i Secret przekazuje się oddzielnym, szyfrowanym kanałem. Dostęp otrzymuje udokumentowaną datę końcową i jest usuwany po zakończeniu projektu.

Taki dostęp strony trzeciej może przez API odczytywać w szczególności Alerts and Events, wyniki Account Health Check, szczegóły urządzeń i konfiguracje Policy. Read-Only uniemożliwia dodawanie, zmienianie i usuwanie w Sophos Fusion, ale nie ogranicza automatycznie zakresu danych, które zewnętrzna platforma rzeczywiście pobiera lub przechowuje. Przed udzieleniem dostępu należy więc umownie ustalić zakres danych, cel użycia, miejsce przechowywania, retencję i usuwanie.

Tworzenie odbywa się standardową ścieżką Global Settings > Access Control > API Credentials > Add Credential. Przy pierwszym otwarciu potwierdza się warunki użytkowania i ochrony danych, wybiera rolę Service Principal Read-Only, a następnie natychmiast bezpiecznie przejmuje Client ID oraz widoczny tylko raz Client Secret. Dane przekazuje się zatwierdzonym szyfrowanym kanałem, na przykład portalem HTTPS dostawcy, a nie wiadomością e-mail ani tekstem zgłoszenia.

API Host nie jest kopiowany ze statycznej tabeli regionów. Aplikacja ustala za pomocą whoami API Host właściwy dokładnie dla tego Tenanta. Dzięki temu dokumentacja integracji pozostaje poprawna nawet wtedy, gdy Sophos zmieni regiony lub punkty końcowe. Gdy dostawca zewnętrzny nie potrzebuje już dostępu, Credential zostaje usunięte, co natychmiast odbiera uprawnienie API.

Eksport osobistego konta Super Admin, wspólna tożsamość API dla wielu klientów ani Secret w zgłoszeniu do pomocy technicznej nie są dopuszczalne. Usługodawca musi ponadto ujawnić, gdzie przechowuje Secret, jak go chroni i kiedy go usuwa.

Precyzyjna diagnostyka błędów

401 Unauthorized

Najczęściej błędne są Client ID, Secret, Token Endpoint lub OAuth Request. Ten błąd powoduje również wygasłe i już usunięte Credential. Najpierw sprawdza się, czy Credential nadal istnieje w Sophos Fusion i czy aplikacja rzeczywiście używa najnowszego zestawu sekretów.

403 Forbidden

Uwierzytelnianie powiodło się, ale rola nie pozwala na tę operację. Zamiast od razu nadawać Super Admin, należy przypisać wymagany punkt końcowy API do właściwej roli Service Principal.

Właściwy token, niewłaściwy region danych

Sam Access Token nie określa merytorycznego API Host. Aplikacja musi korzystać z Regional Host zwróconego przez whoami. Host innego regionu wpisany na stałe powoduje błędy albo zapytania do niewłaściwej granicy platformy.

Integracja przestaje działać bez ostrzeżenia

Jeśli Sophos Fusion nie pokazuje otwartego Alert, sprawdza się datę wygaśnięcia, ostatnie udane wywołanie API i wersję Secret w systemie docelowym. Monitorowanie wygaśnięcia należy do zewnętrznego monitoringu.

Regularna kontrola

Co najmniej raz na kwartał sprawdza się nazwę, właściciela, rolę, ostatnie użycie, wygaśnięcie i system docelowy każdego Credential. Tożsamości, których nie można przypisać lub które nie są używane, należy usunąć. W razie podejrzenia wycieku Secret należy natychmiast usunąć dane Credential i zastąpić je nowymi. Następnie analizuje się logi systemu docelowego i integracji pod kątem nietypowych wywołań API.

Osobiste prawa administratorów kontroluje się oddzielnie zgodnie z artykułem Prawidłowe przypisywanie ról administracyjnych Sophos Fusion. API Credentials nie zastępują MFA ani osobistego, identyfikowalnego dostępu administratora.

Często zadawane pytania