Konfiguracja SSO

NexBasira obsługuje zarówno OpenID Connect (OIDC), jak i SAML 2.0 Web Browser SSO. Użytkownicy w skonfigurowanych domenach e-mail są logowani przez dostawcę tożsamości; pierwsze logowania są provisionowane just-in-time z wybraną rolą domyślną.

Zanim zaczniesz

• Po stronie NexBasira potrzebna jest rola org_admin.
• Potrzebny jest dostęp administracyjny do IdP, aby zarejestrować aplikację + skonfigurować mapowanie atrybutów.
• SSO jest dostępne w warstwie Pro i wyższej (zobacz cennik).

Przewodnik OIDC

1. Znajdź swój callback URL

W NexBasira SPA: Admin → SSO → Protokół: OpenID Connect. Callback URL jest wyświetlany u góry formularza:

https://app.nexbasira.com/api/v1/auth/sso/callback

Klienci z domeną własną (Pro+) widzą tutaj swoją domenę. Skopiuj go — Twój IdP go potrzebuje.

2. Zarejestruj aplikację w swoim IdP

Każdy IdP ma własny interfejs, ale kształt jest ten sam:

• Typ aplikacji: Web (server-side, poufny klient)
• Redirect URI: callback URL z kroku 1
• Dozwolone grant types: Authorization Code (z PKCE)
• Zakresy (scopes): openid + email + profile

IdP zwraca Client ID, Client Secret oraz Issuer URL (bazowy URL dla discovery — zwykle https://your-idp.example.com/realms/yourrealm lub https://accounts.google.com).

3. Wypełnij konfigurację SSO

Wracając do Admin → SSO, wypełnij formularz:

• Nazwa wyświetlana: pokazywana na przycisku „Kontynuuj z SSO”. Np. „Acme SSO”.
• Issuer URL: z Twojego IdP.
• Client ID + Client Secret z Twojego IdP.
• Domeny e-mail: lista rozdzielona przecinkami (acme.com, acme-eu.com). Użytkownicy z e-mailami w tych domenach są kierowani przez SSO.
• Rola domyślna dla nowych użytkowników: zwykle inspector. Administratorzy organizacji muszą otrzymać rolę org_admin ręcznie po pierwszym logowaniu.
• Automatyczne provisionowanie nowych użytkowników przy pierwszym logowaniu: zazwyczaj włączone.
• Włączone: wyłączone do czasu przetestowania.

4. Przetestuj discovery

Kliknij Test discovery. Pobiera konfigurację OpenID Twojego IdP ({issuer_url}/.well-known/openid-configuration) + parsuje JWKS. Typowe błędy:

• OK — N kluczy JWKS: gotowe.
• Connection refused / błąd DNS: literówka w issuer URL; sprawdź, czy rozwiązuje się w przeglądarce.
• Błąd parsowania JSON: issuer URL wskazuje na coś, co nie jest dostawcą OIDC.
• Brak kluczy JWKS: sonda się powiodła, ale endpoint JWKS zwrócił pusty zestaw; sprawdź rotację kluczy po stronie IdP.

5. Włącz + test dymny

Przełącz Włączone, zapisz. Wyloguj się, a następnie zaloguj z e-mailem w jednej z dozwolonych domen. Powinno nastąpić przekierowanie na ekran logowania Twojego IdP, a potem z powrotem do panelu SPA.

Przewodnik SAML 2.0

1. Znajdź swój ACS URL

W Admin → SSO → Protokół: SAML 2.0 skopiuj Assertion Consumer Service URL:

https://app.nexbasira.com/api/v1/auth/saml/acs

2. Zarejestruj aplikację SAML w swoim IdP

• ACS URL / Reply URL: URL z kroku 1.
• Entity ID (audience): https://app.nexbasira.com/saml/sp (lub Twoja domena własna).
• Format NameID: emailAddress.
• Mapowanie atrybutów: co najmniej email; najlepiej także givenName + surname.
• Podpisywanie asercji: wymagane.

IdP zwraca Entity ID, SSO Service URL oraz certyfikat podpisujący (PEM).

3. Wypełnij konfigurację SAML

• IdP Entity ID — z Twojego IdP.
• IdP SSO Service URL — z Twojego IdP.
• Certyfikat podpisujący IdP (PEM) — wklej pełny blok -----BEGIN CERTIFICATE-----.
• Domeny e-mail — taki sam kształt jak w OIDC.
• Rola domyślna + auto-provisionowanie — tak samo jak w OIDC.

Sekcja Zaawansowane — mapowanie atrybutów pozwala nadpisać URN-y, których szukamy; domyślne wartości odpowiadają konwencji WS-Federation firmy Microsoft, którą większość IdP honoruje od razu.

4. Włącz + test dymny

Taki sam przebieg jak w OIDC: przełącz Włączone, wyloguj się, zaloguj z e-mailem z dozwolonej domeny, oczekuj przejścia w obie strony przez Twój IdP.

Przetestowane IdP

Wsparcie OIDC + SAML w NexBasira jest generyczne; działa każdy IdP zgodny ze specyfikacją. Przetestowaliśmy dymnie:

• Microsoft Entra ID (Azure AD) — OIDC + SAML
• Google Workspace — OIDC + SAML
• Okta — OIDC + SAML
• Keycloak — OIDC + SAML
• OneLogin — SAML

Zasady provisionowania JIT

• Przy pierwszym logowaniu przez SSO użytkownika z pasującą domeną tworzone jest członkostwo z skonfigurowaną rolą domyślną.
• email jest kluczem unikalnym. Zmiana e-maila przez użytkownika w IdP tworzy nowe konto.
• Zmiany ról po pierwszym logowaniu zarządzane są w SPA (Admin → Członkowie), nie w IdP. Dla mapowania grupa IdP → rola zobacz provisionowanie SCIM.

Wyłączanie SSO

Możesz przełączyć Włączone na wyłączone (zachowuje konfigurację; możesz ją później włączyć ponownie) albo kliknąć Usuń SSO (usuwa konfigurację). Przy wyłączonym SSO wszyscy użytkownicy wracają do uwierzytelniania hasłem; istniejące członkostwa są zachowywane.

Rozwiązywanie problemów

Co dalej

• Provisionowanie SCIM — tworzenie i dezaktywacja użytkowników sterowane przez IdP
• Uwierzytelnianie API — oddzielne od SSO w SPA