Control API - applications et méthodes d'authentification

Utilisez FoxIDs Control API pour configurer les applications qui font confiance à FoxIDs et les méthodes d'authentification que FoxIDs approuvent. Dans les routes et schémas Control API, un enregistrement d'application est appelé un downparty et une méthode d'authentification est appelée un upparty.

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 les propriétés spécifiques au protocole, les règles de validation, les opérations d'assistance et les schémas de réponse :

• Swagger (OpenAPI) JSON
• Swagger UI

Base de points de terminaison et droits d'accès

Les exemples utilisent FoxIDs Cloud :

https://control.foxids.com/api/{tenant_name}/{track_name}

Remplacez {tenant_name} et {track_name} par les noms techniques tenant et de l'environnement. Changez l’hôte pour un déploiement auto-hébergé. Envoyez le jeton d'accès Control API dans l'en-tête Authorization: Bearer {access_token}.

Ces opérations nécessitent un droit d'accès party pour l'environnement cible. Accordez uniquement l'opération read, create, update ou delete requise via la Control API hiérarchie des droits d'accès.

Répertorier et identifier les inscriptions

Utilisez ces points de terminaison pour découvrir les enregistrements avant d'appeler un point de terminaison spécifique à un type :

Les réponses de la liste contiennent des résumés sécurisés, le type d'enregistrement et un jeton de pagination opaque. Utilisez l’opération get spécifique au type pour la représentation modifiable complète. Répétez une requête paginée avec les mêmes filtres et le jeton renvoyé jusqu'à ce qu'aucun jeton ne soit renvoyé.

Le name technique est l'identifiant stable utilisé par les opérations d'obtention, de mise à jour, de suppression, de secret, de clé et de relation. Les noms sont en minuscules. Fournissez un nom lors de la création lorsqu'une intégration nécessite un identifiant prévisible, ou laissez FoxIDs en générer un. Utilisez l'assistant !newpartyname lorsqu'un nom unique est nécessaire avant la création d'une ressource.

Opérations spécifiques au type

Chaque type de ressource possède son propre point de terminaison car la configuration du protocole diffère. Les principaux critères d'évaluation sont :

Les opérations habituelles sont GET ?name={name}, POST pour créer, PUT pour mettre à jour et DELETE ?name={name}. Ajoutez le point de terminaison à la base de point de terminaison. Consultez Swagger pour les opérations prises en charge par chaque type.

La création d'applications ou de méthodes d'authentification est soumise aux limites de l'environnement et du plan tenant. Certaines opérations de création simultanées limitées par un plan peuvent renvoyer 423 Locked ; réessayez après un court délai.

Mettre à jour et renommer en toute sécurité

Les opérations du groupe PUT sont des mises à jour complètes, pas des correctifs. Utilisez ce flux de travail :

1. Répertoriez les ressources ou obtenez la ressource connue par nom technique.
2. Obtenez sa représentation complète spécifique au type.
3. Conservez les propriétés qui doivent rester inchangées et appliquez les modifications prévues.
4. Envoyez la représentation modifiable complète au point de terminaison PUT spécifique au type correspondant.

Utilisez newName lorsque le nom technique doit changer. Les références sont mises à jour dans le cadre du flux de renommage. La méthode d'authentification de connexion par défaut nommée login ne peut pas être renommée ou supprimée.

Les secrets client, les clés client et certains secrets API externes sont gérés par des points de terminaison dédiés. Ils ne sont délibérément pas renvoyés en clair dans la représentation générale du parti et ne doivent pas être copiés dans une demande de mise à jour normale.

Connecter les applications aux méthodes d'authentification

La collection allowUpParties d'une application contrôle les méthodes d'authentification qui peuvent être utilisées pour se connecter à cette application. Les méthodes d'authentification référencées doivent exister dans le même environnement et être compatibles avec la configuration.

Traitez cette relation comme faisant partie de la configuration complète de l'application lors de sa mise à jour. La suppression d'une méthode d'authentification peut modifier le routage de connexion pour les applications qui y font référence ; vérifier les applications dépendantes avant la suppression. Utilisez un Environment Link lorsque la méthode ou l'application d'authentification est intentionnellement connectée à travers des environnements FoxIDs.

Gérer les secrets et les clés

Les applications OAuth 2.0 et OpenID Connect fournissent des opérations secrètes client dédiées. Un secret est accepté une fois créé, stocké sous forme de hachage et n'est pas renvoyé en texte brut. La réponse de liste contient les identifiants et les informations sécurisées nécessaires à la gestion des secrets existants.

Utilisez des informations d'identification qui se chevauchent pour la rotation :

1. Générez un nouveau secret client et stockez-le en toute sécurité.
2. Créez le secret client dans FoxIDs et déployez la même valeur sur l'application consommatrice.
3. Vérifiez que l'application utilise le nouveau secret.
4. Supprimez l'ancien secret par son application et ses identifiants secrets.

Les méthodes d'authentification OpenID Connect et OAuth 2.0 peuvent utiliser des opérations dédiées de secret client ou de clé client, en fonction de la méthode d'authentification client sélectionnée. Une opération de clé privée accepte les certificats et les éléments de clé privée. External Login dispose d'un point de terminaison secret dédié. Utilisez le point de terminaison exact et le schéma de demande indiqués dans Swagger pour le type d'enregistrement sélectionné.

Les secrets, les clés privées et les charges utiles complètes des certificats sont sensibles. Utilisez TLS, accordez l'accès uniquement aux clients d'automatisation de confiance, protégez les valeurs au repos et n'enregistrez pas les corps de requête ou de réponse.

Aides aux métadonnées et à la découverte

Les opérations d'assistance de protocole réduisent la configuration manuelle mais ne remplacent pas la validation de la ressource résultante :

• Les méthodes d'authentification OpenID Connect et OAuth 2.0 peuvent lire les métadonnées de découverte et renseigner les paramètres compatibles.
• SAML 2.0 les enregistrements d'applications et les méthodes d'authentification peuvent lire les métadonnées.
• WS-Federation les enregistrements d'applications et les méthodes d'authentification peuvent lire les métadonnées.
• Les méthodes d'authentification WS-Federation incluent un assistant de synchronisation Microsoft Entra ID.

Après avoir utilisé un assistant, inspectez la configuration renvoyée, appliquez les paramètres de stratégie et de réclamation locaux, puis enregistrez-la via le point de terminaison de création ou de mise à jour spécifique au type. Les métadonnées peuvent changer au fil du temps, alors définissez si la synchronisation est une action administrative explicite ou un processus récurrent contrôlé.

Effets de suppression et de dépendance

La suppression d'une application arrête les nouvelles demandes de protocole pour cette application. La suppression d'une méthode d'authentification peut empêcher les applications de se connecter et modifier Home Realm Discovery choix. Supprimez ou mettez à jour les dépendances en premier et traitez les deux opérations comme des modifications de configuration permanentes.

Les demandes de création, de mise à jour, de secret/clé, d'assistance et de suppression sont incluses dans le journal d'audit de contrôle. Les opérations de lecture ne sont pas écrites sous forme d’événements d’audit.

Réponses aux erreurs courantes

• 400 Bad Request lorsque les paramètres de protocole, les références, les métadonnées, les secrets, les clés ou les noms ne sont pas valides, ou qu'une limite du forfait est atteinte.
• 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.
• 404 Not Found lorsque l'enregistrement, le secret ou la clé sélectionné n'existe pas.
• 409 Conflict lorsqu'un nom technique ou un identifiant secret existe déjà.
• 423 Locked lorsqu'une opération de création limitée au plan est temporairement verrouillée.

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.

Documentation associée

• Control API authentification et droits d'accès
• Applications
• Méthodes d'authentification
• Environment Link
• Réclamations et transformations de revendications