Control API - applikationer och autentiseringsmetoder

Använd FoxIDs Control API för att konfigurera de program som litar på FoxIDs och autentiseringsmetoderna FoxIDs litar på. I Control API rutter och scheman kallas en applikationsregistrering en downparty och en autentiseringsmetod kallas en upparty.

Innan du anropar dessa åtgärder, konfigurera Control API autentisering och åtkomsträttigheter. Swagger förblir den exakta referensen för protokollspecifika egenskaper, valideringsregler, hjälpoperationer och svarsscheman:

• Swagger (OpenAPI) JSON
• Swagger UI

Slutpunktsbas och åtkomsträttigheter

Exemplen använder FoxIDs Cloud:

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

Ersätt {tenant_name} och {track_name} med de tekniska namnen tenant och miljön. Ändra värd för en självvärd driftsättning. Skicka åtkomsttoken Control API i rubriken Authorization: Bearer {access_token}.

Dessa åtgärder kräver en party-åtkomsträttighet för målmiljön. Ge endast den nödvändiga read-, create-, update- eller delete-operationen genom Control API åtkomsträttshierarkin.

Lista och identifiera registreringar

Använd dessa slutpunkter för att upptäcka registreringar innan du anropar en typspecifik slutpunkt:

Listsvaren innehåller säkra sammanfattningar, registreringstypen och en ogenomskinlig pagineringstoken. Använd den typspecifika get-operationen för den fullständiga redigerbara representationen. Upprepa en sidnumrerad begäran med samma filter och den returnerade token tills ingen token returneras.

Den tekniska name är den stabila identifieraren som används av hämta, uppdatera, ta bort, hemlig, nyckel och relationsoperationer. Namnen är små bokstäver. Ange ett namn vid skapa när en integration kräver en förutsägbar identifierare, eller låt FoxIDs generera en. Använd hjälpen !newpartyname när ett unikt namn behövs innan en resurs skapas.

Typspecifika operationer

Varje resurstyp har sin egen slutpunkt eftersom protokollkonfigurationen skiljer sig åt. De huvudsakliga slutpunkterna är:

De vanliga åtgärderna är GET ?name={name}, POST att skapa, PUT att uppdatera och DELETE ?name={name}. Lägg till slutpunkten till slutpunktsbasen. Konsultera Swagger för de åtgärder som stöds av varje typ.

Att skapa applikationer eller autentiseringsmetoder är föremål för miljön och tenant plangränser. Vissa samtidiga planbegränsade skapande operationer kan returnera 423 Locked; försök igen efter en kort fördröjning.

Uppdatera och byt namn på säkert

Party PUT-operationer är fullständiga uppdateringar, inte patchar. Använd detta arbetsflöde:

1. Lista resurserna eller hämta den kända resursen efter tekniskt namn.
2. Få dess fullständiga typspecifika representation.
3. Bevara fastigheter som ska förbli oförändrade och tillämpa avsedda ändringar.
4. Skicka den fullständiga redigerbara representationen till den matchande typspecifika PUT-slutpunkten.

Använd newName när det tekniska namnet måste ändras. Referenser uppdateras som en del av namnbyteflödet. Standardinloggningsautentiseringsmetoden med namnet login kan inte bytas om eller raderas.

Klienthemligheter, klientnycklar och vissa externa API-hemligheter hanteras av dedikerade slutpunkter. De returneras inte medvetet som klartext i den allmänna partirepresentationen och bör inte kopieras till en normal uppdateringsbegäran.

Anslut applikationer till autentiseringsmetoder

Ett programs allowUpParties-samling styr vilka autentiseringsmetoder som kan användas för att logga in på det programmet. De refererade autentiseringsmetoderna måste finnas i samma miljö och vara kompatibla med konfigurationen.

Behandla detta förhållande som en del av programmets fullständiga konfiguration när du uppdaterar det. Att ta bort en autentiseringsmetod kan ändra inloggningsrutten för applikationer som refererar till den. verifiera beroende applikationer före radering. Använd en Environment Link när autentiseringsmetoden eller applikationen är avsiktligt ansluten mellan FoxIDs miljöer.

Hantera hemligheter och nycklar

Apparna OAuth 2.0 och OpenID Connect tillhandahåller dedikerade klienthemliga operationer. En hemlighet accepteras när den skapas, lagras som en hash och returneras inte i klartext. Listsvaret innehåller identifierarna och säker information som behövs för att hantera befintliga hemligheter.

Använd överlappande autentiseringsuppgifter för rotation:

1. Skapa en ny klienthemlighet och lagra den säkert.
2. Skapa klienthemligheten i FoxIDs och distribuera samma värde till den konsumerande applikationen.
3. Kontrollera att programmet använder den nya hemligheten.
4. Ta bort den gamla hemligheten genom dess applikation och hemliga identifierare.

Autentiseringsmetoderna OpenID Connect och OAuth 2.0 kan använda dedikerade klienthemliga eller klientnyckeloperationer, beroende på vald klientautentiseringsmetod. En operation med privat nyckel accepterar certifikat och material med privat nyckel. External Login har en dedikerad hemlig slutpunkt. Använd det exakta slutpunkts- och begäranschemat som visas i Swagger för den valda registreringstypen.

Hemligheter, privata nycklar och kompletta certifikatnyttolaster är känsliga. Använd TLS, ge åtkomst endast till betrodda automatiseringsklienter, skydda värden i vila och logga inte förfrågnings- eller svarsinstanser.

Metadata och upptäcktshjälpmedel

Protokollhjälparoperationer minskar manuell konfiguration men ersätter inte validering av den resulterande resursen:

• Autentiseringsmetoderna OpenID Connect och OAuth 2.0 kan läsa upptäcktsmetadata och fylla i kompatibla inställningar.
• SAML 2.0 applikationsregistreringar och autentiseringsmetoder kan läsa metadata.
• WS-Federation applikationsregistreringar och autentiseringsmetoder kan läsa metadata.
• WS-Federation autentiseringsmetoder inkluderar en Microsoft Entra ID-synkroniseringshjälp.

Efter att ha använt en hjälpare, inspektera den returnerade konfigurationen, tillämpa lokala policy- och anspråksinställningar och spara den genom den typspecifika skapa eller uppdatera slutpunkten. Metadata kan förändras över tid, så definiera om synkronisering är en explicit administrativ åtgärd eller en kontrollerad återkommande process.

Ta bort och beroende effekter

Om du tar bort ett program stoppas nya protokollförfrågningar för det programmet. Att ta bort en autentiseringsmetod kan förhindra att applikationer slutför inloggningen och kan ändra Home Realm Discovery val. Ta bort eller uppdatera beroenden först och behandla båda operationerna som permanenta konfigurationsändringar.

Skapa, uppdatera, hemlig/nyckel, hjälpare och ta bort förfrågningar ingår i kontrollgranskningsloggen. Läsoperationer skrivs inte som revisionshändelser.

Vanliga felsvar

• 400 Bad Request när protokollinställningar, referenser, metadata, hemligheter, nycklar eller namn är ogiltiga eller en plangräns har nåtts.
• 401 Unauthorized när åtkomsttoken saknas eller är ogiltig.
• 403 Forbidden när den som ringer saknar den åtkomsträttigheter som krävs.
• 404 Not Found när den valda registreringen, hemligheten eller nyckeln inte finns.
• 409 Conflict när ett tekniskt namn eller en hemlig identifierare redan finns.
• 423 Locked när en planbegränsad skapandeåtgärd är tillfälligt låst.

Använd svarstexten för valideringsdetaljer och Swagger UI för svaren som deklareras av varje operation.

Relaterad dokumentation

• Control API autentisering och åtkomsträttigheter
• Ansökningar
• Autentiseringsmetoder
• Environment Link
• Anspråk och anspråksomvandlingar