Control API - miljøer
Brug FoxIDs Control API til at angive, oprette, konfigurere og slette miljøer i en tenant. Et miljø kaldes en track i Control API ruter og skemaer.
Før du kalder disse handlinger, konfigurer Control API-godkendelse og adgangsrettigheder. Swagger forbliver den nøjagtige reference for alle miljøegenskaber, valideringsregler og svarskemaer:
Endpoint-base
Miljøadministration udføres gennem tenants master-miljø. Eksemplerne bruger FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Erstat {tenant_name} med tenants tekniske navn. Skift vært for en selv-hostet implementering. Send Control API-adgangstokenet i Authorization: Bearer {access_token}-overskriften.
Miljøoperationer kræver den tilsvarende tenant eller miljøadgangsrettighed. De miljøer, der returneres af listeoperationer, er begrænset til dem, den opkaldende har adgang til. Brug Control API adgangsrethierarkiet til kun at give den påkrævede read-, create-, update- eller delete-handling.
Miljøoperationer
Miljøhandlinger er grupperet under tenant tracks i Swagger.
| Operation | Endpoint | Formål |
|---|---|---|
| Liste | GET /!tracks |
Liste over tilgængelige miljøer med valgfri filtrering og paginering. |
| Hent | GET /!track?name={name} |
Hent den komplette konfiguration for ét miljø. |
| Opret | POST /!track |
Opret et miljø og dets standard Login-autentificeringsmetode. |
| Opdater | PUT /!track |
Erstat den redigerbare miljøkonfiguration. |
| Slet | DELETE /!track?name={name} |
Slet et miljø og dets data permanent. |
Føj hvert endpoint til endpoint-basen.
List og identificer miljøer
GET /!tracks accepterer filterName og paginationToken. Filteret matcher enten det tekniske name eller displayName, uden hensyn til tilfældet.
Svaret indeholder en data-samling og en uigennemsigtig paginationToken. For at læse den næste side skal du gentage den samme anmodning med det returnerede token og det samme filter. Fortsæt, indtil svaret ikke længere indeholder et token. Du må ikke fortolke eller ændre tokenet.
Den tekniske name identificerer miljøet i Control API webadresser og i efterfølgende handlinger for hent, opdatering og sletning. Behandl det som en stabil automatiseringsnøgle. Brug displayName til tekst præsenteret for administratorer.
Opret et miljø
Miljønavne er små. Angiv en name, når en integration kræver en forudsigelig webadresse, eller udelad den og lad FoxIDs generere et unikt navn. En anmodning skal indeholde enten et navn eller et vist navn.
Oprettelse af et miljø opretter også standard Login-autentificeringsmetoden. Andre applikationer, autentificeringsmetoder, brugere, nøgler og miljøressourcer konfigureres separat efter oprettelsen.
Planen tenant kan begrænse antallet af miljøer. En oprettelsesanmodning kan derfor mislykkes, når grænsen er nået. Samtidige plan-begrænsede oprettelseshandlinger kan returnere 423 Locked; prøv igen efter en kort forsinkelse.
Opdater miljøindstillinger
PUT /!track er en komplet opdatering, ikke en patch. Få først det aktuelle miljø, bevar alle egenskaber, der skal forblive uændrede, anvend de tilsigtede ændringer, og send den komplette redigerbare repræsentation.
Den tekniske name vælger miljøet og omdøbes ikke af en opdatering. Redigerbare indstillinger omfatter visnings- og virksomhedsoplysninger, sequence lifetime, claim mapping-adfærd, beskyttelse mod mislykkede logins, password policies, External Password, directory integration og tilladte iframe-domæner. Nogle relaterede ressourcer, herunder SMS, e-mail, claim mappings, tekster, nøgler og certifikater, har dedikerede endpoints og erstattes ikke gennem miljøoperationen.
Opdaterede indstillinger bruges af efterfølgende anmodninger, efter at FoxIDs ugyldiggør miljøkonfigurationscachen.
Slet et miljø
Sletning af et miljø er en irreversibel, kaskadende operation. Det fjerner miljøkonfigurationen og alle data i miljøet, herunder applikationer, autentificeringsmetoder, brugere, sessioner, grants, nøgler og andre ressourcer. Links fra andre miljøer til det slettede miljø fjernes også.
Brug ikke miljøsletning som en måde at rydde udvalgte ressourcer på. Slet eller opdater disse ressourcer individuelt, når miljøet skal forblive tilgængeligt. Før du sletter et miljø, skal du stoppe trafikken til det, eksportere enhver konfiguration eller data, der skal bevares, og verificere det tekniske navn i anmodningen.
Automatiseringsvejledning
- Hold tekniske navne stabile og gem dem adskilt fra visningsnavne.
- Brug listepaginering, selv når en tenant i øjeblikket kun har nogle få miljøer.
- Brug et get-modify-put-workflow for at undgå utilsigtet nulstilling af indstillinger, der er tilføjet i en nyere FoxIDs-version.
- Opret kun afhængige ressourcer, når anmodningen om oprettelse af miljøet lykkes.
- Behandl sletning som en permanent nedtagningsoperation, og kræv en eksplicit bekræftelse i administrative værktøjer.
- Forvent, at oprettelses-, opdaterings- og sletteanmodninger vises i Control-auditloggen. Læseoperationer skrives ikke som audithændelser.
Almindelige fejlsvar
400 Bad Requestnår miljødata eller -navn er ugyldige, et reserveret navn bruges, eller en plangrænse er nået.401 Unauthorized, når adgangstokenet mangler eller er ugyldigt.403 Forbidden, når den, der ringer, mangler den nødvendige adgangsret.404 Not Found, når det valgte miljø ikke eksisterer.409 Conflict, når der allerede eksisterer et miljø med det samme tekniske navn.423 Lockednår en plan-begrænset oprettelseshandling er midlertidigt låst.
Brug svarteksten til valideringsdetaljer og Swagger UI til de svar, der er erklæret af hver handling.