Control API - aplikacje i metody uwierzytelniania

Użyj opcji FoxIDs Control API, aby skonfigurować aplikacje ufające FoxIDs i metody uwierzytelniania, którym ufa FoxIDs. W Control API trasach i schematach rejestracja aplikacji nazywa się downparty, a metoda uwierzytelniania nazywa się upparty.

Przed wywołaniem tych operacji skonfiguruj Control API uwierzytelnianie i prawa dostępu. Swagger pozostaje dokładnym odniesieniem do właściwości specyficznych protokołu, reguł sprawdzania poprawności, operacji pomocniczych i schematów odpowiedzi:

• Swagger (OpenAPI) JSON
• Swagger UI

Baza punktów końcowych i prawa dostępu

W przykładach zastosowano FoxIDs Cloud:

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

Zastąp {tenant_name} i {track_name} nazwami technicznymi tenant i środowiska. Zmień hosta dla wdrożenia samodzielnego. Wyślij token dostępu Control API w nagłówku Authorization: Bearer {access_token}.

Te operacje wymagają prawa dostępu party dla środowiska docelowego. Udziel tylko wymaganej operacji read, create, update lub delete za pośrednictwem Control API hierarchii praw dostępu.

Wymień i zidentyfikuj rejestracje

Użyj tych punktów końcowych, aby wykryć rejestracje przed wywołaniem punktu końcowego specyficznego dla typu:

Odpowiedzi na liście zawierają bezpieczne podsumowania, typ rejestracji i nieprzezroczysty token paginacji. Użyj specyficznej dla typu operacji get, aby uzyskać pełną edytowalną reprezentację. Powtarzaj żądanie podzielone na strony z tymi samymi filtrami i zwróconym tokenem, dopóki nie zostanie zwrócony żaden token.

Techniczny name to stabilny identyfikator używany przez operacje pobierania, aktualizacji, usuwania, sekretu, klucza i relacji. Imiona pisane małymi literami. Podaj nazwę podczas tworzenia, gdy integracja wymaga przewidywalnego identyfikatora, lub pozwól, aby FoxIDs go wygenerował. Użyj pomocnika !newpartyname, gdy przed utworzeniem zasobu wymagana jest unikalna nazwa.

Operacje specyficzne dla typu

Każdy typ zasobu ma swój własny punkt końcowy, ponieważ konfiguracja protokołu jest inna. Główne punkty końcowe to:

Typowe operacje to GET ?name={name}, POST tworzenie, PUT aktualizacja i DELETE ?name={name}. Dołącz punkt końcowy do bazy punktu końcowego. Informacje na temat operacji obsługiwanych przez każdy typ można znaleźć w witrynie Swagger.

Tworzenie aplikacji lub metod uwierzytelniania podlega ograniczeniom środowiska i planu tenant. Niektóre współbieżne operacje tworzenia ograniczone do planu mogą zwracać wartość 423 Locked; spróbuj ponownie po krótkim opóźnieniu.

Bezpiecznie aktualizuj i zmieniaj nazwę

Operacje Party PUT to pełne aktualizacje, a nie łatki. Użyj tego przepływu pracy:

1. Wymień zasoby lub uzyskaj znany zasób według nazwy technicznej.
2. Uzyskaj pełną reprezentację specyficzną dla typu.
3. Zachowaj właściwości, które powinny pozostać niezmienione i zastosuj zamierzone zmiany.
4. Wyślij kompletną, edytowalną reprezentację do pasującego punktu końcowego PUT specyficznego dla typu.

Użyj newName, gdy nazwa techniczna musi się zmienić. Odniesienia są aktualizowane w ramach procesu zmiany nazwy. Nie można zmienić nazwy ani usunąć domyślnej metody uwierzytelniania logowania o nazwie login.

Sekrety klienta, klucze klienta i niektóre zewnętrzne sekrety API są zarządzane przez dedykowane punkty końcowe. Celowo nie są one zwracane w postaci zwykłego tekstu w oświadczeniu strony ogólnej i nie należy ich kopiować w ramach zwykłego żądania aktualizacji.

Połącz aplikacje z metodami uwierzytelniania

Kolekcja allowUpParties aplikacji kontroluje, jakich metod uwierzytelniania można używać do logowania się do tej aplikacji. Wymienione metody uwierzytelniania muszą istnieć w tym samym środowisku i być zgodne z konfiguracją.

Traktuj tę relację jako część pełnej konfiguracji aplikacji podczas jej aktualizacji. Usunięcie metody uwierzytelniania może zmienić routing logowania dla aplikacji, które się do niej odwołują; sprawdź zależne aplikacje przed usunięciem. Użyj Environment Link, jeśli metoda uwierzytelniania lub aplikacja jest celowo połączona w środowiskach FoxIDs.

Zarządzaj sekretami i kluczami

Aplikacje OAuth 2.0 i OpenID Connect zapewniają dedykowane operacje na tajnych klientach. Sekret jest akceptowany po utworzeniu, przechowywany jako skrót i nie jest zwracany w postaci zwykłego tekstu. Odpowiedź na liście zawiera identyfikatory i bezpieczne informacje potrzebne do zarządzania istniejącymi sekretami.

Użyj nakładających się danych uwierzytelniających do rotacji:

1. Wygeneruj nowy sekret klienta i przechowuj go bezpiecznie.
2. Utwórz klucz tajny klienta w FoxIDs i wdróż tę samą wartość w aplikacji korzystającej.
3. Sprawdź, czy aplikacja używa nowego klucza tajnego.
4. Usuń stary sekret według jego aplikacji i identyfikatorów sekretu.

Metody uwierzytelniania OpenID Connect i OAuth 2.0 mogą wykorzystywać dedykowane operacje na kluczu klienta lub kluczu klienta, w zależności od wybranej metody uwierzytelniania klienta. Operacja na kluczu prywatnym akceptuje certyfikat i materiał klucza prywatnego. External Login ma dedykowany tajny punkt końcowy. Użyj dokładnego punktu końcowego i schematu żądania pokazanego w Swagger dla wybranego typu rejestracji.

Sekrety, klucze prywatne i pełne ładunki certyfikatów są poufne. Używaj protokołu TLS, udzielaj dostępu tylko zaufanym klientom automatyzacji, chroń wartości w spoczynku i nie rejestruj treści żądań ani odpowiedzi.

Pomocnicy metadanych i odkrywania

Operacje pomocnicze protokołu ograniczają ręczną konfigurację, ale nie zastępują sprawdzania poprawności wynikowego zasobu:

• Metody uwierzytelniania OpenID Connect i OAuth 2.0 mogą odczytywać metadane wykrywania i wypełniać zgodne ustawienia.
• Rejestracje aplikacji i metody uwierzytelniania SAML 2.0 mogą odczytywać metadane.
• Rejestracje aplikacji i metody uwierzytelniania WS-Federation mogą odczytywać metadane.
• Metody uwierzytelniania WS-Federation obejmują pomocnika synchronizacji Microsoft Entra ID.

Po użyciu pomocnika sprawdź zwróconą konfigurację, zastosuj zasady lokalne i ustawienia roszczeń, a następnie zapisz je za pomocą punktu końcowego tworzenia lub aktualizacji specyficznego dla typu. Metadane mogą zmieniać się w czasie, dlatego należy określić, czy synchronizacja jest wyraźną czynnością administracyjną, czy kontrolowanym procesem powtarzającym się.

Usuń i efekty zależności

Usunięcie aplikacji powoduje zatrzymanie nowych żądań protokołu dla tej aplikacji. Usunięcie metody uwierzytelniania może uniemożliwić aplikacjom ukończenie logowania i wpłynąć na zmianę opcji Home Realm Discovery. Najpierw usuń lub zaktualizuj zależności i traktuj obie operacje jako trwałe zmiany konfiguracji.

Żądania tworzenia, aktualizacji, sekretu/klucza, pomocy i usuwania są uwzględniane w dzienniku audytu kontroli. Operacje odczytu nie są zapisywane jako zdarzenia kontroli.

Typowe reakcje na błędy

• 400 Bad Request, gdy ustawienia protokołu, odniesienia, metadane, klucze tajne, klucze lub nazwy są nieprawidłowe lub osiągnięto limit planu.
• 401 Unauthorized, gdy brakuje tokena dostępu lub jest on nieprawidłowy.
• 403 Forbidden, gdy rozmówca nie ma wymaganych uprawnień dostępu dla strony.
• 404 Not Found, gdy wybrana rejestracja, sekret lub klucz nie istnieje.
• 409 Conflict, gdy istnieje już nazwa techniczna lub tajny identyfikator.
• 423 Locked, gdy operacja tworzenia ograniczona planem jest tymczasowo zablokowana.

Użyj treści odpowiedzi, aby uzyskać szczegółowe informacje dotyczące sprawdzania poprawności, oraz Swagger UI w przypadku odpowiedzi zadeklarowanych przez każdą operację.

Powiązana dokumentacja

• Control API prawa uwierzytelniania i dostępu
• Aplikacje
• Metody uwierzytelniania
• Environment Link
• Roszczenia i przekształcenia roszczeń