Control API - miljøer
Bruk FoxIDs Control API til å liste opp, opprette, konfigurere og slette miljøer i en tenant. Et miljø kalles en track i Control API ruter og skjemaer.
Før du kaller disse operasjonene, konfigurer Control API autentisering og tilgangsrettigheter. Swagger forblir den nøyaktige referansen for alle miljøegenskaper, valideringsregler og svarskjemaer:
Endepunktbase
Miljøadministrasjon utføres gjennom tenants master-miljø. Eksemplene bruker FoxIDs Cloud:
https://control.foxids.com/api/{tenant_name}/master
Erstatt {tenant_name} med tenants tekniske navn. Endre verten for en selvdrevet distribusjon. Send Control API-tilgangstokenet i Authorization: Bearer {access_token}-overskriften.
Miljøoperasjoner krever den tilsvarende tenant- eller miljøtilgangsrettigheten. Miljøene som returneres av listeoperasjoner er begrenset til de som ringer har tilgang til. Bruk Control API tilgangsrettighetshierarkiet for å gi bare den nødvendige read-, create-, update- eller delete-operasjonen.
Miljødrift
Miljøoperasjoner er gruppert under tenant tracks i Swagger.
| Operasjon | Endepunkt | Hensikt |
|---|---|---|
| Liste | GET /!tracks |
Liste tilgjengelige miljøer med valgfri filtrering og paginering. |
| Bli | GET /!track?name={name} |
Få den komplette konfigurasjonen for ett miljø. |
| Skape | POST /!track |
Opprett et miljø og standard påloggingsautentiseringsmetode. |
| Oppdater | PUT /!track |
Erstatt den redigerbare miljøkonfigurasjonen. |
| Slett | DELETE /!track?name={name} |
Slett et miljø og dets data permanent. |
Legg til hvert endepunkt til endepunktbasen.
List opp og identifiser miljøer
GET /!tracks godtar filterName og paginationToken. Filteret samsvarer enten med den tekniske name eller displayName, uten hensyn til store og små bokstaver.
Svaret inneholder en data-samling og en ugjennomsiktig paginationToken. For å lese neste side, gjenta den samme forespørselen med det returnerte tokenet og det samme filteret. Fortsett til svaret ikke lenger inneholder et token. Ikke tolk eller modifiser tokenet.
Den tekniske name identifiserer miljøet i Control API URL-er og i påfølgende handlinger for hent, oppdatering og sletting. Behandle den som en stabil automatiseringsnøkkel. Bruk displayName for tekst presentert for administratorer.
Skap et miljø
Miljønavn er små bokstaver. Oppgi en name når en integrasjon krever en forutsigbar nettadresse, eller utelat den og la FoxIDs generere et unikt navn. En forespørsel må inneholde enten et navn eller et visningsnavn.
Oppretting av et miljø oppretter også standard påloggingsautentiseringsmetode. Andre applikasjoner, autentiseringsmetoder, brukere, nøkler og miljøressurser konfigureres separat etter opprettelse.
tenant-planen kan begrense antall miljøer. En opprettelsesforespørsel kan derfor mislykkes når grensen er nådd. Samtidige planbegrensede opprettelsesoperasjoner kan returnere 423 Locked; prøv igjen etter en kort forsinkelse.
Oppdater miljøinnstillinger
PUT /!track er en fullstendig oppdatering, ikke en oppdatering. Få først det gjeldende miljøet, bevar alle egenskaper som skal forbli uendret, bruk de tiltenkte endringene og send den fullstendige redigerbare representasjonen.
Den tekniske name velger miljøet og får ikke nytt navn av en oppdatering. Redigerbare innstillinger inkluderer skjerm- og firmadetaljer, sekvenslevetid, kravkartlegging, beskyttelse mot påloggingsfeil, passordpolicyer, eksternt passord og katalogintegrasjon, og tillatte iframe-domener. Noen relaterte ressurser, inkludert SMS, e-post, kravtilordninger, tekster, nøkler og sertifikater, har dedikerte endepunkter og erstattes ikke gjennom miljøoperasjonen.
Oppdaterte innstillinger brukes av påfølgende forespørsler etter at FoxIDs ugyldiggjør miljøkonfigurasjonsbufferen.
Slett et miljø
Å slette et miljø er en irreversibel, gjennomgripende operasjon. Den fjerner miljøkonfigurasjonen og alle data som er omfattet av det miljøet, inkludert applikasjoner, autentiseringsmetoder, brukere, økter, bevilgninger, nøkler og andre ressurser. Lenker fra andre miljøer til det slettede miljøet fjernes også.
Ikke bruk miljøsletting som en måte å slette utvalgte ressurser. Slett eller oppdater disse ressursene individuelt når miljøet må forbli tilgjengelig. Før du sletter et miljø, stopp trafikken til det, eksporter eventuelle konfigurasjoner eller data som må beholdes, og bekreft det tekniske navnet i forespørselen.
Automasjonsveiledning
- Hold tekniske navn stabile og lagre dem separat fra visningsnavn.
- Bruk listepaginering selv når en tenant for øyeblikket bare har noen få miljøer.
- Bruk en get-modify-put-arbeidsflyt for å unngå utilsiktet tilbakestilling av innstillinger som er lagt til i en nyere FoxIDs-versjon.
- Opprett avhengige ressurser først etter at miljøopprettingsforespørselen lykkes.
- Behandle sletting som en permanent riveoperasjon og krev en eksplisitt bekreftelse i administrativt verktøy.
- Forvent at opprette, oppdatere og slette forespørsler vises i kontrollrevisjonsloggen. Leseoperasjoner skrives ikke som revisjonshendelser.
Vanlige feilsvar
400 Bad Requestnår miljødataene eller navnet er ugyldig, et reservert navn brukes eller en plangrense er nådd.401 Unauthorizednår tilgangstokenet mangler eller er ugyldig.403 Forbiddennår den som ringer mangler den nødvendige tilgangsrettigheten.404 Not Foundnår det valgte miljøet ikke eksisterer.409 Conflictnår et miljø med samme tekniske navn allerede eksisterer.423 Lockednår en planbegrenset opprettelsesoperasjon er midlertidig låst.
Bruk svarteksten for valideringsdetaljer og Swagger UI for svarene deklarert av hver operasjon.