Control API - journaux, audit et utilisation

Utilisez FoxIDs Control API pour interroger les journaux de diagnostic, les événements d'audit et les données d'utilisation, ainsi que pour configurer les types de journaux émis par un environnement. Ces ressources ont des finalités et des droits d’accès différents :

Les journaux aident les opérateurs à diagnostiquer les erreurs, les avertissements, les flux de protocole, les événements et les mesures.
Audit enregistre les actions de sécurité et d'administration, y compris l'activité de connexion et les Control API demandes de création, de mise à jour et de suppression.
Utilisation regroupe l'activité pour l'analyse opérationnelle et de facturation.

Avant d'appeler ces opérations, configurez Control API l'authentification et les droits d'accès. Swagger reste la référence exacte pour tous les paramètres de requête, valeurs d'énumération, paramètres et schémas de réponse :

Portée de la requête et points de terminaison

FoxIDs fournit trois étendues de requête.

Portée	Base de point de terminaison	Journal de diagnostic	Audit	Usage
Un environnement	`/api/{tenant_name}/{track_name}`	`!tracklog`	`!tracklogaudit`	`!tracklogusage`
Votre tenant	`/api/{tenant_name}/master`	`!mytenantlog`	`!mytenantlogaudit`	`!mytenantlogusage`
Administration du déploiement	`/api/master/master`	`!tenantlog`	`!tenantlogaudit`	`!tenantlogusage`

Préfixez la base avec l'hôte FoxIDs Control, par exemple https://control.foxids.com. Changez l’hôte pour un déploiement auto-hébergé. Envoyez le jeton d'accès dans l'en-tête Authorization: Bearer {access_token}.

Les requêtes d'environnement utilisent l'environnement de la route. Les requêtes Tenant peuvent éventuellement sélectionner un environnement avec trackName. Les requêtes d'administration de déploiement peuvent sélectionner un tenant et un environnement avec tenantName et trackName. La requête de diagnostic de déploiement peut également inclure les demandes rejetées avant tenant et le routage de l'environnement.

Utilisez les droits d'accès track:log, track:audit ou track:usage, éventuellement restreints à un environnement spécifique. L'audit et l'utilisation à l'échelle du déploiement nécessitent les droits d'accès master correspondants. Voir les tableaux complets des droits d'accès.

Interroger les journaux de diagnostic

Une demande de journal de diagnostic spécifie fromTime et toTime comme heure Unix en secondes. Une seule demande peut couvrir au maximum 24 heures. Sélectionnez une ou plusieurs catégories telles que les erreurs, les avertissements, les traces, les événements et les métriques, et utilisez filter pour le filtrage de texte libre.

Une réponse contient jusqu'à 300 des entrées correspondantes les plus récentes. Vérifiez responseTruncated ; lorsqu'il s'agit de true, réduisez la plage de temps ou filtrez et interrogez à nouveau plutôt que de supposer que le résultat est complet.

Application Insights ne prend pas en charge l'interrogation conjointe des traces et des événements via cette opération. Envoyez des demandes distinctes lorsque les deux catégories sont requises. Gardez les plages de temps aussi étroites que possible pour améliorer les performances des requêtes et réduire la quantité de données sensibles renvoyées.

Les points de terminaison de requête nécessitent un référentiel de journaux principal consultable. Ils ne peuvent pas récupérer les journaux lorsque la sortie principale du journal du déploiement est la sortie standard (Stdout). Dans cette configuration, interrogez plutôt le conteneur ou le système de journalisation hôte de la plateforme. FoxIDs prend en charge les requêtes de contrôle sur les référentiels Application Insights et OpenSearch configurés.

Événements d’audit de requête

Une demande d'audit spécifie fromTime et toTime comme heure Unix en secondes et peut couvrir sept jours au maximum. toTime doit être égal ou supérieur à fromTime. Le filter facultatif effectue une recherche générale en texte libre dans les champs d'audit et les données d'événement.

Une réponse contient jusqu'à 300 des événements d'audit correspondants les plus récents. Cochez responseTruncated et divisez ou affinez la requête lorsqu'un résultat complet est requis.

Les événements d’audit incluent l’activité d’authentification destinée aux utilisateurs et les mutations administratives. Les actions Control API POST, PUT et DELETE sont auditées automatiquement, contrairement aux requêtes GET en lecture seule. Un événement d'audit peut contenir des valeurs de corrélation utiles telles que tenant, l'environnement, la méthode d'authentification, l'application, l'utilisateur, la session, l'adresse IP du client et l'agent utilisateur lorsque ces valeurs sont disponibles pour l'action.

L'audit est conçu pour montrer quelle action s'est produite et son contexte. Il ne s'agit pas d'une file d'attente d'événements transactionnels et ne doit pas être utilisée comme seul déclencheur pour une synchronisation critique pour l'entreprise. Les résultats de la recherche dépendent également du référentiel de journaux configuré et de la conservation.

Utilisation des requêtes

Les demandes d'utilisation sélectionnent une étendue temporelle, un décalage UTC et un niveau de synthèse. Les indicateurs d'inclusion déterminent si la réponse contient tenants, des environnements, des méthodes d'authentification, des utilisateurs, des connexions, des demandes de jetons, une utilisation supplémentaire et une activité Control API.

Choisissez la portée la plus étroite et uniquement les dimensions nécessaires au consommateur. Cela permet de réduire la taille des réponses et d'éviter d'exposer inutilement tenant ou les détails de l'utilisateur. Utilisez Swagger pour la durée actuelle et les valeurs de synthèse.

Configurer la journalisation de l'environnement

La configuration du journal d'environnement utilise :

Opération	Point de terminaison	But
Obtenir les paramètres	`GET /!tracklogsetting`	Lire les types de journaux de diagnostic activés pour l’environnement d’itinéraire.
Enregistrer les paramètres	`POST /!tracklogsetting`	Remplacez les paramètres de journal de l'environnement.
Obtenez des flux	`GET /!tracklogstreamssettings`	Lire la configuration du flux de journaux externe.
Enregistrer les flux	`POST /!tracklogstreamssettings`	Remplacez la configuration du flux de journaux externe.

Les paramètres contrôlent les traces d’informations, les traces de réclamations, les traces de messages et les métriques. Les erreurs, avertissements, erreurs critiques et événements restent disponibles indépendamment, comme décrit dans Journalisation. POST remplace la ressource complète des paramètres ; obtenez la ressource actuelle, conservez les propriétés inchangées, puis enregistrez la représentation complète.

Un flux de journaux transfère les catégories sélectionnées vers une destination externe indépendamment du référentiel de journaux principal. Cela peut être utilisé pour envoyer un ensemble contrôlé de journaux d'environnement à une ressource Application Insights distincte.

Les traces de réclamations et de messages peuvent contenir des données personnelles, des jetons et des messages de protocole complets. Activez-les uniquement pour un besoin de diagnostic défini, limitez l'accès, définissez une période de conservation appropriée et désactivez-les à nouveau une fois l'enquête terminée.

Orientation opérationnelle

Utilisez les horodatages UTC Unix dans les intégrations et appliquez timeOffset uniquement lorsque la présentation de l'utilisation nécessite une limite locale.
Divisez les longues enquêtes en demandes dans la plage de temps maximale du point de terminaison.
Gardez les filtres de texte libre spécifiques et évitez de vous fier au texte affiché comme identifiant permanent de la machine.
Protégez les données de journal et d’audit renvoyées en tant qu’informations opérationnellement sensibles.
Utilisez l'audit pour enquêter et prouver les actions, et non pour remplacer une notification ou une synchronisation garantie API.
Attendez-vous à ce que les modifications apportées aux paramètres de journalisation et aux flux soient auditées, car il s'agit de Control API mutations.

Réponses aux erreurs courantes

400 Bad Request lorsqu'une ressource de plage horaire, de sélecteur, de tenant, d'environnement ou de paramètres n'est pas valide.
401 Unauthorized lorsque le jeton d'accès est manquant ou invalide.
403 Forbidden lorsque l'appelant ne dispose pas du droit d'accès requis au journal, à l'audit ou à l'utilisation.
404 Not Found lorsque la ressource d'environnement ou de paramètres sélectionnée n'existe pas.

Utilisez le corps de la réponse pour les détails de validation et Swagger UI pour les réponses déclarées par chaque opération.