Control API - logboeken, audit en gebruik

Gebruik de FoxIDs Control API om diagnostische logboeken, auditgebeurtenissen en gebruiksgegevens op te vragen, en om de logboektypen te configureren die door een omgeving worden verzonden. Deze bronnen hebben verschillende doeleinden en toegangsrechten:

Logboeken helpen operators bij het diagnosticeren van fouten, waarschuwingen, protocolstromen, gebeurtenissen en statistieken.
Audit registreert beveiligings- en administratieve acties, waaronder inlogactiviteiten en Control API verzoeken voor het maken, bijwerken en verwijderen.
Gebruik verzamelt activiteit voor operationele en factureringsanalyse.

Voordat u deze bewerkingen uitvoert, configureert u Control API authenticatie en toegangsrechten. Swagger blijft de exacte referentie voor alle queryparameters, opsommingswaarden, instellingen en antwoordschema's:

Querybereik en eindpunten

FoxIDs biedt drie querybereiken.

Domein	Eindpuntbasis	Diagnostisch logboek	Controle	Gebruik
Eén omgeving	`/api/{tenant_name}/{track_name}`	`!tracklog`	`!tracklogaudit`	`!tracklogusage`
Jouw tenant	`/api/{tenant_name}/master`	`!mytenantlog`	`!mytenantlogaudit`	`!mytenantlogusage`
Implementatie administratie	`/api/master/master`	`!tenantlog`	`!tenantlogaudit`	`!tenantlogusage`

Laat de basis voorafgaan door de host FoxIDs Control, bijvoorbeeld https://control.foxids.com. Wijzig de host voor een zelf-hostende implementatie. Verzend het toegangstoken in de Authorization: Bearer {access_token}-header.

Omgevingsquery's gebruiken de omgeving van de route. Tenant query's kunnen optioneel een omgeving met trackName selecteren. Query's voor implementatiebeheer kunnen een tenant en een omgeving selecteren met tenantName en trackName. De diagnostische implementatiequery kan ook verzoeken bevatten die zijn afgewezen vóór tenant en omgevingsroutering.

Gebruik de toegangsrechten van track:log, track:audit of track:usage, eventueel beperkt tot een specifieke omgeving. Voor implementatiebrede audits en gebruik zijn de bijbehorende master toegangsrechten vereist. Zie de volledige tabellen met toegangsrechten.

Diagnostische logboeken opvragen

Een diagnostisch logverzoek specificeert fromTime en toTime als Unix-tijd in seconden. Een enkel verzoek kan maximaal 24 uur bestrijken. Selecteer een of meer categorieën, zoals fouten, waarschuwingen, sporen, gebeurtenissen en statistieken, en gebruik filter voor het filteren van vrije tekst.

Een antwoord bevat maximaal 300 van de nieuwste overeenkomende vermeldingen. Controleer responseTruncated; als het true is, beperk dan het tijdsbereik of filter en voer opnieuw een zoekopdracht uit in plaats van aan te nemen dat het resultaat compleet is.

Application Insights biedt geen ondersteuning voor het samen opvragen van traceringen en gebeurtenissen via deze bewerking. Stuur afzonderlijke verzoeken wanneer beide categorieën vereist zijn. Houd de tijdsbereiken zo beperkt als praktisch mogelijk is om de prestaties van query's te verbeteren en de hoeveelheid geretourneerde gevoelige gegevens te verminderen.

Voor de query-eindpunten is een doorzoekbare primaire logboekopslagplaats vereist. Ze kunnen geen logboeken ophalen als de primaire logboekuitvoer van de implementatie standaarduitvoer is (Stdout). In die configuratie kunt u in plaats daarvan een query uitvoeren op het container- of hostlogboeksysteem van het platform. FoxIDs ondersteunt controlequery's tegen geconfigureerde Application Insights- en OpenSearch-opslagplaatsen.

Auditgebeurtenissen opvragen

Een auditverzoek specificeert fromTime en toTime als Unix-tijd in seconden en kan maximaal zeven dagen bestrijken. toTime moet gelijk zijn aan of later zijn dan fromTime. Het optionele filter voert een algemene zoekopdracht in vrije tekst uit in auditvelden en de gebeurtenisgegevens.

Een antwoord bevat maximaal 300 van de nieuwste overeenkomende auditgebeurtenissen. Vink responseTruncated aan en splits of verfijn de zoekopdracht wanneer een volledig resultaat vereist is.

Auditgebeurtenissen omvatten gebruikersgerichte authenticatieactiviteiten en administratieve mutaties. Control API POST-, PUT- en DELETE-acties worden automatisch gecontroleerd, terwijl alleen-lezen GET-verzoeken dat niet doen. Een auditgebeurtenis kan nuttige correlatiewaarden bevatten, zoals tenant, omgeving, authenticatiemethode, applicatie, gebruiker, sessie, client-IP en user-agent als deze waarden beschikbaar zijn voor de actie.

Audit is bedoeld om te laten zien welke actie heeft plaatsgevonden en wat de context ervan is. Het is geen wachtrij voor transactiegebeurtenissen en mag niet worden gebruikt als enige trigger voor bedrijfskritische synchronisatie. Zoekresultaten zijn ook afhankelijk van de geconfigureerde opslagplaats en retentie van logboeken.

Querygebruik

Gebruiksaanvragen selecteren een tijdsbereik, een UTC-offset en een samenvattingsniveau. Inclusief vlaggen bepalen of het antwoord tenants, omgevingen, authenticatiemethoden, gebruikers, logins, tokenverzoeken, extra gebruik en Control API-activiteit bevat.

Kies het smalste bereik en alleen de afmetingen die de consument nodig heeft. Hierdoor blijven de reacties kleiner en wordt voorkomen dat tenant of gebruikersdetails onnodig zichtbaar worden. Gebruik Swagger voor de huidige tijdsbereik- en samenvattingswaarden.

Configureer omgevingsregistratie

Omgevingslogboekconfiguratie gebruikt:

Operatie	Eindpunt	Doel
Instellingen ophalen	`GET /!tracklogsetting`	Lees ingeschakelde diagnostische logboektypen voor de routeomgeving.
Instellingen opslaan	`POST /!tracklogsetting`	Vervang de logboekinstellingen van de omgeving.
Ontvang streams	`GET /!tracklogstreamssettings`	Lees de externe logstreamconfiguratie.
Bewaar streams	`POST /!tracklogstreamssettings`	Vervang de externe logstreamconfiguratie.

De instellingen beheren informatiesporen, claimtraceringen, berichttraceringen en statistieken. Fouten, waarschuwingen, kritieke fouten en gebeurtenissen blijven onafhankelijk beschikbaar, zoals beschreven in Logboekregistratie. POST vervangt de volledige instellingenbron; haal de huidige bron op, behoud ongewijzigde eigenschappen en sla vervolgens de volledige weergave op.

Een logstroom stuurt geselecteerde categorieën door naar een externe bestemming, onafhankelijk van de primaire logopslagplaats. Dit kan worden gebruikt om een gecontroleerde set omgevingslogboeken naar een afzonderlijke Application Insights-bron te sturen.

Claim- en berichttraceringen kunnen persoonlijke gegevens, tokens en volledige protocolberichten bevatten. Schakel ze alleen in voor een gedefinieerde diagnostische behoefte, beperk de toegang, stel een passende bewaartermijn in en schakel ze weer uit wanneer het onderzoek is voltooid.

Operationele begeleiding

Gebruik UTC Unix-tijdstempels in integraties en pas timeOffset alleen toe als de gebruikspresentatie een lokale grens vereist.
Splits lange onderzoeken op naar verzoeken binnen het maximale tijdsbereik van het eindpunt.
Houd vrije-tekstfilters specifiek en vermijd het vertrouwen op weergavetekst als permanente machine-ID.
Bescherm geretourneerde log- en auditgegevens als operationeel gevoelige informatie.
Gebruik audit om acties te onderzoeken en te bewijzen, niet om een gegarandeerde melding of synchronisatie API te vervangen.
Verwacht dat wijzigingen in de loginstellingen en streams worden gecontroleerd, omdat het Control API mutaties zijn.

Veelvoorkomende foutreacties

400 Bad Request wanneer een tijdsbereik, selector, tenant, omgeving of instellingenbron ongeldig is.
401 Unauthorized wanneer het toegangstoken ontbreekt of ongeldig is.
403 Forbidden wanneer de beller niet over de vereiste log-, audit- of gebruiksrechten beschikt.
404 Not Found wanneer de geselecteerde omgeving of instellingenbron niet bestaat.

Gebruik de antwoordtekst voor validatiedetails en Swagger UI voor de antwoorden die door elke bewerking zijn gedeclareerd.