Control API - applikationer og autentificeringsmetoder

Brug FoxIDs Control API til at konfigurere de applikationer, der har tillid til FoxIDs, og de autentificeringsmetoder, som FoxIDs har tillid til. I Control API-ruter og -skemaer kaldes en applikationsregistrering en downparty, og en autentificeringsmetode kaldes en upparty.

Før du kalder disse handlinger, konfigurer Control API-godkendelse og adgangsrettigheder. Swagger forbliver den nøjagtige reference for protokolspecifikke egenskaber, valideringsregler, hjælperoperationer og svarskemaer:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-base og adgangsrettigheder

Eksemplerne bruger FoxIDs Cloud:

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

Erstat {tenant_name} og {track_name} med tenant og miljøets tekniske navne. Skift vært for en selv-hostet implementering. Send Control API-adgangstokenet i Authorization: Bearer {access_token}-overskriften.

Disse handlinger kræver en party-adgangsrettighed til målmiljøet. Giv kun den påkrævede read-, create-, update- eller delete-handling gennem Control API adgangsrethierarkiet.

List og identificer registreringer

Brug disse endepunkter til at finde registreringer, før du kalder et typespecifikt endepunkt:

Listesvarene indeholder sikre oversigter, registreringstypen og et uigennemsigtigt pagineringstoken. Brug den typespecifikke get-operation til den komplette redigerbare repræsentation. Gentag en pagineret anmodning med de samme filtre og det returnerede token, indtil der ikke returneres noget token.

Den tekniske name er den stabile identifikator, der bruges af handlinger for hent, opdatering, sletning, hemmelighed, nøgle og relationer. Navne er med små bogstaver. Angiv et navn ved oprettelse, når en integration kræver en forudsigelig identifikator, eller lad FoxIDs generere en. Brug !newpartyname-hjælperen, når der kræves et unikt navn, før en ressource oprettes.

Typespecifikke operationer

Hver ressourcetype har sit eget endpoint, fordi protokolkonfigurationen er forskellig. De vigtigste endpoints er:

De sædvanlige operationer er GET ?name={name}, POST til oprettelse, PUT til opdatering og DELETE ?name={name}. Føj endpointet til endpoint-basen. Se Swagger for de operationer, der understøttes af hver type.

Oprettelse af applikationer eller godkendelsesmetoder er underlagt miljø- og tenant-plangrænserne. Nogle samtidige plan-begrænsede oprettelseshandlinger kan returnere 423 Locked; prøv igen efter en kort forsinkelse.

Opdater og omdøb sikkert

Party PUT-handlinger er komplette opdateringer, ikke patches. Brug denne arbejdsgang:

1. List ressourcerne eller få den kendte ressource efter teknisk navn.
2. Få dens komplette typespecifikke repræsentation.
3. Bevar egenskaber, der skal forblive uændrede, og anvend de tilsigtede ændringer.
4. Send den komplette redigerbare repræsentation til det tilsvarende typespecifikke PUT-endpoint.

Brug newName, når det tekniske navn skal ændres. Referencer opdateres som en del af omdøbningsflowet. Standard Login-autentificeringsmetoden med navnet login kan ikke omdøbes eller slettes.

Client secrets, client keys og nogle eksterne API-secrets administreres via dedikerede endpoints. De returneres bevidst ikke som klartekst i den generelle party-repræsentation og bør ikke kopieres til en normal opdateringsanmodning.

Forbind applikationer til autentificeringsmetoder

En applikations allowUpParties-samling styrer, hvilke autentificeringsmetoder der kan bruges til login i applikationen. De refererede autentificeringsmetoder skal findes i samme miljø og være kompatible med konfigurationen.

Behandl relationen som en del af applikationens komplette konfiguration ved opdatering. Sletning af en autentificeringsmetode kan ændre login-routing for applikationer, der refererer til den. Kontroller afhængige applikationer før sletning. Brug Environment Link, når autentificeringsmetoden eller applikationen med vilje er forbundet på tværs af FoxIDs-miljøer.

Administrer hemmeligheder og nøgler

OAuth 2.0 og OpenID Connect applikationer giver dedikerede klienthemmelige operationer. En hemmelighed accepteres, når den oprettes, gemmes som en hash og returneres ikke i almindelig tekst. Listesvaret indeholder identifikatorerne og sikre oplysninger, der er nødvendige for at administrere eksisterende hemmeligheder.

Brug overlappende legitimationsoplysninger til rotation:

1. Generer en ny klienthemmelighed og gem den sikkert.
2. Opret klienthemmeligheden i FoxIDs, og implementer den samme værdi til den forbrugende applikation.
3. Bekræft, at applikationen bruger den nye hemmelighed.
4. Slet den gamle hemmelighed ved dens applikation og hemmelige identifikatorer.

OpenID Connect- og OAuth 2.0-godkendelsesmetoderne kan bruge dedikerede klienthemmelige eller klientnøgleoperationer, afhængigt af den valgte klientgodkendelsesmetode. En privatnøgleoperation accepterer certifikat og privatnøglemateriale. External Login har et dedikeret hemmeligt slutpunkt. Brug det nøjagtige slutpunkt og anmodningsskema vist i Swagger for den valgte registreringstype.

Hemmeligheder, private nøgler og komplette certifikater er følsomme. Brug TLS, giv kun adgang til betroede automatiseringsklienter, beskyt værdier i hvile, og log ikke anmodnings- eller svarinstanser.

Metadata og opdagelseshjælpere

Protokolhjælpeoperationer reducerer manuel konfiguration, men erstatter ikke validering af den resulterende ressource:

• OpenID Connect- og OAuth 2.0-godkendelsesmetoder kan læse metadata for opdagelse og udfylde kompatible indstillinger.
• SAML 2.0 applikationsregistreringer og godkendelsesmetoder kan læse metadata.
• WS-Federation applikationsregistreringer og godkendelsesmetoder kan læse metadata.
• WS-Federation-godkendelsesmetoder omfatter en Microsoft Entra ID-synkroniseringshjælper.

Efter at have brugt en hjælper, skal du inspicere den returnerede konfiguration, anvende lokale politik- og kravindstillinger og gemme den gennem det typespecifikke oprettelse eller opdatering af slutpunkt. Metadata kan ændre sig over tid, så definer, om synkronisering er en eksplicit administrativ handling eller en kontrolleret tilbagevendende proces.

Slet- og afhængighedseffekter

Sletning af en applikation stopper nye protokolanmodninger for den applikation. Sletning af en godkendelsesmetode kan forhindre applikationer i at fuldføre login og kan ændre Home Realm Discovery valg. Fjern eller opdater afhængigheder først, og behandl begge operationer som permanente konfigurationsændringer.

Anmodninger om oprettelse, opdatering, secrets/keys, hjælpeoperationer og sletning medtages i Control-auditloggen. Læseoperationer skrives ikke som audithændelser.

Almindelige fejlsvar

• 400 Bad Request når protokolindstillinger, referencer, metadata, hemmeligheder, nøgler eller navne er ugyldige, 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 partadgangsrettighed.
• 404 Not Found når den valgte registrering, hemmelighed eller nøgle ikke eksisterer.
• 409 Conflict, når der allerede findes et teknisk navn eller hemmelig identifikator.
• 423 Locked nå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.

Relateret dokumentation

• Control API godkendelse og adgangsrettigheder
• Applikationer
• Godkendelsesmetoder
• Environment Link
• Krav og kravtransformationer