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

Jeśli utworzysz nowe oświadczenie za pomocą transformacji lub zadania pierwszego poziomu, oświadczenie jest lokalne dla metody uwierzytelniania, z wyjątkiem metody uwierzytelniania login.
W metodzie uwierzytelniania oświadczenie jest przekazywane, jeśli typ oświadczenia został dodany do listy Forward claims lub jeśli w liście znajduje się * (domyślnie).

Jeśli utworzysz nowe oświadczenie za pomocą transformacji lub zadania oświadczeń, oświadczenie jest lokalne dla rejestracji aplikacji.
W rejestracji aplikacji musisz dodać oświadczenie lub * do listy Issue claims. Alternatywnie w OpenID Connect dodaj oświadczenie do listy Voluntary claims w scope i zażądaj tego scope z aplikacji.

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.

Lokalne oświadczenia dodawane w AddLocalClaims:

_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)

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

Typy transformacji oświadczeń obsługujące wszystkie akcje:

Match claim - wykonaj akcję, jeśli typ oświadczenia pasuje
Match claim and value - wykonaj akcję, jeśli typ i wartość oświadczenia pasują
Regex match - wykonaj akcję, jeśli typ oświadczenia pasuje i wartość oświadczenia pasuje do wyrażenia regularnego

Typy transformacji oświadczeń obsługujące akcje Add claim, Replace claim i Add claim, if new claim does not exist:

Map - wykonaj akcję, jeśli typ oświadczenia pasuje, następnie zmapuj wartość na nowe oświadczenie
Regex map - wykonaj akcję, jeśli typ oświadczenia pasuje i wartość pasuje do grupy wyrażenia regularnego, następnie zmapuj wartość grupy na nowe oświadczenie

Typy transformacji oświadczeń obsługujące akcje Add claim i Replace claim:

Constant - zawsze wykonaj akcję (dodaj/zastąp oświadczenie stałą wartością)
Concatenate - wykonaj akcję, jeśli pasuje jeden lub więcej typów oświadczeń, następnie połącz wartości oświadczeń w nowe oświadczenie
External claims API - wywołaj zewnętrzne API z wybranymi oświadczeniami, aby dodać/zastąpić oświadczenia zwrócone przez API
DK XML privilege to JSON - konwertuj DK privilege to JSON.

Typy zadań oświadczeń obsługujące akcje Add claim i Replace claim:

Query internal user - dopasuj oświadczenie i znajdź dokładnie jednego użytkownika wewnętrznego na podstawie wartości oświadczenia. Żądanie zakończy się błędem, jeśli znajdzie się więcej niż jednego użytkownika. Następnie dodaj/zastąp oświadczenia użytkownika.
Query external user - dopasuj oświadczenie i znajdź dokładnie jednego użytkownika zewnętrznego na podstawie wartości oświadczenia. Żądanie zakończy się błędem, jeśli znajdzie się więcej niż jednego użytkownika. Następnie dodaj/zastąp oświadczenia użytkownika.

Typy zadań oświadczeń obsługujące akcje If match i If not match:

Match claim and return error - zwróć błąd, jeśli typ oświadczenia pasuje/nie pasuje.
Match claim and value and return error - zwróć błąd, jeśli typ i wartość oświadczenia pasują/nie pasują.
Regex match and return error - zwróć błąd, jeśli typ oświadczenia pasuje, a wartość pasuje/nie pasuje do wyrażenia regularnego.
Match claim and start authentication - rozpocznij nowe logowanie, inicjując metodę uwierzytelniania, jeśli typ oświadczenia pasuje/nie pasuje.
Match claim and value and start authentication - rozpocznij nowe logowanie, inicjując metodę uwierzytelniania, jeśli typ i wartość oświadczenia pasują/nie pasują.
Regex match and start authentication - rozpocznij nowe logowanie, inicjując metodę uwierzytelniania, jeśli typ oświadczenia pasuje, a wartość pasuje/nie pasuje do wyrażenia regularnego.

Zadania startu uwierzytelniania 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 (oświadczenia).

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.

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ń.

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).

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.

Przejdź do sekcji Claim Transform
Kliknij Add claim transform
Kliknij External claims API
Wybierz Add claim lub Replace claim
Dodaj wybrane oświadczenia, np. sub, w Select claims
Dodaj bazowy URL API bez folderu claims w polu API URL
Dodaj API secret
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 ^(nemlogin\|)(?<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.