Control API – Protokolle, Prüfung und Nutzung

Verwenden Sie FoxIDs Control API, um Diagnoseprotokolle, Prüfereignisse und Nutzungsdaten abzufragen und die von einer Umgebung ausgegebenen Protokolltypen zu konfigurieren. Diese Ressourcen haben unterschiedliche Zwecke und Zugriffsrechte:

• Protokolle helfen Betreibern bei der Diagnose von Fehlern, Warnungen, Protokollabläufen, Ereignissen und Metriken.
• Audit zeichnet Sicherheits- und Verwaltungsaktionen auf, einschließlich Anmeldeaktivitäten und Control APIErstellungs-, Aktualisierungs- und Löschanfragen.
• Nutzung aggregiert Aktivitäten für Betriebs- und Abrechnungsanalysen.

Bevor Sie diese Vorgänge aufrufen, konfigurieren Sie Control API Authentifizierungs- und Zugriffsrechte. Swagger bleibt die genaue Referenz für alle Abfrageparameter, Enum-Werte, Einstellungen und Antwortschemata:

• Swagger (OpenAPI) JSON
• Swagger UI

Abfragebereich und Endpunkte

FoxIDs bietet drei Abfragebereiche.

Stellen Sie der Basis den Host FoxIDs Control voran, zum Beispiel https://control.foxids.com. Ändern Sie den Host für eine selbstgehostete Bereitstellung. Senden Sie das Zugriffstoken im Authorization: Bearer {access_token}-Header.

Umgebungsabfragen verwenden die Umgebung aus der Route. Tenant-Abfragen können optional eine Umgebung mit trackName auswählen. Bereitstellungsverwaltungsabfragen können eine tenant und eine Umgebung mit tenantName und trackName auswählen. Die Bereitstellungsdiagnoseabfrage kann auch vor tenant und Umgebungsrouting abgelehnte Anforderungen umfassen.

Verwenden Sie die Zugriffsrechte track:log, track:audit oder track:usage, optional eingeschränkt auf eine bestimmte Umgebung. Für die bereitstellungsweite Prüfung und Nutzung sind die entsprechenden master-Zugriffsrechte erforderlich. Siehe die vollständigen Zugriffsrechtetabellen.

Diagnoseprotokolle abfragen

Eine Diagnoseprotokollanforderung gibt fromTime und toTime als Unix-Zeit in Sekunden an. Eine einzelne Anfrage kann höchstens 24 Stunden umfassen. Wählen Sie eine oder mehrere Kategorien wie Fehler, Warnungen, Ablaufverfolgungen, Ereignisse und Metriken aus und verwenden Sie filter für die Freitextfilterung.

Eine Antwort enthält bis zu 300 der neuesten übereinstimmenden Einträge. Überprüfen Sie responseTruncated; Wenn es true ist, grenzen Sie den Zeitbereich ein oder filtern und fragen Sie erneut ab, anstatt davon auszugehen, dass das Ergebnis vollständig ist.

Application Insights unterstützt die gemeinsame Abfrage von Ablaufverfolgungen und Ereignissen durch diesen Vorgang nicht. Senden Sie separate Anfragen, wenn beide Kategorien erforderlich sind. Halten Sie die Zeitbereiche so eng wie möglich, um die Abfrageleistung zu verbessern und die Menge der zurückgegebenen sensiblen Daten zu reduzieren.

Die Abfrageendpunkte erfordern ein durchsuchbares primäres Protokoll-Repository. Sie können keine Protokolle abrufen, wenn die primäre Protokollausgabe der Bereitstellung die Standardausgabe (Stdout) ist. Fragen Sie in dieser Konfiguration stattdessen das Container- oder Host-Protokollierungssystem der Plattform ab. FoxIDs unterstützt Kontrollabfragen für konfigurierte Application Insights- und OpenSearch-Repositorys.

Audit-Ereignisse abfragen

Eine Prüfanforderung gibt fromTime und toTime als Unix-Zeit in Sekunden an und kann höchstens sieben Tage umfassen. toTime muss gleich oder größer als fromTime sein. Das optionale filter führt eine allgemeine Freitextsuche über Audit-Felder und die Ereignisdaten durch.

Eine Antwort enthält bis zu 300 der neuesten passenden Prüfereignisse. Aktivieren Sie responseTruncated und teilen oder grenzen Sie die Abfrage ein, wenn ein vollständiges Ergebnis erforderlich ist.

Zu den Prüfereignissen gehören benutzerseitige Authentifizierungsaktivitäten und administrative Änderungen. Control API POST-, PUT- und DELETE-Aktionen werden automatisch geprüft, schreibgeschützte GET-Anfragen dagegen nicht. Ein Prüfereignis kann nützliche Korrelationswerte wie tenant, Umgebung, Authentifizierungsmethode, Anwendung, Benutzer, Sitzung, Client-IP und Benutzeragent enthalten, wenn diese Werte für die Aktion verfügbar sind.

Die Prüfung soll zeigen, welche Aktion stattgefunden hat und in welchem ​​Kontext sie steht. Es handelt sich nicht um eine transaktionale Ereigniswarteschlange und sollte nicht als alleiniger Auslöser für eine geschäftskritische Synchronisierung verwendet werden. Suchergebnisse hängen auch vom konfigurierten Protokoll-Repository und der Aufbewahrung ab.

Abfragenutzung

Nutzungsanfragen wählen einen Zeitbereich, einen UTC-Offset und eine Zusammenfassungsebene aus. Include-Flags bestimmen, ob die Antwort tenants, Umgebungen, Authentifizierungsmethoden, Benutzer, Anmeldungen, Token-Anfragen, zusätzliche Nutzung und Control API-Aktivität enthält.

Wählen Sie den engsten Umfang und nur die vom Verbraucher benötigten Abmessungen. Dadurch werden die Antworten kleiner und es wird vermieden, dass tenant oder Benutzerdetails unnötig offengelegt werden. Verwenden Sie Swagger für den aktuellen Zeitrahmen und die Zusammenfassungswerte.

Konfigurieren Sie die Umgebungsprotokollierung

Die Konfiguration des Umgebungsprotokolls verwendet Folgendes:

Die Einstellungen steuern Informationsverfolgungen, Anspruchsverfolgungen, Nachrichtenverfolgungen und Metriken. Fehler, Warnungen, kritische Fehler und Ereignisse bleiben unabhängig voneinander verfügbar, wie in Protokollierung beschrieben. POST ersetzt die komplette Einstellungsressource; Rufen Sie die aktuelle Ressource ab, behalten Sie unveränderte Eigenschaften bei und speichern Sie dann die vollständige Darstellung.

Ein Protokollstream leitet ausgewählte Kategorien unabhängig vom primären Protokoll-Repository an ein externes Ziel weiter. Dies kann verwendet werden, um einen kontrollierten Satz von Umgebungsprotokollen an eine separate Application Insights-Ressource zu senden.

Anspruchs- und Nachrichtenspuren können persönliche Daten, Token und vollständige Protokollnachrichten enthalten. Aktivieren Sie sie nur für einen definierten Diagnosebedarf, schränken Sie den Zugriff ein, legen Sie einen angemessenen Aufbewahrungszeitraum fest und schalten Sie sie wieder aus, wenn die Untersuchung abgeschlossen ist.

Betriebsführung

• Verwenden Sie UTC-Unix-Zeitstempel in Integrationen und wenden Sie timeOffset nur dort an, wo die Nutzungsdarstellung eine lokale Grenze erfordert.
• Teilen Sie lange Untersuchungen in Anfragen innerhalb des maximalen Zeitbereichs des Endpunkts auf.
• Halten Sie Freitextfilter spezifisch und verlassen Sie sich nicht auf den Anzeigetext als permanente Maschinenkennung.
• Schützen Sie zurückgegebene Protokoll- und Prüfdaten als betriebssensible Informationen.
• Verwenden Sie die Prüfung, um Maßnahmen zu untersuchen und nachzuweisen, und nicht, um eine garantierte Benachrichtigung oder Synchronisierung zu ersetzen API.
• Erwarten Sie, dass Änderungen an Protokolleinstellungen und Streams geprüft werden, da es sich um Control API-Mutationen handelt.

Häufige Fehlerreaktionen

• 400 Bad Request, wenn ein Zeitbereich, ein Selektor, tenant, eine Umgebung oder eine Einstellungsressource ungültig ist.
• 401 Unauthorized, wenn das Zugriffstoken fehlt oder ungültig ist.
• 403 Forbidden, wenn dem Aufrufer das erforderliche Protokoll-, Audit- oder Nutzungszugriffsrecht fehlt.
• 404 Not Found, wenn die ausgewählte Umgebungs- oder Einstellungsressource nicht vorhanden ist.

Verwenden Sie den Antworttext für Validierungsdetails und Swagger UI für die von jedem Vorgang deklarierten Antworten.

Zugehörige Dokumentation

• Control API Authentifizierungs- und Zugriffsrechte
• Protokollierungs-, Audit- und Nutzungskonzepte
• Überwachung und Gesundheitsprüfungen
• Umgebung API
• Tenant Verwaltung API