Control API – programmer og autentiseringsmetoder

Bruk FoxIDs Control API til å konfigurere applikasjonene som klarerer FoxIDs og autentiseringsmetodene FoxIDs klarerer. I Control API ruter og skjemaer kalles en applikasjonsregistrering en downparty og en autentiseringsmetode kalles en upparty.

Før du kaller disse operasjonene, konfigurer Control API autentisering og tilgangsrettigheter. Swagger forblir den nøyaktige referansen for protokollspesifikke egenskaper, valideringsregler, hjelpeoperasjoner og svarskjemaer:

• Swagger (OpenAPI) JSON
• Swagger UI

Endepunktbase og tilgangsrettigheter

Eksemplene bruker FoxIDs Cloud:

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

Erstatt {tenant_name} og {track_name} med de tekniske navnene tenant og miljø. Endre verten for en selvdrevet distribusjon. Send Control API-tilgangstokenet i Authorization: Bearer {access_token}-overskriften.

Disse operasjonene krever en party-tilgangsrettighet for målmiljøet. Gi bare den nødvendige read-, create-, update- eller delete-operasjonen gjennom Control API tilgangsrettighetshierarkiet.

List opp og identifiser registreringer

Bruk disse endepunktene til å oppdage registreringer før du anroper et typespesifikt endepunkt:

Listesvarene inneholder sikre sammendrag, registreringstypen og et ugjennomsiktig pagineringstoken. Bruk den typespesifikke hentoperasjonen for den fullstendige redigerbare representasjonen. Gjenta en paginert forespørsel med de samme filtrene og det returnerte tokenet til ingen token returneres.

Den tekniske name er den stabile identifikatoren som brukes av hent, oppdater, slett, hemmelig, nøkkel og relasjonsoperasjoner. Navnene er små. Oppgi et navn ved opprettelse når en integrasjon krever en forutsigbar identifikator, eller la FoxIDs generere en. Bruk !newpartyname-hjelperen når et unikt navn er nødvendig før en ressurs opprettes.

Typespesifikke operasjoner

Hver ressurstype har sitt eget endepunkt fordi protokollkonfigurasjonen er forskjellig. De viktigste endepunktene er:

De vanlige operasjonene er GET ?name={name}, POST å opprette, PUT å oppdatere og DELETE ?name={name}. Legg til endepunktet til endepunktbasen. Se Swagger for operasjoner som støttes av hver type.

Oppretting av applikasjoner eller autentiseringsmetoder er underlagt miljø- og tenant plangrenser. Noen samtidige planbegrensede opprettelsesoperasjoner kan returnere 423 Locked; prøv igjen etter en kort forsinkelse.

Oppdater og gi nytt navn trygt

Party PUT-operasjoner er fullstendige oppdateringer, ikke oppdateringer. Bruk denne arbeidsflyten:

1. List opp ressursene eller få den kjente ressursen etter teknisk navn.
2. Få dens komplette typespesifikke representasjon.
3. Bevar egenskaper som skal forbli uendret og bruk de tiltenkte endringene.
4. Send den fullstendige redigerbare representasjonen til det samsvarende typespesifikke PUT-endepunktet.

Bruk newName når det tekniske navnet må endres. Referanser oppdateres som en del av endre navn flyten. Standard påloggingsautentiseringsmetode kalt login kan ikke gis nytt navn eller slettes.

Klienthemmeligheter, klientnøkler og noen eksterne API-hemmeligheter administreres av dedikerte endepunkter. De er bevisst ikke returnert som klartekst i den generelle partirepresentasjonen og bør ikke kopieres inn i en vanlig oppdateringsforespørsel.

Koble applikasjoner til autentiseringsmetoder

En applikasjons allowUpParties-samling kontrollerer hvilke autentiseringsmetoder som kan brukes for å logge på det programmet. De refererte autentiseringsmetodene må eksistere i samme miljø og være kompatible med konfigurasjonen.

Behandle dette forholdet som en del av programmets komplette konfigurasjon når du oppdaterer det. Sletting av en autentiseringsmetode kan endre påloggingsrutingen for applikasjoner som refererer til den. bekrefte avhengige applikasjoner før sletting. Bruk en Environment Link når autentiseringsmetoden eller applikasjonen er tilkoblet på tvers av FoxIDs miljøer.

Administrer hemmeligheter og nøkler

OAuth 2.0- og OpenID Connect-applikasjoner gir dedikerte klienthemmelige operasjoner. En hemmelighet aksepteres når den opprettes, lagres som en hash, og returneres ikke i ren tekst. Listesvaret inneholder identifikatorene og sikker informasjon som trengs for å administrere eksisterende hemmeligheter.

Bruk overlappende legitimasjon for rotasjon:

1. Generer en ny klienthemmelighet og oppbevar den sikkert.
2. Opprett klienthemmeligheten i FoxIDs og distribuer den samme verdien til den forbrukende applikasjonen.
3. Bekreft at applikasjonen bruker den nye hemmeligheten.
4. Slett den gamle hemmeligheten etter applikasjonen og hemmelige identifikatorer.

OpenID Connect og OAuth 2.0 autentiseringsmetoder kan bruke dedikerte klienthemmelige eller klientnøkkeloperasjoner, avhengig av den valgte klientautentiseringsmetoden. En privatnøkkeloperasjon godtar sertifikater og privatnøkkelmateriale. External Login har et dedikert hemmelig endepunkt. Bruk det nøyaktige endepunktet og forespørselsskjemaet vist i Swagger for den valgte registreringstypen.

Hemmeligheter, private nøkler og komplette sertifikatnyttelaster er sensitive. Bruk TLS, gi tilgang kun til pålitelige automatiseringsklienter, beskytt verdier i hvile, og logg ikke forespørsels- eller svarinstanser.

Metadata og oppdagelseshjelpere

Protokollhjelpeoperasjoner reduserer manuell konfigurasjon, men erstatter ikke validering av den resulterende ressursen:

• OpenID Connect og OAuth 2.0 autentiseringsmetoder kan lese metadata for oppdagelse og fylle ut kompatible innstillinger.
• SAML 2.0 applikasjonsregistreringer og autentiseringsmetoder kan lese metadata.
• WS-Federation applikasjonsregistreringer og autentiseringsmetoder kan lese metadata.
• WS-Federation autentiseringsmetoder inkluderer en Microsoft Entra ID-synkroniseringshjelp.

Etter å ha brukt en hjelper, inspiser den returnerte konfigurasjonen, bruk lokale retningslinjer og kravinnstillinger, og lagre den gjennom det typespesifikke endepunktet for opprettelse eller oppdatering. Metadata kan endres over tid, så definer om synkronisering er en eksplisitt administrativ handling eller en kontrollert tilbakevendende prosess.

Sletting og avhengighetseffekter

Sletting av en applikasjon stopper nye protokollforespørsler for den applikasjonen. Sletting av en autentiseringsmetode kan hindre programmer i å fullføre pålogging og kan endre Home Realm Discovery valg. Fjern eller oppdater avhengigheter først, og behandle begge operasjonene som permanente konfigurasjonsendringer.

Forespørsler om opprettelse, oppdatering, hemmelig/nøkkel, hjelper og sletting er inkludert i kontrollrevisjonsloggen. Leseoperasjoner skrives ikke som revisjonshendelser.

Vanlige feilsvar

• 400 Bad Request når protokollinnstillinger, referanser, metadata, hemmeligheter, nøkler eller navn er ugyldige, eller en plangrense er nådd.
• 401 Unauthorized når tilgangstokenet mangler eller er ugyldig.
• 403 Forbidden når den som ringer mangler den nødvendige rettigheten til parten.
• 404 Not Found når den valgte registreringen, hemmeligheten eller nøkkelen ikke eksisterer.
• 409 Conflict når et teknisk navn eller en hemmelig identifikator allerede eksisterer.
• 423 Locked når en planbegrenset opprettelsesoperasjon er midlertidig låst.

Bruk svarteksten for valideringsdetaljer og Swagger UI for svarene deklarert av hver operasjon.

Relatert dokumentasjon

• Control API autentisering og tilgangsrettigheter
• Applikasjoner
• Autentiseringsmetoder
• Environment Link
• Krav og kravtransformasjoner