Control API - applicaties en authenticatiemethoden

Gebruik de FoxIDs Control API om de toepassingen te configureren die FoxIDs vertrouwen, en de authenticatiemethoden die FoxIDs vertrouwen. In Control API routes en schema's wordt een applicatieregistratie een downparty genoemd en een authenticatiemethode een upparty.

Voordat u deze bewerkingen uitvoert, configureert u Control API authenticatie en toegangsrechten. Swagger blijft de exacte referentie voor protocolspecifieke eigenschappen, validatieregels, helperbewerkingen en antwoordschema's:

• Swagger (OpenAPI) JSON
• Swagger UI

Eindpuntbasis en toegangsrechten

In de voorbeelden wordt FoxIDs Cloud gebruikt:

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

Vervang {tenant_name} en {track_name} door de tenant en technische namen van de omgeving. Wijzig de host voor een zelf-hostende implementatie. Verzend het toegangstoken Control API in de header Authorization: Bearer {access_token}.

Voor deze bewerkingen is een toegangsrecht van party vereist voor de doelomgeving. Verleen alleen de vereiste bewerking read, create, update of delete via de Control API hiërarchie van toegangsrechten.

Registreer en identificeer registraties

Gebruik deze eindpunten om registraties te ontdekken voordat u een typespecifiek eindpunt aanroept:

De lijstreacties bevatten veilige samenvattingen, het registratietype en een ondoorzichtig pagineringstoken. Gebruik de typespecifieke get-bewerking voor de volledige bewerkbare representatie. Herhaal een gepagineerd verzoek met dezelfde filters en het geretourneerde token totdat er geen token wordt geretourneerd.

De technische name is de stabiele identificatie die wordt gebruikt voor ophaal-, update-, verwijder-, geheim-, sleutel- en relatiebewerkingen. Namen zijn in kleine letters. Geef een naam op bij het maken wanneer een integratie een voorspelbare ID vereist, of laat FoxIDs er een genereren. Gebruik de !newpartyname-helper wanneer een unieke naam nodig is voordat een bron wordt gemaakt.

Typespecifieke bewerkingen

Elk brontype heeft zijn eigen eindpunt omdat de protocolconfiguratie verschilt. De belangrijkste eindpunten zijn:

De gebruikelijke bewerkingen zijn GET ?name={name}, POST om te maken, PUT om bij te werken en DELETE ?name={name}. Voeg het eindpunt toe aan de eindpuntbasis. Raadpleeg Swagger voor de bewerkingen die door elk type worden ondersteund.

Het maken van applicaties of authenticatiemethoden is onderworpen aan de omgevings- en tenant abonnementslimieten. Sommige gelijktijdige, planbeperkte maakbewerkingen kunnen 423 Locked retourneren; probeer het na een korte vertraging opnieuw.

Veilig bijwerken en hernoemen

Party PUT-bewerkingen zijn volledige updates, geen patches. Gebruik deze werkstroom:

1. Maak een lijst van de resources of haal de bekende resource op via de technische naam.
2. Verkrijg de volledige typespecifieke weergave.
3. Behoud eigenschappen die onveranderd moeten blijven en pas de beoogde wijzigingen toe.
4. Stuur de volledige bewerkbare representatie naar het overeenkomende typespecifieke eindpunt PUT.

Gebruik newName als de technische naam moet veranderen. Verwijzingen worden bijgewerkt als onderdeel van de hernoemingsstroom. De standaard aanmeldingsverificatiemethode met de naam login kan niet worden hernoemd of verwijderd.

Clientgeheimen, clientsleutels en enkele externe API-geheimen worden beheerd door speciale eindpunten. Ze worden met opzet niet als leesbare tekst teruggestuurd in de algemene partijweergave en mogen niet worden gekopieerd naar een normaal updateverzoek.

Verbind applicaties met authenticatiemethoden

De allowUpParties-verzameling van een applicatie bepaalt welke authenticatiemethoden kunnen worden gebruikt om in te loggen bij die applicatie. De authenticatiemethoden waarnaar wordt verwezen, moeten in dezelfde omgeving bestaan ​​en compatibel zijn met de configuratie.

Behandel deze relatie als onderdeel van de volledige configuratie van de applicatie wanneer deze wordt bijgewerkt. Het verwijderen van een authenticatiemethode kan de aanmeldingsroutering wijzigen voor toepassingen die ernaar verwijzen; verifieer afhankelijke applicaties voordat u deze verwijdert. Gebruik een Environment Link wanneer de authenticatiemethode of -applicatie opzettelijk is verbonden met FoxIDs-omgevingen.

Beheer geheimen en sleutels

OAuth 2.0- en OpenID Connect-applicaties bieden speciale clientgeheime bewerkingen. Een geheim wordt geaccepteerd wanneer het wordt gemaakt, opgeslagen als een hash en niet in leesbare tekst geretourneerd. Het lijstantwoord bevat de identificatiegegevens en veilige informatie die nodig is om bestaande geheimen te beheren.

Gebruik overlappende referenties voor rotatie:

1. Genereer een nieuw klantgeheim en bewaar het veilig.
2. Maak het clientgeheim in FoxIDs en implementeer dezelfde waarde in de verbruikende applicatie.
3. Controleer of de toepassing het nieuwe geheim gebruikt.
4. Verwijder het oude geheim op basis van de toepassing en geheime ID's.

De authenticatiemethoden OpenID Connect en OAuth 2.0 kunnen speciale clientgeheim- of clientsleutelbewerkingen gebruiken, afhankelijk van de geselecteerde clientauthenticatiemethode. Bij een privésleutelbewerking worden certificaten en privésleutelmateriaal geaccepteerd. External Login heeft een speciaal geheim eindpunt. Gebruik het exacte eindpunt en verzoekschema dat wordt weergegeven in Swagger voor het geselecteerde registratietype.

Geheimen, privésleutels en volledige certificaatpayloads zijn gevoelig. Gebruik TLS, verleen alleen toegang aan vertrouwde automatiseringsclients, bescherm waarden in rust en registreer geen verzoek- of antwoordinstanties.

Metagegevens en ontdekkingshulpmiddelen

Protocolhelperbewerkingen verminderen de handmatige configuratie, maar vervangen de validatie van de resulterende bron niet:

• De authenticatiemethoden OpenID Connect en OAuth 2.0 kunnen ontdekkingsmetadata lezen en compatibele instellingen invullen.
• SAML 2.0 applicatieregistraties en authenticatiemethoden kunnen metadata lezen.
• WS-Federation applicatieregistraties en authenticatiemethoden kunnen metadata lezen.
• WS-Federation authenticatiemethoden omvatten een Microsoft Entra ID-synchronisatiehulp.

Nadat u een helper hebt gebruikt, inspecteert u de geretourneerde configuratie, past u lokale beleids- en claiminstellingen toe en slaat u deze op via het typespecifieke eindpunt voor maken of bijwerken. Metagegevens kunnen in de loop van de tijd veranderen, dus definieer of synchronisatie een expliciete administratieve actie is of een gecontroleerd terugkerend proces.

Verwijderings- en afhankelijkheidseffecten

Als u een toepassing verwijdert, worden nieuwe protocolaanvragen voor die toepassing stopgezet. Als u een verificatiemethode verwijdert, kan dit ertoe leiden dat toepassingen de aanmelding niet voltooien en kunnen de keuzes van Home Realm Discovery worden gewijzigd. Verwijder of update eerst de afhankelijkheden en behandel beide bewerkingen als permanente configuratiewijzigingen.

Aanmaak-, update-, geheim/sleutel-, helper- en verwijderverzoeken zijn opgenomen in het Controle-auditlogboek. Leesbewerkingen worden niet geschreven als auditgebeurtenissen.

Veelvoorkomende foutreacties

• 400 Bad Request wanneer protocolinstellingen, referenties, metadata, geheimen, sleutels of namen ongeldig zijn of een abonnementslimiet is bereikt.
• 401 Unauthorized wanneer het toegangstoken ontbreekt of ongeldig is.
• 403 Forbidden wanneer de beller niet over de vereiste partijtoegangsrechten beschikt.
• 404 Not Found wanneer de geselecteerde registratie, geheim of sleutel niet bestaat.
• 409 Conflict wanneer er al een technische naam of geheime identificatie bestaat.
• 423 Locked wanneer een planbeperkte maakbewerking tijdelijk is vergrendeld.

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

Gerelateerde documentatie

• Control API authenticatie en toegangsrechten
• Toepassingen
• Authenticatiemethoden
• Environment Link
• Claims en claimtransformaties