Transformacje oświadczeń i zadania oświadczeń

Każda metoda uwierzytelniania i rejestracja aplikacji FoxIDs obsługuje oświadczenia oraz transformacje oświadczeń i zadania oświadczeń. Oznacza to, że dla każdego uwierzytelnienia użytkownika można wykonać wiele zestawów transformacji i zadań oświadczeń. Najpierw transformacje i zadania oświadczeń są wykonywane w metodzie uwierzytelniania, a następnie w rejestracji aplikacji.

Dodatkowe podzbiory transformacji i zadań oświadczeń mogą być wykonywane, jeśli tworzony jest użytkownik wewnętrzny lub zewnętrzny.

Claim transform flow diagram

W metodach uwierzytelniania z listą Forward claims dodaj do niej zwykłe claimy utworzone przez transformacje pierwszego poziomu, aby udostępnić je w kolejnych krokach, lub uwzględnij * (domyślnie). Metody Login przekazują te claimy bez tej listy.

Zarezerwowane prefiksy _local:, _internal:, _session: i _impersonate: określają sposób użycia claims podczas uwierzytelniania. Różne okresy ich dostępności opisano w sekcji Claims lokalne, wewnętrzne i sesyjne.

Aby wystawić zwykły claim z rejestracji aplikacji, dodaj go lub * do Issue claims. W OpenID Connect możesz też dodać go do Voluntary claims zakresu i zażądać tego zakresu z aplikacji. Zarezerwowane claimy nie są wystawiane, nawet z *.

Zobacz przykłady transformacji oświadczeń.

Włącz Log claim trace w ustawieniach logów, aby zobaczyć oświadczenia przed i po transformacji w logach.

Transformacje oświadczeń można skonfigurować w metodzie uwierzytelniania login.

FoxIDs authentication method claim transform

I zadania oświadczeń.

FoxIDs authentication method claim task

Podobnie transformacje i zadania oświadczeń można skonfigurować jako pierwszego i drugiego poziomu w metodzie uwierzytelniania OpenID Connect.

FoxIDs application registration claim transform

Oświadczenia są domyślnie reprezentowane jako oświadczenia JWT. Jeśli metodą uwierzytelniania jest SAML 2.0, oświadczenia pierwszego poziomu są reprezentowane jako oświadczenia SAML 2.0. Jeśli rejestracją aplikacji jest SAML 2.0, oświadczenia są reprezentowane jako oświadczenia SAML 2.0.

Transformacja oświadczeń i zadanie oświadczeń wykonują jedną z maksymalnie siedmiu akcji w zależności od typu transformacji lub zadania.

Akcje transformacji i zadań oświadczeń:

  • Add claim - dodaj nowe oświadczenie
  • Add claim, if not match - wykonaj dodanie, jeśli warunek nie pasuje
  • Replace claim - dodaj nowe oświadczenie i usuń istniejące, jeśli jedno lub więcej istnieje
  • Replace claim, if not match - wykonaj zamianę, jeśli warunek nie pasuje
  • Remove claim - usuń oświadczenia, jeśli jedno lub więcej istnieje
  • If match - wykonaj akcję, jeśli warunek pasuje
  • If not match - wykonaj akcję, jeśli warunek nie pasuje

Transformacje i zadania oświadczeń są wykonywane w kolejności, więc akcje są wykonywane sekwencyjnie. Oznacza to, że można utworzyć zmienną lokalną, dodając oświadczenie, a później podejmować decyzje na podstawie tego oświadczenia. Oświadczenie jest lokalne w zestawie transformacji i zadań oświadczeń, jeśli zaczyna się od _local:.

Gdy transformacje i zadania oświadczeń są uruchamiane w przepływie logowania, FoxIDs automatycznie dodaje lokalne oświadczenia z żądania logowania przed wykonaniem transformacji. Te oświadczenia _local: są przeznaczone do decyzji wewnątrz sekwencji transformacji/zadań i są usuwane z wyniku.

Ogólne lokalne claimy dodawane z żądania logowania:

  • _local:login_action - akcja żądania logowania, zapisana jako camelCase
  • _local:user_id - identyfikator użytkownika z żądania logowania (tylko jeśli podany)
  • _local:max_age - maksymalny wiek z żądania logowania (tylko jeśli ustawiony i większy niż 0)
  • _local:login_hint - wskazówka logowania z żądania logowania (tylko jeśli podana)
  • _local:acr - wartości ACR z żądania logowania jako lista rozdzielona spacjami (tylko jeśli podane)
  • _local:params:{name} - dozwolony parametr żądania aplikacji, z nazwą parametru zapisaną małymi literami i jednym claimem na wartość (tylko jeśli został przekazany)

Gdy metoda uwierzytelniania jest używana jako element Advanced MFA, jej własne transformacje claimów otrzymują poniższe lokalne claimy dotyczące użytkownika już uwierzytelnionego przez metodę uwierzytelniania Login:

Claim Wartość
_local:mfa:user_id Stały techniczny identyfikator użytkownika FoxIDs.
_local:mfa:user_identifier Identyfikator użyty podczas uwierzytelniania Login. Jeśli go nie podano, FoxIDs używa adresu e-mail, numeru telefonu lub nazwy użytkownika.
_local:mfa:username Zarejestrowana nazwa użytkownika.
_local:mfa:email Zarejestrowany adres e-mail użytkownika lub wartość jego claimu email, jeśli zarejestrowany adres jest pusty.
_local:mfa:phone Zarejestrowany numer telefonu użytkownika lub wartość jego claimu phone_number, jeśli zarejestrowany numer jest pusty.

Dodawane są tylko claimy z niepustą wartością. Transformacje te przetwarzają claimy zwrócone przez zewnętrznego dostawcę tożsamości i mogą dodać wartość AMR wymaganą przez element MFA. Przepływ MFA metody Login używa przekształconej odpowiedzi do walidacji tej wartości AMR. Pozostałe claimy zwrócone przez metodę uwierzytelniania nie są łączone z claimami metody uwierzytelniania Login ani przekazywane do jej ogólnych transformacji claimów.

Akcja Add claim, if not match pozwala dodać oświadczenie (zmienną lokalną), jeśli inne oświadczenie lub jego wartość nie istnieje.

Typy claim transform obsługujące wszystkie akcje:

  • Match claim - sprawdza, czy wybrany typ claim istnieje. Dla akcji add i replace outgoing claim jest zapisywany z nową wartością, gdy claim istnieje. Akcje if not match są wykonywane, gdy claim nie istnieje. Akcja remove usuwa wybrany outgoing claim, gdy claim istnieje.
  • Match claim and value - sprawdza, czy wybrany typ claim istnieje z skonfigurowaną wartością. Dla akcji add i replace outgoing claim jest zapisywany z nową wartością, gdy typ i wartość pasują. Akcje if not match są wykonywane, gdy claim istnieje, ale wartość nie pasuje. Akcja remove usuwa wybrany outgoing claim, gdy typ i wartość pasują.
  • Regex match - sprawdza, czy wybrany typ claim istnieje i czy wartość pasuje do skonfigurowanego wyrażenia regularnego. Dla akcji add i replace outgoing claim jest zapisywany z nową wartością, gdy wyrażenie regularne pasuje. Akcje if not match są wykonywane, gdy claim istnieje, ale wartość nie pasuje do wyrażenia regularnego. Akcja remove usuwa wybrany outgoing claim, gdy wyrażenie regularne pasuje.

Typy claim transform obsługujące akcje Add claim, Replace claim i Add claim, if new claim does not exist:

  • Map - kopiuje wartość wybranego claim do outgoing claim. Przy Add claim, if new claim does not exist wartość jest zapisywana tylko wtedy, gdy outgoing claim jeszcze nie istnieje.
  • Regex map - wyodrębnia nazwaną grupę regex map z wartości wybranego claim i zapisuje wyodrębnioną wartość w outgoing claim. Przy Add claim, if new claim does not exist wartość jest zapisywana tylko wtedy, gdy outgoing claim jeszcze nie istnieje.

Typy claim transform obsługujące akcje Add claim i Replace claim:

  • Constant - zawsze zapisuje skonfigurowaną stałą wartość w outgoing claim.
  • Concatenate - buduje outgoing claim z wartości w wybranych claims. Format string używa placeholderów takich jak {0}, {1} i {2} dla wybranych wartości w kolejności.
  • External claims API - wysyła wybrane claims do zewnętrznego API. Claims zwrócone przez API są dodawane lub zastępują outgoing claims.
  • Impersonation - przygotowuje wybrany lokalny target jako użytkownika efektywnego po transformacjach metody uwierzytelniania. Zobacz Impersonacja.
  • DK XML privilege to JSON - konwertuje DK privilege XML claim na JSON claims, jeden claim dla każdego elementu XML PrivilegeGroup.

Typy claim task obsługujące akcje Add claim i Replace claim:

  • Query internal user - używa wartości lookup claim, aby znaleźć dokładnie jednego użytkownika wewnętrznego, a następnie dodaje lub zastępuje wybrane claims tego użytkownika w bieżącym claim set.
  • Query external user - używa wartości lookup claim, aby znaleźć dokładnie jednego użytkownika zewnętrznego, a następnie dodaje lub zastępuje wybrane claims tego użytkownika w bieżącym claim set.
  • Save claim on internal user - używa wartości lookup claim, aby znaleźć dokładnie jednego użytkownika wewnętrznego, a następnie dodaje lub zastępuje wybrany claim na tym użytkowniku wartościami z wybranego update value claim w bieżącym claim set.
  • Save claim on external user - używa wartości lookup claim, aby znaleźć dokładnie jednego użytkownika zewnętrznego, a następnie dodaje lub zastępuje wybrany claim na tym użytkowniku wartościami z wybranego update value claim w bieżącym claim set.

Wszystkie cztery zadania użytkownika wymienione powyżej traktują użytkownika jako niedostępnego, gdy konto jest wyłączone bezpośrednio lub przez aktywne członkostwo w strukturze dostępu. Użytkownik jest wykluczany, zanim FoxIDs ustali, czy wyszukiwanie znalazło dokładnie jednego użytkownika, dlatego zadania query nie dodają claims, a zadania save nie wprowadzają zmian.

Gdy którekolwiek z dwóch zadań query użytkownika jest wykonywane w metodzie uwierzytelniania i żadne konto lokalne nie jest jeszcze powiązane z bieżącą odpowiedzią uwierzytelniania, pierwszy jednoznacznie dopasowany użytkownik w kolejności wykonywania claim transforms staje się kontem lokalnym odpowiedzi. Zadanie Query internal user z ustawieniem Target dostarcza tylko lokalne claims i pozostawia to powiązanie konta bez zmian. Jeśli uwierzytelnianie jest kontynuowane przez kroki Extended UI, FoxIDs zachowuje migawkę dostępu wybranego konta w sekwencji po stronie serwera i używa jej podczas kończenia odpowiedzi. Następnie FoxIDs stosuje powiązanie do aktywnych sesji i grantów refresh token. Użytkownik wewnętrzny lub połączony użytkownik zewnętrzny uwierzytelniony bezpośrednio przez metodę uwierzytelniania ma pierwszeństwo, a istniejące powiązanie nigdy nie jest zastępowane przez późniejsze query.

Jeśli claim transform interaktywnie uruchamia inną metodę uwierzytelniania, przekierowane uwierzytelnianie działa jako nowy login flow. Powiązanie konta lokalnego wybrane przez wcześniejsze query nie jest przenoszone przez to przekierowanie.

Zadania query użytkownika w rejestracji aplikacji mogą dodawać claims, ale nie tworzą ani nie zmieniają powiązania konta lokalnego dla logowania.

Zadania query użytkownika udostępniają stabilny identyfikator wybranego użytkownika jako lokalny claim:

Claim task Lokalny claim Wartość
Query internal user _local:internal_user_id Stabilny techniczny identyfikator użytkownika FoxIDs dla wybranego użytkownika wewnętrznego.
Query external user _local:external_user_id Stabilny techniczny identyfikator FoxIDs dla wybranego użytkownika zewnętrznego.

Wybierz lokalny claim jawnie w outgoing claims zadania albo wybierz *, aby udostępnić go kolejnym transforms w tej samej sekwencji. Lokalne claims są usuwane z końcowego wyniku, chyba że ich wartość zostanie zmapowana do nielokalnego claim.

Na przykład po wyszukaniu użytkownika wewnętrznego według adresu e-mail lub nazwy użytkownika zadanie Match claim and return error może sprawdzić _local:internal_user_id i zatrzymać flow, jeśli nie znaleziono jednoznacznego użytkownika wewnętrznego. Transform Match claim może zamiast tego dodać inny claim tylko wtedy, gdy wyszukiwanie się powiedzie. Stabilny identyfikator użytkownika pozostaje lokalny dla sekwencji transforms, zapewniając jednocześnie wiarygodną podstawę dla kolejnych decyzji.

Dla Query internal user i Save claim on internal user lookup claim jest odczytywany z bieżącego claim set. Wartość Lookup claim on internal user określa sposób dopasowania użytkownika wewnętrznego:

  • sub dopasowuje user ID użytkownika wewnętrznego.
  • email, phone_number i preferred_username najpierw przeszukują identifiers użytkownika wewnętrznego z dopasowaniem bez rozróżniania wielkości liter tam, gdzie wielkość liter ma znaczenie. Jeśli użytkownik nie zostanie znaleziony przez identifier, wyszukiwanie jest kontynuowane w zapisanych claims użytkownika.
  • Następnie wyszukiwanie jest kontynuowane w zapisanych claims użytkownika wewnętrznego pod kątem tego samego typu claim i wartości pasującej bez rozróżniania wielkości liter. Dotyczy to wszystkich typów lookup claim, jeśli wcześniej nie znaleziono użytkownika.

Jeśli wyszukiwanie znajdzie dokładnie jednego użytkownika wewnętrznego, Query internal user dodaje lub zastępuje wybrane claims tego użytkownika w bieżącym claim set. Save claim on internal user dodaje lub zastępuje wybrany claim na tym użytkowniku wartościami z wybranego update value claim. Jeśli użytkownik nie zostanie znaleziony albo przez claims zostanie znaleziony więcej niż jeden użytkownik, żadne wewnętrzne user claims nie zostaną dodane ani zapisane.

Dla Query external user i Save claim on external user lookup claim jest odczytywany z bieżącego claim set i dopasowywany do wybranego zewnętrznego źródła użytkowników. Użyj link_claim jako lookup claim na użytkowniku zewnętrznym, aby dopasować wartość link claim użytkownika zewnętrznego.

Typy claim task obsługujące akcje If match i If not match:

  • Match claim and return error - zwraca błąd, jeśli typ claim pasuje lub nie pasuje.
  • Match claim and value and return error - zwraca błąd, jeśli typ i wartość claim pasują lub nie pasują.
  • Regex match and return error - zwraca błąd, jeśli typ i wartość claim pasują lub nie pasują do wyrażenia regularnego.
  • Match claim and log event - zapisuje wybraną wartość claim w logu, jeśli typ claim pasuje.
  • Match claim and start authentication - rozpoczyna nowy login flow przez zainicjowanie metody uwierzytelniania, jeśli typ claim pasuje lub nie pasuje.
  • Match claim and value and start authentication - rozpoczyna nowy login flow przez zainicjowanie metody uwierzytelniania, jeśli typ i wartość claim pasują lub nie pasują.
  • Regex match and start authentication - rozpoczyna nowy login flow przez zainicjowanie metody uwierzytelniania, jeśli typ i wartość claim pasują lub nie pasują do wyrażenia regularnego.

Dla return error tasks skonfiguruj błąd protokołu zwracany do klienta lub requester. Konfiguracje OpenID Connect i OAuth 2.0 zwracają error oraz opcjonalną error description. Konfiguracje SAML 2.0 zwracają SAML status code i message.

Start authentication claim tasks można użyć do step-up, gdy użytkownik jest zalogowany jednym czynnikiem i wymagany jest kolejny czynnik, albo gdy wymagane są dodatkowe informacje (claims).

Wczytywanie użytkownika wewnętrznego do lokalnych claims

Ustaw opcjonalne Target w zadaniu Query internal user, aby wczytać claims innego użytkownika do sprawdzenia lub transformacji, zachowując powiązanie logowania z kontem lokalnym. Wprowadź nazwę, taką jak target; FoxIDs dodaje _local: i umieszcza tę nazwę przed każdym wybranym typem claim:

Wybrany claim Lokalny wynik z Target target
sub _local:target:sub
email _local:target:email
role _local:target:role
_local:internal_user_id _local:target:_local:internal_user_id
_local:access_node _local:target:_local:access_node
_local:access_claim _local:target:_local:access_claim
_local:access_path_claim _local:target:_local:access_path_claim

Pełny oryginalny typ claim pozostaje zachowany pod nazwą target. Pozwala to odróżnić lokalne pomocnicze claims konta i Access Structure od zwykłych claims. Wyszukiwanie uwzględnia claims wynikające z aktywnych członkostw Access Structure zgodnie z ustawieniem Forward claims struktury oraz lokalne pomocnicze claims do sprawdzania członkostwa.

Wybierz claims według ich oryginalnych nazw w Claims from internal user lub użyj *. Pełna nazwa lokalnego claim, łącznie z prefiksem i nazwą target, musi mieścić się w limicie 100 znaków. Pozostaw Target puste, aby dodać lub zastąpić wybrane claims bezpośrednio w bieżącej kolekcji claims.

Wiele zapytań i wywołań Claims API może uzupełniać ten sam target. Add claim dodaje zwrócone wartości. Replace claim zastępuje wartości zwróconych typów claim w tym target i zachowuje pozostałe claims, które już się tam znajdują.

Używaj claims z target w kolejnych transformacjach tego samego zestawu. Na przykład sprawdź _local:target:role lub mapuj _local:target:sub na _internal:selected_user_id, aby zachować tę wartość dla późniejszych zestawów transformacji. Lokalne claims z target są usuwane na końcu zestawu.

Claimy lokalne, wewnętrzne i sesyjne

Użyj tych prefiksów, aby wybrać czas życia wartości używanej przez transformacje i zadania claimów. Zestaw transformacji to jedna uporządkowana lista transformacji i zadań, na przykład pierwszy poziom metody uwierzytelniania, lista Extended UI, drugi poziom albo lista rejestracji aplikacji. Przejście do innego zestawu ma znaczenie również wtedy, gdy oba należą do tej samej metody.

Prefiks Zastosowanie Dostępność wartości Dostępność przy późniejszym logowaniu do aplikacji?
_local: Tymczasowa wartość lub decyzja w jednym zestawie Kolejne transformacje i zadania tego samego zestawu. Usuwany po zakończeniu zestawu. Nie. FoxIDs może dostarczyć nowy lokalny kontekst żądania lub zadania w nowym zestawie.
_internal: Wartość potrzebna kolejnym zestawom bieżącego przepływu uwierzytelniania Transformacje metody, kontynuacje takie jak Extended UI oraz transformacje aplikacji. Usuwany, zanim odpowiedź protokołu opuści FoxIDs. Nie. Utwórz lub skopiuj wartość ponownie w nowym przepływie.
_session: Niewielka wartość zachowana dla tego samego uwierzytelnionego użytkownika Przywracany przed pierwszym poziomem; dostępny w transformacjach pośrednich i na drugim poziomie. Zapisywany po pomyślnym zakończeniu drugiego poziomu i usuwany przed transformacjami aplikacji. Tak, przez tę samą metodę uwierzytelniania, dopóki sesja użytkownika jest ważna.
_impersonate: Tożsamość docelowa przygotowana do impersonacji Transformacje metody uwierzytelniania i Extended UI do zakończenia impersonacji po transformacjach drugiego poziomu. Przygotuj użytkownika docelowego ponownie przy każdym logowaniu.

Przykładowo _local:customer_found może sterować kolejnym zadaniem tej samej listy, _internal:customer_category może zostać odczytany później przez transformację aplikacji, a _session:profileId może zachować wybrany profil do następnego logowania do aplikacji.

Transformacje tworzące powiązanego użytkownika zewnętrznego korzystają z claimów wybranych dla tego kroku oraz z bieżących claimów _session:. Wybierz claim _internal: jako dane wejściowe, jeśli transformacje tworzenia potrzebują jego wartości. Claimy sesyjne pozostają częścią przepływu uwierzytelniania i nie są zapisywane na koncie użytkownika zewnętrznego.

Transformacje takie jak Constant, Map, Match claim i Match claim and value mogą tworzyć lub używać tych claimów za pomocą swoich zwykłych działań. Prefiks określa czas życia. Używaj _session: w metodzie uwierzytelniania: claimy sesyjne utworzone przez transformacje aplikacji nie są zapisywane w sesji metody.

Kopiowanie wartości do innego czasu życia

Transformacja Map kopiuje wartość do wybranego claimu wyjściowego. Źródło i cel to osobne claimy o czasach życia wynikających z ich prefiksów. Gdy nazwy są różne, Replace claim zastępuje istniejące wartości claimu docelowego i zachowuje claim źródłowy. Późniejsza zmiana jednego nie aktualizuje automatycznie drugiego.

Na przykład po zwróceniu _local:internal_user_id przez zadanie Query internal user dodaj w tym samym zestawie transformację Map z _local:internal_user_id do _internal:selected_user_id. Kolejne zestawy mogą odczytać _internal:selected_user_id po usunięciu claimu lokalnego. Transformacja metody może podobnie skopiować wartość _internal: do claimu _session:, aby zachować ją do późniejszych logowań.

Przekazanie wartości sesyjnej do transformacji aplikacji

Załóżmy, że _session:profileId zawiera customer-456, a transformacje aplikacji potrzebują tej wartości. Skonfiguruj poniższą transformację na liście drugiego poziomu metody uwierzytelniania, po transformacjach zmieniających wybrany profil:

Ustawienie Wartość
Typ transformacji Map
Działanie Replace claim
Claim wejściowy _session:profileId
Claim wyjściowy _internal:profileId

Dalszy przepływ wygląda następująco:

  1. Oba claimy zawierają customer-456 podczas pozostałych transformacji metody.
  2. Po zakończeniu drugiego poziomu FoxIDs zapisuje _session:profileId do późniejszych logowań i usuwa go z bieżącej kolekcji claimów.
  3. _internal:profileId trafia do transformacji aplikacji. Może służyć do podejmowania decyzji bez wystawiania go aplikacji.
  4. Jeśli aplikacja potrzebuje wartości w tokenie lub asercji, dodaj w niej transformację Map z _internal:profileId do zwykłego claimu, takiego jak profile_id, i skonfiguruj jego wystawianie.

Przy następnym logowaniu do aplikacji FoxIDs przywraca _session:profileId dla tego samego uwierzytelnionego użytkownika. Transformacja metody tworzy nowy _internal:profileId dla tego przepływu. To samo podejście działa, gdy FoxIDs konwertuje claimy między JWT i SAML.

Przekazywanie, mapowanie protokołu i zewnętrzne API

Claimy wewnętrzne i sesyjne nie wymagają wpisu w Forward claims; ogólne limity długości nadal obowiązują. Zarezerwowane nazwy claimów nie zmieniają się przy mapowaniu protokołu JWT/SAML, również automatycznym. Do kopiowania wartości między prefiksami używaj transformacji claimu Map; mapowania protokołu nie mogą tworzyć zarezerwowanych typów claimów.

Żadna z trzech zarezerwowanych przestrzeni nazw nie jest wystawiana w tokenach ani asercjach, nawet z * w Issue claims. Są one też wykluczone z żądań i odpowiedzi zewnętrznego API claimów. Przed wysłaniem wybranej wartości do API zmapuj ją na zwykły claim, a następnie w razie potrzeby zmapuj zwykły claim odpowiedzi na zarezerwowany.

Prefiksy rozróżniają wielkość liter i są zarezerwowane przez FoxIDs. Zarezerwowane claimy otrzymane z protokołu lub API integracji są usuwane przed transformacjami. Te zapisane na istniejącym użytkowniku są ignorowane; zadania nie mogą ich zapisać na użytkowniku wewnętrznym ani zewnętrznym. Gdy zadanie uruchamia inną metodę uwierzytelniania, bieżąca kolekcja claimów nie jest przekazywana do nowego przepływu logowania.

Claimy sesyjne

Używaj claimów _session:, aby zachować niewielkie ilości stanu dla tego samego uwierzytelnionego użytkownika między logowaniami w przeglądarce do różnych aplikacji. Sesje muszą być włączone w metodzie uwierzytelniania; są włączone domyślnie. FoxIDs obsługuje claimy sesyjne dla Login, External Login, OpenID Connect, SAML 2.0, WS-Federation i Environment Link.

FoxIDs udostępnia zapisane claimy sesyjne przed transformacjami pierwszego poziomu. Pozostają dostępne podczas transformacji pośrednich, Extended UI i drugiego poziomu. Po pomyślnym zakończeniu tych transformacji FoxIDs zapisuje wynikowe claimy sesyjne. Usunięcie claimu sesyjnego w transformacji usuwa również jego zapisaną wartość. Aby użyć zapisanej wartości sesji w transformacjach aplikacji, skopiuj ją do claimu wewnętrznego przed zakończeniem metody uwierzytelniania.

Claimy sesyjne należą do pierwotnie uwierzytelnionego użytkownika, niezależnie od zmian sub w transformacjach. Są przywracane tylko przy zgodnym uwierzytelnionym subject i ważnej, aktywnej sesji tej samej metody. Metoda akceptująca wielu issuers musi otrzymywać wartości subject unikatowe wśród nich wszystkich. Zadanie uruchamiające uwierzytelnianie nie przekazuje claimów sesyjnych do innej metody; przepływy obsługujące tylko tokeny nie odczytują ani nie zapisują claimów sesji przeglądarki.

Login i External Login mogą ponownie użyć sesji przeglądarki. Metody oparte na protokołach zewnętrznych nadal uwierzytelniają u zewnętrznego dostawcy tożsamości przy każdym logowaniu do aplikacji; FoxIDs przywraca claimy sesyjne po sprawdzeniu zwróconej tożsamości. Claimy podlegają czasowi życia sesji metody i są niedostępne po wylogowaniu lub unieważnieniu sesji.

Gdy nowe logowanie weryfikuje tego samego użytkownika, a jego poprzednia sesja jest nadal ważna, FoxIDs zachowuje zapisane wartości tej sesji podczas transformacji claimów i Extended UI, aż transformacje drugiego poziomu zakończą się pomyślnie i zastąpią te wartości. Zakończone nowe logowanie rozpoczyna od nowa bezwzględny czas życia sesji metody uwierzytelniania; ponowne użycie sesji Login lub External Login podlega skonfigurowanemu kroczącemu i bezwzględnemu czasowi życia.

Login i External Login zachowują oryginalne claimy w sesji przeglądarki przed uruchomieniem transformacji claimów. Po pomyślnym zakończeniu transformacji drugiego poziomu FoxIDs aktualizuje claimy sesyjne uwierzytelnionego użytkownika, również po Extended UI. Ta aktualizacja zachowuje zwykłe claimy i termin wygaśnięcia sesji. Każda metoda uwierzytelniania utrzymuje w przeglądarce jednego bieżącego użytkownika i jeden zbiór claimów sesyjnych. Nowe logowanie przebiega zgodnie z normalnym działaniem sesji dla danej metody uwierzytelniania; przeglądarka używa ostatnio otrzymanego pliku cookie sesji.

Claimy sesyjne mają następujące limity przechowywania:

Limit Wartość
Nazwa claimu 100 znaków, w tym _session:, z prawidłową nazwą claimu JWT i nazwą po prefiksie, która nie jest pusta ani złożona wyłącznie z białych znaków
Pojedyncza wartość 1 000 znaków
Liczba claimów 10 par nazwa/wartość; każda wartość claimu wielowartościowego liczona jest osobno
Łączna długość wartości 2 000 znaków

Claimy z nieprawidłowymi nazwami, pustymi wartościami lub wartościami złożonymi tylko z białych znaków są pomijane. Dłuższe wartości są skracane. Claimy są rozpatrywane po kolei; zapis kończy się, gdy następny prawidłowy claim przekroczyłby limit liczby lub łącznej długości. Ogólna walidacja claimów w przepływie uwierzytelniania nadal obowiązuje.

Przykładowo transformacja metody uwierzytelniania może zachować odwołanie do dozwolonego użytkownika docelowego impersonacji w _session:impersonation_target_id. Kolejne logowania do aplikacji przez tę metodę mogą używać odwołania do wczytania użytkownika docelowego i ponownego sprawdzenia uprawnień. Pełny przykład opisano w sekcji Impersonacja.

Zewnętrzne oświadczenia - API

Możesz wywołać własne API z FoxIDs w ramach transformacji oświadczeń. API jest wywoływane z oświadczeniami, a oświadczenia zwrócone z API można dodać lub zastąpić. API jest wywoływane tylko wtedy, gdy istnieje co najmniej jedno wybrane oświadczenie. Możesz użyć *, aby wybrać i wysłać wszystkie oświadczenia do API.

Zarezerwowane claimy _local:, _internal:, _session: i _impersonate: są wykluczone z żądań i odpowiedzi API. Aby wymienić wybraną zarezerwowaną wartość, zmapuj ją na zwykły claim przed wywołaniem albo później zmapuj zwykły claim odpowiedzi na zarezerwowany.

Chronione oświadczenia, takie jak sid i auth_time, są odrzucane z odpowiedzi API. Pozostałe oświadczenia w odpowiedzi są przetwarzane zgodnie ze skonfigurowaną akcją.

Przykładowe zastosowania:

  • Wywołaj API z metody uwierzytelniania przy każdym uwierzytelnieniu użytkownika w FoxIDs lub u zewnętrznego dostawcy tożsamości. Możesz wtedy znaleźć użytkownika w bazie danych i zwrócić identyfikator użytkownika oraz np. identyfikator klienta lub inne istotne dane. Na przykład możesz też utworzyć użytkownika w swojej bazie danych.
  • Wywołaj API z rejestracji aplikacji z identyfikatorem użytkownika (sub) i pobierz role użytkownika z bazy danych. API może wtedy zwrócić pustą listę lub listę oświadczeń ról, albo bardziej złożoną strukturę uprawnień.

Wczytywanie claims z odpowiedzi API do lokalnych claims

Ustaw opcjonalne Target w External claims API, aby używać claims z odpowiedzi w kolejnych sprawdzeniach lub transformacjach. Gdy Target ma wartość target, claim o nazwie sub z odpowiedzi API staje się _local:target:sub, a role staje się _local:target:role. API zwraca zwykłe nazwy claims; FoxIDs dodaje lokalny prefiks po przefiltrowaniu i zweryfikowaniu odpowiedzi. Pełna nazwa lokalnego claim musi mieścić się w limicie 100 znaków. Pozostaw Target puste, aby dodawać lub zastępować claims z odpowiedzi bezpośrednio w bieżącej kolekcji claims.

Wiele wywołań API i zapytań o użytkowników wewnętrznych może uzupełniać ten sam target. Add claim dodaje zwrócone wartości. Replace claim zastępuje zwrócone typy claim w tym target i zachowuje pozostałe. Pusta odpowiedź pozostawia istniejące claims w target bez zmian.

Lokalne claims z target są dostępne w bieżącym zestawie transformacji. Mapuj wartość taką jak _local:target:sub na _internal:selected_user_id, aby używać jej w późniejszych zestawach.

Implementacja API

Musisz zaimplementować proste API, które FoxIDs wywołuje, gdy wykonywana jest transformacja oświadczeń. Zobacz kod przykładowy.

API ma bazowy URL, a funkcjonalność jest podzielona na foldery. Obecnie obsługiwany jest tylko folder claims (funkcjonalność) do żądania listy oświadczeń.

Jeśli bazowy URL API to https://somewhere.org/myclaimsstore, URL dla folderu claims będzie https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud wywołuje Twoje API z adresu IP 57.128.60.142. Adresy IP wychodzące mogą się zmieniać i z czasem mogą zostać dodane kolejne.

Żądanie

Zabezpieczone HTTP Basic auth: nazwa użytkownika external_claims, hasło = skonfigurowany sekret.

API jest wywoływane przez HTTP POST z ciałem JSON.

To przykładowe ciało JSON z dwoma wejściowymi oświadczeniami:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@test.org" }
  ]
}

Odpowiedź — sukces

W przypadku sukcesu API powinno zwrócić kod HTTP 200 i listę claims (lista może być pusta).

FoxIDs ignoruje oświadczenia, w których pole type lub value nie występuje, ma wartość null, jest puste lub zawiera wyłącznie białe znaki. Gdy rejestrowanie śladów komunikatów jest włączone, ślad odpowiedzi zawiera otrzymane oświadczenia przed ich filtrowaniem. Długie komunikaty śledzenia są obcinane.

Przykładowo, sub użytkownika (ID użytkownika / nazwa użytkownika), ID klienta i role:

{
    "claims": [
        { "type": "sub", "value": "somewhere/external-some@test.org" },
        { "type": "customer_id", "value": "1234abcd" },
        { "type": "role", "value": "admin_access" },
        { "type": "role", "value": "read_access" },
        { "type": "role", "value": "write_access" }
    ]
}

Odpowiedź — błąd

API musi zwrócić kod HTTP 401 (Unauthorized) i error (wymagane), jeśli Basic auth zostanie odrzucone. Opcjonalnie dodaj opis błędu w ErrorMessage.

{
    "error": "invalid_api_id_secret",
    "ErrorMessage": "Invalid API ID or secret"
}

Jeśli wystąpią inne błędy, API powinno zwrócić kod HTTP 500 lub inny odpowiedni kod błędu. Zaleca się dodanie technicznego komunikatu ErrorMessage do diagnostyki (jest on tylko logowany; nigdy nie jest pokazywany użytkownikowi końcowemu).

Komunikaty błędów zwrócone przez API w ErrorMessage NIE są wyświetlane użytkownikowi; są tylko logowane.

Przykład API

Przykład ExternalClaimsApiSample pokazuje, jak zaimplementować API w ASP.NET Core.

Możesz użyć tej kolekcji Postman do wywoływania i testowania API w Postman.

Konfiguracja

Skonfiguruj FoxIDs, aby wywoływał Twoje API z transformacji oświadczeń w FoxIDs Control Client.

  1. Przejdź do sekcji Claim Transform
  2. Kliknij Add claim transform
  3. Kliknij External claims API
  4. Wybierz Add claim lub Replace claim
  5. Dodaj wybrane oświadczenia, np. sub, w Select claims
  6. Dodaj bazowy URL API bez folderu claims w polu API URL
  7. Dodaj API secret Configure an external claims API claims transformation
  8. Opcjonalnie ustaw Target, aby wczytać claims z odpowiedzi do lokalnych claims
  9. Kliknij Update

Przykłady transformacji oświadczeń

Podziel oświadczenie name na dwa oświadczenia given_name i family_name

Transformacja dzieli wartość oświadczenia name przy pierwszej spacji i odpowiednio dodaje oświadczenia given_name oraz family_name, jeśli jeszcze nie istnieją. Jeśli w wartości oświadczenia name jest więcej niż jedna spacja, nowe oświadczenia given_name i family_name nie zostaną dodane, ponieważ już istnieją.

Użyj dwóch transformacji Regex map.

Transform name to given_name and family_name

  • Znajdź wartość family_name wyrażeniem regex ^\S+\s(?<map>\S+)$
  • Znajdź wartość given_name wyrażeniem regex ^(?<map>\S+)\s\S+$

Usuń domyślnie dodaną nazwę metody uwierzytelniania z sub

Nazwa metody uwierzytelniania jest domyślnie dodawana do wartości oświadczenia sub jako prefiks oddzielony pionową kreską, np. some-auth-method|my-external-user-id.

Możesz użyć akcji replace claim na oświadczeniu sub, aby usunąć domyślnie dodany prefiks.

Transformacja dzieli wartość oświadczenia sub i zastępuje oświadczenie nowym sub, zawierającym tylko oryginalny identyfikator.

Użyj transformacji Regex map i wybierz akcję Replace claim.

Remove default added post authentication method name

Znajdź identyfikator bez domyślnie dodanej nazwy metody uwierzytelniania wyrażeniem regex ^([^|]+)\|(?<map>.+)$

To samo możesz zrobić w metodzie uwierzytelniania SAML 2.0, używając oświadczenia http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (które zawiera wartość NameID z odpowiedzi SAML 2.0 Authn Response) zamiast oświadczenia sub.

Porównaj email z _local:mfa:email i dodaj amr

Przykład jest wykonywany w metodzie uwierzytelniania używanej jako element MFA. Porównuje zwrócony przez tę metodę claim email z _local:mfa:email użytkownika Login. Jeśli obie wartości adresu e-mail są równe i pasują do wyrażenia regularnego, dodawany jest claim amr z nazwą metody uwierzytelniania jako wartością (nazwa ta jest konfigurowana jako wartość amr).

Przepływ MFA metody Login używa dodanego claimu amr do potwierdzenia pomyślnego wykonania elementu MFA. Zwrócony claim email i pozostałe claimy metody uwierzytelniania nie są łączone z claimami metody uwierzytelniania Login.

Użyj transformacji claim Concatenate, a następnie transformacji claim Regex match.

Porównaj email i dodaj amr

  • Concatenate: Nowa claim _local:compare_emails, akcja Replace claim, concatenate claims email i _local:mfa:email, concatenate format string {0}|{1}.
  • Regex match: Nowa claim amr, akcja Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nowa wartość ustawiona na nazwę metody uwierzytelniania (na przykład 9fk5z3vg).

Impersonacja

Użyj transformacji Impersonation w metodzie uwierzytelniania, aby wydawać claims dla innego użytkownika, zachowując pierwotnie uwierzytelnionego użytkownika jako aktora. Sesje muszą być włączone w metodzie uwierzytelniania; domyślnie są włączone.

Wczytaj użytkownika docelowego przez Query internal user, zewnętrzne API claims lub obie te metody, ustawiając Target na nazwę taką jak target. Sprawdź uprawnienia uwierzytelnionego użytkownika i wymagane claims użytkownika docelowego przed wybraniem go transformacją Impersonation. Target jest wymagany i ma domyślną wartość target w Control Client. Parametr żądania aplikacji wybiera użytkownika docelowego; nie nadaje uprawnień do impersonacji.

Zachowaj odwołanie do wybranego użytkownika docelowego w claim sesyjnym, aby ponawiać wyszukiwanie przy kolejnych logowaniach do aplikacji. Odwołaniem może być wewnętrzny identyfikator użytkownika lub zewnętrzny identyfikator profilu; nie musi odpowiadać wydawanemu sub użytkownika docelowego. Poniższy przykład z użytkownikiem wewnętrznym używa impersonation_target_id zarówno dla parametru żądania, jak i claim sesyjnego; są to przykładowe nazwy, które dostosowujesz do swojego przepływu.

Wybrany użytkownik docelowy musi zawierać dokładnie jedną odrębną, niepustą wartość sub. W przeciwnym razie transformacja kontynuuje bez wyboru tego użytkownika. Wyszukanie wyłączonego użytkownika wewnętrznego nie zwraca claims. Użyj warunkowego zadania błędu, jeśli polityka wymaga odrzucenia logowania, gdy nie można wybrać użytkownika docelowego.

Transformacja przygotowuje claims _impersonate: do finalizacji po pomyślnych transformacjach drugiego poziomu. Na przykład _local:target:sub staje się _impersonate:sub, a _local:target:_local:internal_user_id staje się _impersonate:_local:internal_user_id. Claims te można przygotować również zwykłymi transformacjami. Pozostają dostępne między zestawami transformacji metody uwierzytelniania oraz w Extended UI.

Podczas finalizacji FoxIDs zastępuje zwykłe claims tożsamości użytkownika zwykłymi claims użytkownika docelowego, zachowuje zweryfikowany kontekst uwierzytelniania i dodaje claim act, którego sub identyfikuje pierwotnie uwierzytelnionego użytkownika. Subject aktora to FoxIDs sub użytkownika sprzed zastąpienia jego claims przez impersonację. Transformacje aplikacji otrzymują tę efektywną tożsamość. Zarezerwowane pomocnicze claims nie są wydawane aplikacjom.

Wewnętrzne konta docelowe

Gdy występuje _impersonate:_local:internal_user_id, FoxIDs sprawdza, czy użytkownik wewnętrzny istnieje i jest włączony, uwzględniając obowiązującą politykę Access Structure, oraz wiąże konto docelowe z sesją i grantami obok konta pierwotnego. Jeśli wewnętrzny użytkownik docelowy jest nieprawidłowy, nie istnieje lub jest wyłączony, impersonacja nie jest wykonywana.

Wyłączenie lub usunięcie dowolnego z powiązanych kont unieważnia aktywną sesję i granty tokenów odświeżania. Cofnięcie dostępu w Access Structure oraz sprawdzanie członkostw ograniczonych czasowo obejmuje także powiązanego użytkownika docelowego. Dla użytkownika dostarczanego wyłącznie przez API, bez powiązania z kontem wewnętrznym, skonfigurowane API i transformacje określają jego dostępność przy każdym logowaniu.

Przykład: impersonacja użytkownika wewnętrznego

Przykład umożliwia pracownikowi z wartością allow_impersonation w claim role wybór użytkownika wewnętrznego i kontynuowanie jego impersonacji przy kolejnych logowaniach do aplikacji. Logowanie bez wybranego użytkownika docelowego przebiega jako użytkownik pierwotny.

Diagram przedstawia osiem transformacji skonfigurowanych poniżej. Odwołanie do celu jest zachowywane między logowaniami; claims użytkownika docelowego i uprawnienia pracownika są sprawdzane ponownie przy każdym logowaniu.

Impersonacja wewnętrznego użytkownika: wybierz cel, sprawdź uprawnienia, wczytaj użytkownika i zachowaj odwołanie do celu na kolejne logowania

Skonfiguruj impersonation_target_id w Allowed request parameters każdej rejestracji aplikacji, która wysyła ten parametr. Aplikacja przekazuje jeden wewnętrzny identyfikator użytkownika jako wartość parametru, którą FoxIDs udostępnia jako _local:params:impersonation_target_id. Zobacz Parametry żądań aplikacji. Upewnij się, że claims pracownika zawierają role=allow_impersonation.

Dodaj kolejno osiem poniższych pozycji do Second-level claim transforms metody uwierzytelniania Login.

  1. Map: przywróć zapisane odwołanie do użytkownika docelowego. Użyj Replace claim, ustaw Select claim na _session:impersonation_target_id, a New claim na _local:impersonation_target_id.

  2. Map: zastosuj użytkownika docelowego z aplikacji. Użyj Replace claim, ustaw Select claim na _local:params:impersonation_target_id, a New claim na _local:impersonation_target_id. Przekazany parametr zastępuje zapisany wybór. Jeśli parametru nie ma, pozostaje wartość z kroku 1.

  3. Match claim and value: sprawdź rolę pracownika. Użyj Replace claim, ustaw Select claim na role, Match value na allow_impersonation, New claim na _local:impersonation_check_passed, a New value na true.

  4. Match claim: zezwól na logowanie bez użytkownika docelowego. Użyj Replace claim, if not match, ustaw Select claim na _local:impersonation_target_id, New claim na _local:impersonation_check_passed, a New value na true.

Lokalny claim kontrolny oznacza, że logowanie może być kontynuowane: pracownik ma wymaganą rolę albo nie wybrano użytkownika docelowego. Rola jest sprawdzana, zanim użytkownik docelowy zastąpi claims użytkownika pierwotnego.

Transformacje claims drugiego poziomu 1–4: wybór użytkownika docelowego i sprawdzenie roli pierwotnego użytkownika

  1. Match claim and return error: odrzuć nieuprawniony wybór. Użyj If not match i wybierz _local:impersonation_check_passed. Ustaw Error na access_denied, a Error message na You are not allowed to impersonate another user.

  2. Query internal user: wczytaj użytkownika docelowego. Użyj Replace claim, ustaw Lookup claim na _local:impersonation_target_id, Lookup claim on internal user na sub, Claims from internal user na *, a Target na target. Wyszukiwanie dopasowuje wewnętrzny identyfikator użytkownika i wczytuje jego claims, w tym przekazywane claims Access Structure i lokalne pomocnicze claims, pod _local:target:. Dostarcza na przykład _local:target:sub oraz _local:target:_local:internal_user_id.

  3. Impersonation: wybierz wczytanego użytkownika docelowego. Użyj Replace claim i ustaw Target na target.

  4. Map: zachowaj użytkownika docelowego na kolejne logowania. Użyj Replace claim, ustaw Select claim na _local:target:_local:internal_user_id, a New claim na _session:impersonation_target_id. Zapisuje to trwały identyfikator wczytanego użytkownika jako odwołanie dla następnego logowania.

Transformacje claims drugiego poziomu 5–8: odrzucenie nieuprawnionego wyboru, wczytanie i impersonacja użytkownika wewnętrznego oraz zapis odwołania

Jeśli polityka ogranicza użytkowników, których można impersonować, dodaj kontrole użytkownika docelowego między krokami 6 i 7. Sprawdź na przykład _local:target:role lub pomocniczy claim Access Structure _local:target:_local:access_node.

Jeśli wyszukiwanie nie zwróci użytkownika docelowego, te osiem kroków kończy się bez impersonacji i zachowuje wcześniej zapisane odwołanie. Dodaj warunkowe zadanie błędu po wyszukiwaniu, jeśli niedostępny użytkownik docelowy ma spowodować odrzucenie logowania, lub jawnie usuń claim sesyjny, jeśli zapisany wybór ma zostać wyczyszczony.

Kontynuowanie i zmiana impersonacji

Każde logowanie do aplikacji ponownie uruchamia transformacje metody uwierzytelniania. W powyższym przykładzie odczytują one odwołanie z _session:impersonation_target_id, gdy brakuje _local:params:impersonation_target_id, następnie wczytują aktualne claims użytkownika docelowego i ponawiają kontrolę uprawnień przed wyborem impersonacji. Zapisane odwołanie pozostaje związane z pierwotnie uwierzytelnionym użytkownikiem i tą samą metodą uwierzytelniania.

Aby wybrać innego użytkownika docelowego, przekaż nowe odwołanie w parametrze żądania i zastąp zapisany claim sesyjny po pomyślnych kontrolach nowego użytkownika. Aby zakończyć impersonację, wyczyść odwołanie i zakończ transformacje bez prawidłowego użytkownika docelowego.

Pomyślne zakończenie z tym samym użytkownikiem docelowym zachowuje sid. Wybór innego użytkownika, rozpoczęcie impersonacji lub zakończenie bez prawidłowego użytkownika docelowego tworzy nowy sid i unieważnia poprzednią aktywną sesję oraz granty tokenów odświeżania.

UserInfo i realizacja grantów odrzucają unieważnioną aktywną sesję. Aplikacje i API walidujące tokeny lokalnie nadal muszą stosować własne reguły dotyczące sesji i czasu życia tokenów. SAML single logout korzysta z wartości zapisanych przy wydaniu dla każdej aplikacji.

Aktywne sesje i granty tokenów odświeżania pokazują subject użytkownika impersonowanego i pierwotnego aktora w Control Client i Control API. Zdarzenia audytu logowania obejmują aktora. Osobne zdarzenia audytu impersonacji rejestrują rozpoczęcie, zmianę i zakończenie, w tym poprzednie i aktualne identyfikatory sesji.