Rejestracja aplikacji OpenID Connect

Rejestracja aplikacji OpenID Connect w FoxIDs umożliwia aplikacji internetowej, jednostronicowej lub natywnej uwierzytelnianie użytkowników za pośrednictwem FoxIDs oraz odbieranie tokenów ID i tokenów dostępu. Aplikacja jest Relying Party (RP), a FoxIDs jest OpenID Provider (OP).

Ważne funkcje OpenID Connect obejmują discovery, Authorization Code Flow, PKCE, klucze i sekrety klienta, punkt końcowy UserInfo, wylogowanie inicjowane przez RP oraz front-channel logout.

Konfiguracja

W FoxIDs Control:

1. Wybierz środowisko, w którym aplikacja ma zostać zarejestrowana.
2. Otwórz Applications i kliknij Add application.
3. Wybierz Web Application, Single Page Application lub Native Application. Te trzy opcje OpenID Connect są widoczne bez włączania Show all options.
4. Wprowadź nazwę i identyfikator URI przekierowania, sprawdź wygenerowane informacje o aplikacji i kliknij Create.
5. Skopiuj wygenerowany sekret przed zamknięciem wyniku tworzenia. Wygenerowany sekret jest widoczny tylko podczas tworzenia.

Po utworzeniu kliknij Change application, aby przejrzeć lub zmienić pełne ustawienia aplikacji. Karta typu aplikacji zapewnia odpowiednią konfigurację początkową, a wynikowego klienta OpenID Connect można później dostosować.

Aplikacja internetowa (klient poufny)

Wybierz Web Application dla aplikacji działającej na serwerze, np. aplikacji ASP.NET Core, Node.js, Java lub PHP. Jest ona tworzona jako klient poufny z:

• Authorization Code Flow używającym response type code.
• Wygenerowanym sekretem klienta.
• PKCE domyślnie wyłączonym. Po utworzeniu włącz Require PKCE, jeśli aplikacja obsługuje PKCE. Jest to zalecane jako dodatkowa ochrona kodu autoryzacyjnego.

Wprowadź bazowy adres URL lub adres URL wywołania zwrotnego aplikacji jako Redirect URI. Podczas tworzenia włącz Show advanced tylko wtedy, gdy chcesz wybrać identyfikator klienta lub skonfigurować dokładne dopasowanie adresu URL przekierowania.

Aplikacja jednostronicowa (klient publiczny)

Wybierz Single Page Application dla aplikacji działającej w przeglądarce, np. React, Angular, Vue lub Blazor WebAssembly. Jest ona tworzona jako klient publiczny z:

• Authorization Code Flow używającym response type code.
• PKCE domyślnie włączonym.
• Brakiem sekretu klienta.
• Origin adresu URL przekierowania dodanym jako dozwolony CORS origin.

Aplikacja natywna (klient publiczny)

Wybierz Native Application dla zainstalowanej aplikacji mobilnej lub komputerowej, np. iOS, Android, React Native, .NET MAUI lub Ionic. Jest ona tworzona jako klient publiczny z Authorization Code Flow, domyślnie włączonym PKCE i bez sekretu klienta.

Identyfikator URI przekierowania może korzystać ze schematu specyficznego dla aplikacji, takiego jak myapp://callback, lub z identyfikatora URI HTTPS obsługiwanego przez aplikację.

Identyfikatory URI przekierowania i wartości bezwzględne

Domyślnie opcja Absolute URIs jest wyłączona dla aplikacji internetowych i jednostronicowych. Skonfigurowany adres URL przekierowania jest wtedy traktowany jako wartość bazowa, a adresy URL przekierowania zaczynające się od tej wartości są akceptowane.

Włącz Show advanced i Absolute URIs, jeśli znasz dokładny adres URL w aplikacji, do którego użytkownik ma zostać przekierowany po zalogowaniu. Wprowadź ten dokładny adres jako Redirect URI. To samo ustawienie obsługuje dokładne identyfikatory URI specyficzne dla aplikacji natywnych.

Po utworzeniu identyfikatory URI przekierowania, identyfikator URI przekierowania po wylogowaniu i dozwolone CORS origins można zmieniać na karcie OpenID Connect Client. Pozostaw Show advanced wyłączone, jeśli potrzebne ustawienie nie jest zaawansowane.

Implicit Flow

Implicit Flow pozostaje dostępny ze względów zgodności, ale nie jest zalecany dla nowych aplikacji. Preferuj Authorization Code Flow z PKCE.

Aby skonfigurować istniejącego klienta publicznego do używania Implicit Flow, kliknij Change application, włącz Show advanced, zmień Response types na token id_token lub opcjonalnie tylko token i wyłącz Require PKCE. Response types można zmieniać w tych samych zaawansowanych ustawieniach klienta, gdy wymagana jest inna obsługiwana kombinacja.

Punkty końcowe aplikacji i bezpieczeństwo klienta

Informacje o aplikacji w FoxIDs Control zawierają authority, identyfikator klienta, punkt końcowy discovery, punkt końcowy authorize i punkt końcowy tokenu. Dokument discovery OpenID Connect ma następującą postać:

https://foxids.com/tenant-x/environment-y/application-client1(*)/.well-known/openid-configuration

Aplikacja może zezwalać na logowanie za pośrednictwem wielu metod uwierzytelniania. Jeśli metoda uwierzytelniania definiuje profile, metodę podstawową i każdy profil można wybierać niezależnie. Aby wybrać metodę uwierzytelniania w adresie URL authority, dodaj jej nazwę do segmentu aplikacji:

https://foxids.com/tenant-x/environment-y/application-client1(login)/.well-known/openid-configuration

Podczas wylogowania inicjowanego przez RP nazwę metody uwierzytelniania można pominąć, jeśli token ID jest zawarty w żądaniu.

Issuer specyficzny dla aplikacji

Domyślnie tokeny wydane aplikacji używają issuer środowiska:

https://foxids.com/tenant-x/environment-y/

Aby issuer odpowiadał authority aplikacji, kliknij Change application, włącz Show advanced i włącz Use matching issuer and authority with application specific issuer. Issuer zmieni się na:

https://foxids.com/tenant-x/environment-y/application-client1(*)

Issuer specyficzny dla aplikacji zmienia się wraz ze zmianą metod uwierzytelniania wybranych w adresie URL authority. W przypadku API issuer zależy więc od aplikacji wywołującej. Token exchange jest możliwy tylko między konfiguracjami z odpowiadającymi sobie metodami uwierzytelniania.

Bezpieczeństwo klienta

Klienci publiczni, w tym aplikacje jednostronicowe i natywne, nie mogą bezpiecznie przechowywać poświadczeń klienta. Skonfiguruj ich bez sekretu klienta i używaj Authorization Code Flow z PKCE.

Klienci poufni uwierzytelniają się w punkcie końcowym tokenu. Domyślną metodą uwierzytelniania klienta jest client secret post. Włącz Show advanced, aby zmienić ją na client secret basic lub private key JWT. PKCE jest również zalecane, gdy klient poufny je obsługuje. Jeśli skonfigurowano zarówno PKCE, jak i sekret lub klucz klienta, FoxIDs sprawdza oba.

Metoda uwierzytelniania klienta none jest obsługiwana z PKCE. Dla klienta można skonfigurować do 10 sekretów i 4 kluczy. Przechowuj sekrety klienta i klucze prywatne bezpiecznie oraz rotuj je w razie potrzeby.

FoxIDs ustanawia sesję podczas uwierzytelniania użytkownika i umieszcza jej identyfikator w tokenie ID. Sesja jest unieważniana podczas wylogowania. W zależności od konfiguracji klienta i tego, czy żądanie wylogowania zawiera token ID, FoxIDs może wyświetlić okno potwierdzenia wylogowania.

Klient i API

Rejestracja aplikacji OpenID Connect może zawierać zarówno klienta, jak i jego zasób OAuth 2.0. Identyfikator klienta jest wtedy również nazwą zasobu API.

Poniższy przykład konfiguruje oidc-web-app zarówno jako klienta OpenID Connect, jak i API:

1. Kliknij Change application i włącz Show advanced.
2. Zmień typ rejestracji aplikacji na OpenID Connect Client and OAuth 2.0 Resource.
3. Na karcie OpenID Connect Client pozostaw zaznaczone Default resource 'oidc-web-app' for the application itself.
4. Dodaj zakresy read i write pod zasobem domyślnym.

Na karcie OAuth 2.0 Resource zdefiniuj te same zakresy read i write, które udostępnia API.

Zasób i zakresy

API można zamiast tego zarejestrować osobno jako zasób OAuth 2.0. W tym przykładzie klient oidc-web-app wywołuje osobne Orders API o nazwie zasobu orders-api.

Na karcie OpenID Connect Client klienta:

1. Usuń zaznaczenie Default resource 'oidc-web-app' for the application itself, ponieważ klient nie działa jako własne API.
2. Dodaj zasób orders-api.
3. Dodaj zakresy read i write pod tym zasobem.

Pełne wartości zakresów żądane przez klienta to orders-api:read i orders-api:write.

W rejestracji aplikacji Orders API zdefiniuj read i write na karcie OAuth 2.0 Resource.

Zakresy żądane przez klienta są sprawdzane względem zakresów skonfigurowanych w API. Jeśli klient i API znajdują się w tej samej rejestracji aplikacji, zakresy dodane pod domyślnym zasobem klienta są automatycznie dodawane do zasobu.

Domyślnie identyfikator klienta jest audience zarówno tokenu ID, jak i tokenu dostępu. Skonfigurowane zakresy zasobów dodają audiences API do tokenu dostępu, a jeden token dostępu może być przeznaczony dla wielu zasobów API.

Zakresy i oświadczenia

Zakresy OpenID Connect konfiguruje się na karcie OpenID Connect Client. Domyślne zakresy offline_access, profile, email, address i phone można zmieniać lub usuwać. Dla każdego zakresu ustawienie Voluntary claims kontroluje, które oświadczenia są wydawane, gdy klient żąda tego zakresu.

Włącz Show advanced, aby skonfigurować Issue claims. Dodaj konkretne oświadczenie lub *, aby wydać wszystkie dostępne oświadczenia w tokenie dostępu. Pozostaw Include in ID token wyłączone dla *. W przeciwnym razie wszystkie dostępne oświadczenia zostaną skopiowane do tokenu ID, co może nadmiernie zwiększyć jego rozmiar i spowodować problemy w przepływach, w których token ID jest wysyłany podczas wylogowania.

Możesz też dodać oświadczenie do Voluntary claims zakresu i zażądać tego zakresu z aplikacji. Poszczególne oświadczenia można umieszczać w tokenie ID, gdy aplikacja ich tam potrzebuje. Oświadczenia można również zmieniać za pomocą transformacji i zadań oświadczeń.

Czas życia tokenu

Kliknij Change application i włącz Show advanced, aby skonfigurować czas życia kodu autoryzacyjnego, tokenu ID, tokenu dostępu i refresh tokenu.

W tym przykładzie każdy refresh token jest ważny przez 36 000 sekund. Aplikacja może odnawiać sesję do momentu osiągnięcia bezwzględnego czasu życia refresh tokenu wynoszącego 86 400 sekund.

Wymaganie uwierzytelniania wieloskładnikowego (MFA)

Klient OpenID Connect może wymagać MFA, dołączając urn:foxids:mfa do parametru acr_values. Można go łączyć z bardziej szczegółowymi wartościami, takimi jak urn:foxids:link. Zobacz żądanie MFA z aplikacji.

Parametr acr_values można ustawić w zdarzeniu OnRedirectToIdentityProvider w pliku Startup.cs:

options.Events.OnRedirectToIdentityProvider = (context) =>
{
    context.ProtocolMessage.AcrValues = "urn:foxids:mfa";
    return Task.FromResult(string.Empty);
};

Zobacz AspNetCoreOidcAuthorizationCodeSample i jego konfigurację Startup.cs.

Przewodniki

• Połącz Tailscale

Powiązana dokumentacja

• OpenID Connect
• Zasoby i API OAuth 2.0
• Uwierzytelnianie wieloskładnikowe
• Łączenie środowisk za pomocą Environment Link
• Łączenie środowisk za pomocą OpenID Connect
• Oświadczenia i mapowanie oświadczeń