Control API - omgevingen

Gebruik de FoxIDs Control API om omgevingen in een tenant weer te geven, te maken, te configureren en te verwijderen. Een omgeving wordt in Control API routes en schema's een track genoemd.

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

Eindpuntbasis

Omgevingsbeheer wordt uitgevoerd via de master-omgeving van tenant. In de voorbeelden wordt FoxIDs Cloud gebruikt:

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

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

Omgevingsbewerkingen vereisen het overeenkomstige tenant- of omgevingstoegangsrecht. De omgevingen die door lijstbewerkingen worden geretourneerd, zijn beperkt tot de omgevingen waartoe de beller toegang heeft. Gebruik de Control API hiërarchie van toegangsrechten om alleen de vereiste bewerking read, create, update of delete toe te staan.

Omgevingsactiviteiten

Omgevingsbewerkingen zijn gegroepeerd onder tenant tracks in Swagger.

Operatie	Eindpunt	Doel
Lijst	`GET /!tracks`	Maak een lijst van toegankelijke omgevingen met optionele filtering en paginering.
Krijgen	`GET /!track?name={name}`	Ontvang de volledige configuratie voor één omgeving.
Creëren	`POST /!track`	Maak een omgeving en de standaardaanmeldingsverificatiemethode.
Update	`PUT /!track`	Vervang de bewerkbare omgevingsconfiguratie.
Verwijderen	`DELETE /!track?name={name}`	Een omgeving en de bijbehorende gegevens definitief verwijderen.

Voeg elk eindpunt toe aan de eindpuntbasis.

Omgevingen benoemen en identificeren

GET /!tracks accepteert filterName en paginationToken. Het filter komt overeen met de technische name of de displayName, ongeacht hoofdlettergebruik.

Het antwoord bevat een verzameling data en een ondoorzichtige paginationToken. Om de volgende pagina te lezen, herhaalt u hetzelfde verzoek met het geretourneerde token en hetzelfde filter. Ga door totdat het antwoord geen token meer bevat. Interpreteer of wijzig het token niet.

De technische name identificeert de omgeving in Control API URL's en in daaropvolgende ophaal-, update- en verwijderbewerkingen. Behandel het als een stabiele automatiseringssleutel. Gebruik displayName voor tekst die aan beheerders wordt gepresenteerd.

Creëer een omgeving

Omgevingsnamen zijn in kleine letters. Geef een name op als een integratie een voorspelbare URL vereist, of laat deze weg en laat FoxIDs een unieke naam genereren. Een aanvraag moet een naam of een weergavenaam bevatten.

Door een omgeving te maken, wordt ook de standaard aanmeldingsverificatiemethode aangemaakt. Andere applicaties, authenticatiemethoden, gebruikers, sleutels en omgevingsbronnen worden na creatie afzonderlijk geconfigureerd.

Het tenant-abonnement kan het aantal omgevingen beperken. Een create request kan dus mislukken als de limiet bereikt is. Gelijktijdige planbeperkte maakbewerkingen kunnen 423 Locked retourneren; probeer het na een korte vertraging opnieuw.

Omgevingsinstellingen bijwerken

PUT /!track is een volledige update, geen patch. Haal eerst de huidige omgeving op, behoud alle eigenschappen die ongewijzigd moeten blijven, pas de beoogde wijzigingen toe en verzend de volledige bewerkbare weergave.

De technische name selecteert de omgeving en wordt niet hernoemd door een update. Bewerkbare instellingen omvatten de weergave- en bedrijfsgegevens, de levensduur van de reeks, het gedrag van het in kaart brengen van claims, bescherming tegen inlogfouten, wachtwoordbeleid, externe wachtwoord- en directory-integratie en toegestane iframe-domeinen. Sommige gerelateerde bronnen, waaronder sms, e-mail, claimtoewijzingen, teksten, sleutels en certificaten, hebben speciale eindpunten en worden niet vervangen door de omgevingsbewerking.

Bijgewerkte instellingen worden gebruikt door volgende verzoeken nadat FoxIDs de cache van de omgevingsconfiguratie ongeldig heeft gemaakt.

Verwijder een omgeving

Het verwijderen van een omgeving is een onomkeerbare, trapsgewijze bewerking. Het verwijdert de omgevingsconfiguratie en alle gegevens die betrekking hebben op die omgeving, inclusief de applicaties, authenticatiemethoden, gebruikers, sessies, subsidies, sleutels en andere bronnen. Ook koppelingen vanuit andere omgevingen naar de verwijderde omgeving worden verwijderd.

Gebruik het verwijderen van de omgeving niet als een manier om geselecteerde bronnen te wissen. Verwijder of update deze bronnen afzonderlijk wanneer de omgeving beschikbaar moet blijven. Voordat u een omgeving verwijdert, stopt u het verkeer ernaartoe, exporteert u alle configuraties of gegevens die moeten worden bewaard en verifieert u de technische naam in het verzoek.

Automatisering begeleiding

Houd technische namen stabiel en bewaar ze gescheiden van weergavenamen.
Gebruik lijstpaginering, zelfs als een tenant momenteel slechts enkele omgevingen heeft.
Gebruik een get-modify-put-workflow om te voorkomen dat instellingen die zijn toegevoegd in een nieuwere FoxIDs-versie onbedoeld opnieuw worden ingesteld.
Maak pas afhankelijke resources nadat de aanvraag voor het maken van de omgeving is geslaagd.
Beschouw het verwijderen als een permanente demontageoperatie en vereis een expliciete bevestiging in de administratieve tool.
Verwacht dat aanvragen voor het maken, bijwerken en verwijderen verschijnen in het controle-auditlogboek. Leesbewerkingen worden niet geschreven als auditgebeurtenissen.

Veelvoorkomende foutreacties

400 Bad Request wanneer de omgevingsgegevens of -naam ongeldig zijn, een gereserveerde naam wordt gebruikt of een abonnementslimiet wordt bereikt.
401 Unauthorized wanneer het toegangstoken ontbreekt of ongeldig is.
403 Forbidden wanneer de beller niet over de vereiste toegangsrechten beschikt.
404 Not Found wanneer de geselecteerde omgeving niet bestaat.
409 Conflict wanneer er al een omgeving met dezelfde technische naam 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.