Konfiguracja logowania zewnętrznego do nAxiom
Przeczytasz w 12 min.
Spis treści
Wstęp
Logowanie zewnętrzne nAxiom bazuje na protokole OpenID Connect. Mechanizm pozwala na wprowadzenie SSO (Single Sign-On), czyli korzystanie z jednego sposobu logowania dla rónych systemów. Do prawidłowego działania logowania wymagane jest, aby użytkownicy, którzy mogą zalogować się za pomocą SSO mieli profile w bazie użytkowników systemu nAxiom.
W tym artykule opisano parametry konfiguracyjne logowania zewnętrznego do nAxiom oraz podano przykładowe informacje dla różnych tożsamości. Dodatkowe informacje dotyczące konfiguracji środowiska i oprogramowania można znaleźć w artykule „Logowanie zewnętrzne do witryny nAxiom”.
Parametry konfiguracyjne logowania zewnętrznego
Konfiguracja logowania zewnętrznego jest dostępna w aplikacji TenantAdminSPA i dokonuje się jej osobno dla każdego tenanta.
Konfiguracja obejmuje następujące parametry:
- UseExternalLogin (bool): określa czy aplikacja zezwala na logowanie zewnętrzne.
- AutomaticRedirect (bool): określa czy użytkownik jest automatycznie przekierowywany do logowania zewnętrznego.
- AuthenticationScheme (string): schemat autentykacji pozwalający na precyzyjne odróżnienie od innych schematów takich jak public-api, parametr przyjmuje dowolną wartość, ale zalecane jest korzystanie z wartości, które niosą ze sobą informacje o wykorzystywanym sposobie autentykacji, na przykład oidc dla protokołu OpenID Connect; w przypadku obsługi wielu tenantów system automatycznie dodaje do podanego schematu dopisek -tenantSuffix, gdzie Suffix to kod klienta.
- DisplayName (string): nazwa dostawcy tożsamości wyświetlana na ekranie logowania nAxiom, o ile nie następuje automatyczne przekierowanie do logowania zewnętrznego.
- SignInScheme (string): schemat logowania, a dokładnie sposób obsługi komunikacji pomiędzy serwerem autoryzacji nAxiom, a zewnętrznym dostawcą tożsamości. Schemat ten określa w jaki sposób zostanie przechowany token autoryzacyjny w powyższej komunikacji (cookie). Dostępne wartości to idsrv lub idsrv.external. Wartość idsrv służy do długotrwałego przechowania tokenów autoryzacyjnych w ciasteczkach przeglądarki. Token zawiera informacje o uwierzytelnionym użytkowniku. Wartość idsrv.external służy do tymczasowego przechowania tokenów autoryzacyjnych, kiedy po procesie logowania u zewnętrznego dostawcy powinny one zostać usunięte.
- Authority (string): adres URL, pod który wysyłane będą żądania OpenID Connect.
- ClientId (string): identyfikator klienta uwierzytelniający komunikację z zewnętrznym dostawcą tożsamości.
- ClientSecret (string): sekret klienta uwierzytelniający komunikację z zewnętrznym dostawcą tożsamości.
-
ResponseType (string): określa przebieg autoryzacji (authorization flow) i ma bezpośredni wpływ na zwracane parametry oraz tokeny od zewnętrznego dostawcy tożsamości. Dostępne wartości:
- code
- token
- id_token
- none
Dostępne kombinacje wartości:
- code
- token
- id_token
- id_token token
- code id_token
- code token
- code id_token token
- none
Wartości obsługiwane przez nAxiom:
- code
- id_token
Ze względu na wykorzystanie parametru id_token z odpowiedzi od zewnętrznego dostawcy tożsamości, należy zastosować konfigurację, która pozwoli powyższy parametr otrzymać. W tym celu można zastosować wartość id_token lub code, ale tylko w połączeniu z wartością openid w parametrze Scopes konfiguracji. W tabeli poniżej podano linki do opisu przebiegu autoryzacji dla poszczególnych kombinacji wartości parametru responseType.
-
ResponseMode (string): określa sposób, w jaki zewnętrzny dostawca tożsamości ma odpowiedzieć na żądanie autoryzacji. Dostępne wartości:
- query
- fragment
- form_post Jedyna wartość obsługiwana to form_post.
- SaveTokens (bool): określa czy zapisać dodatkowe tokeny (access_token oraz refresh_token) w tokenach autoryzacyjnych; aby wylogowanie działało prawidłowo działania, musi mieć wartość true.
- GetClaimsFromUserInfoEndpoint (bool): określa czy system powinien odpytać serwer zewnętrznego dostawcy tożsamości o dodatkowe parametry podczas autentykacji użytkownika (exp, iat, iss, aud, azp, nonce). Te parametry nie są wykorzystywane podczas autentykacji. Parametr może przyjmować wartość false.
- UsePkce (bool): określa czy podczas wymiany informacji zastosować Proof Key for Code Exchange; ma zastosowanie tylko w wypadku ustawienia dla ResponseType wartości code (https://tools.ietf.org/html/rfc7636).
-
AcrValue (string): (Authentication Context Class Reference) określa kontekst autoryzacji. W przypadku, gdy różne systemy korzystają z tego samego zewnętrznego dostawcy tożsamości kontekst autoryzacji nie zawsze jest taki sam> Przykładem może być logowanie do systemu, gdzie podstawowy zakres danych będzie dostępny po zwykłym logowaniu, a dostęp do danych wrażliwych wymaga dodatkowego mechanizmu logowania (multifactor). Wartości parametru należy rozdzielić spacją. Istnieją dwie specjalne wartości dla tego parametru:
- idp:name_of_idp: jeśli konfiguracja klienta na to pozwala, nastąpi bezpośrednie przekierowanie do dostawcy tożsamości.
- tenant:name_of_tenant: przekazuje nazwę tenanta do interfejsu użytkownika strony logowania; parametr nie jest obsługiwany.
- Scopes (list of strings): lista zakresów do jakich system chce uzyskać dostęp. Standardowe dostępne wartości to openid, profile, email. Wartosć domyślna to openid. Zwracane wartości zależą też od konfiguracji zewnętrznego dostawcy tożsamości i zmiana wartości może nie mieć wpływu na działanie systemu.
- ClaimTypeInExternalToken (string): określa, w którym parametrze odpowiedzi autoryzacji znajduje się wartość pozwalająca na wyszukanie oraz zalogowanie użytkownika w systemie nAxiom.
-
AuthenticateUser (string): określa atrybut używany do uwierzytelniania użytkownika. Dostępne wartości to:
- ByUserName: identyfikowanie użytkownika na podstawie nazwy (wartość domyślna w przypadku, gdy parametr nie jest ustawiony),
- ByUserEmail: identyfikowanie użytkownika na podstawie adresu email,
- ByUserId: identyfikowanie użytkownika na podstawie identyfikatora UUID pobieranego w postaci tekstowej,
- ByUserIdBase64: identyfikowanie użytkownika na podstawie identyfikatora UUID pobieranego w postaci binarnej w formacie Base64.
- RequireHttpsMetadata (bool): określa czy metadane dotyczące konfiguracji logowania do zewnętrznego dostawy tożsamości muszą być dostępne pod adresem szyfrowanym (https), zalecane jest stosowanie szyfrowanych kanałów komunikacji oraz korzystanie z wartości true.
Zmienna @_UserAuthenticationLevel i powiązane parametry konfiguracyjne
W sekcji ExternalLogin można ponadto skonfigurować klucze dla zmiennej systemowej {@_UserAuthenticationLevel}. Wartość zmiennej odpowiada metodzie uwierzytelnienia użytej w danej sesji przez użytkownika i jest określana na podstawie danych zwracanych przez dostawcę SSO. Zmienna może być używana w środowiskach, w których skonfigurowano logowanie SSO do witryny nAxiom. Klucze konfiguracyjne tej zmiennej to:
- AuthenticationLevelClaimName: nazwa atrybutu przesyłanego z systemu zewnętrznego uwierzytelnienia, zawierającego wartość poziomu uwierzytelnienia,
- DefaultAuthenticationLevel: domyślny poziom uwierzytelnienia, jeżeli system zewnętrzny nie prześle atrybutu,
- AuthenticationLevelMapper mapper wartości przychodzących z zewnętrznego systemu na wartości nAxiom.
Przykładowa konfiguracja:
"ExternalLogin": {
"AuthenticationLevelClaimName": "authenticationLevel",
"DefaultAuthenticationLevel": 2,
"AuthenticationLevelMapper": {
"1": "1",
"2": "2",
"3": "3"
}
}
Wprowadzone zmiany pozwalają na uzależnienie przebiegu procesu biznesowego w nAxiom od metody uwierzytelnienia bieżącego użytkownika i na przykład żądanie uwierzytelnienia dwuskładnikowego w przypadku niektórych newralgicznych operacji.
Przykłady konfiguracji logowania zewnętrznego
Poniżej przedstawiono konfigurację logowania zewnętrznego dla różnych dostawców tożsamości.
nAxiom obsługuje wersje Keyclock od 16.1.1 do 19.0.2.
KeyCloak
"ExternalLogin": {
"UseExternalLogin": true,
"AutomaticRedirect": false,
"AuthenticationScheme": "oidc",
"DisplayName": "Logowanie Keycloak",
"SignInScheme": "idsrv.external",
"Authority": "http://localhost:8080/auth/realms/naxiom",
"ClientId": "naxiom",
"ResponseType": "id_token",
"ResponseMode": "form_post",
"SaveTokens": true,
"GetClaimsFromUserInfoEndpoint": false,
"UsePkce": false,
"Scopes": [
"openid"
],
"ClaimTypeInExternalToken": "unit4_id",
"AuthenticateUserByUserName": true,
"AuthenticateUserByUserEmail": false,
"RequireHttpsMetadata": false
}
CAS
"ExternalLogin": {
"UseExternalLogin": true,
"AutomaticRedirect": false,
"AuthenticationScheme": "oidc",
"DisplayName": "Logowanie CAS",
"SignInScheme": "idsrv.external",
"Authority": "https://cas.dev.localhost/cas/oidc",
"ClientId": "eodcas",
"ResponseType": "code",
"ResponseMode": "form_post",
"SaveTokens": true,
"GetClaimsFromUserInfoEndpoint": false,
"UsePkce": true,
"Scopes": [
"openid"
],
"ClaimTypeInExternalToken": "unit4_id",
"AuthenticateUserByUserName": true,
"AuthenticateUserByUserEmail": false,
"RequireHttpsMetadata": true
}
ADFS
"ExternalLogin": {
"UseExternalLogin": true,
"AutomaticRedirect": false,
"AuthenticationScheme": "oidc",
"DisplayName": "Logowanie ADFS",
"SignInScheme": "idsrv.external",
"Authority": "https://login.usos.local/adfs",
"ClientId": "e47468e2-0be5-48b3-8710-5e1e60b85c36",
"ResponseType": "id_token",
"ResponseMode": "form_post",
"SaveTokens": true,
"GetClaimsFromUserInfoEndpoint": true,
"UsePkce": true,
"AcrValue": "",
"Scopes": [
"openid"
],
"ClaimTypeInExternalToken": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"AuthenticateUserByUserName": true,
"AuthenticateUserByUserEmail": false,
"RequireHttpsMetadata": true
}