Przejdź do głównej treści

Przegląd

protocol: saml sprawia, że gateway działa jako dostawca usług (service provider) SAML 2.0 zamiast klienta OIDC. Sesje, ścieżki użytkowników, mapowanie grup, wylogowanie i zdarzenia logowania działają dokładnie tak, jak opisano dla OIDC SSO; zmienia się tylko sposób potwierdzania logowania.
  • Jeden protokół i jeden dostawca tożsamości na gateway. Przy protocol: saml ustawienia klienta OIDC (issuer_url, client_id, client_secret, redirect_url) nie mogą być ustawione ani w YAML, ani w środowisku. Przy protocol: oidc nie może być ustawione żadne ustawienie saml. W przeciwnym razie uruchamianie zostaje przerwane.
  • Zmiana protokołu zmienia każdy identyfikator principala. Identyfikator zapisywany we wpisach logu requestów jest wyprowadzany z protokołu, dostawcy tożsamości i podmiotu, więc ta sama osoba po zmianie występuje jako nowy principal.
SAML wymaga uprawnienia licencyjnego saml oprócz sso. Jak każda włączona konfiguracja SSO blokuje w razie błędu (fail closed): uruchamianie zostaje przerwane, gdy brakuje któregokolwiek uprawnienia lub konfiguracja jest nieprawidłowa. Gateway nigdy nie wraca do OIDC ani do niechronionego Dashboardu.

Skonfiguruj SAML

Ta sama konfiguracja za pomocą zmiennych środowiskowych, które nadpisują wartości z YAML:
Wspólne ustawienia z sekcji Tożsamość i dopuszczanie zachowują swoje znaczenie.

Zarejestruj gateway

Gateway udostępnia dwa adresy URL, oba poniżej skonfigurowanego BASE_PATH:
1

Utwórz aplikację SAML 2.0 u dostawcy tożsamości

Zaimportuj adres URL metadanych dostawcy usług, jeśli dostawca to obsługuje, a gateway już działa. W przeciwnym razie wpisz ręcznie adres ACS z bindingiem HTTP-POST oraz entity ID (audience).
2

Podpisz asercję

Sama asercja musi być podpisana algorytmem RSA-SHA256 lub silniejszym i kluczem RSA o długości co najmniej 2048 bitów. Podpisanie samej odpowiedzi nie wystarcza. Nie szyfruj asercji. Gateway wysyła niepodpisane żądania przez HTTP-Redirect.
3

Wysyłaj stabilny podmiot i używane atrybuty

Użyj trwałego (persistent) NameID albo wysyłaj niezmienny identyfikator użytkownika jako atrybut i wskaż go w principal_attribute. Udostępnij atrybut dla ścieżki użytkownika oraz, jeśli używasz admin_groups lub mapowań grup, atrybut grup zawierający tylko grupy potrzebne gatewayowi.
4

Przekaż gatewayowi metadane dostawcy tożsamości

Ustaw idp_metadata_url albo pobierz metadane i ustaw idp_metadata_file. Metadane muszą opisywać jednego dostawcę tożsamości z punktem logowania HTTP-Redirect i co najmniej jednym certyfikatem podpisującym.
5

Uruchom gateway i zaloguj się

Otwórz /sso/login poniżej skonfigurowanego BASE_PATH. Jeśli logowanie się nie powiedzie, sprawdź powód w sekcji Powody odrzuconych logowań.
Te kroki używają ogólnych pojęć SAML 2.0; nazwy ustawień różnią się między dostawcami tożsamości. Logowanie SAML zostało dotąd zweryfikowane wyłącznie z testowym dostawcą tożsamości, więc pierwsze wdrożenie ze swoim dostawcą traktuj jako integrację do przetestowania, a nie sprawdzony przepis.

Atrybuty i principal

user_path_claim i groups_claim wskazują atrybuty SAML, bezpośrednio przez Name atrybutu albo przez alias w saml.attributes:
  • Alias przesłania atrybut SAML o tej samej nazwie.
  • Atrybut ścieżki użytkownika musi mieć dokładnie jedną wartość; otaczające ją białe znaki są usuwane. Wartości grup nie są przycinane i są porównywane dokładnie w takiej postaci, w jakiej zostały wysłane. Atrybut grup z jedną pustą wartością oznacza brak grup, a atrybut z wartością nietekstową odrzuca logowanie z powodem claim_mapping_failed, gdy ustawiono admin_groups lub mapowania grup.
  • Asercja bez atrybutu grup, która zamiast niego zawiera atrybut Entra ID http://schemas.microsoft.com/claims/groups.link (wysyłany dla osób w ponad 150 grupach), jest odrzucana z powodem groups_overage, gdy ustawiono admin_groups lub mapowania grup. Zobacz Ograniczenia.
  • Zmiana protocol albo atrybutu, na który user_path_claim lub groups_claim wskazują przez saml.attributes, kończy istniejące sesje, jak opisano w sekcji Gdy zmienia się konfiguracja.
  • allowed_domains i domyślne user_path_claim: email odczytują atrybut o nazwie lub aliasie email. Ścieżka użytkownika jest zamieniana na małe litery tylko przy user_path_claim: email lub user_path_case_insensitive: true.
  • Principalem jest NameID albo principal_attribute, jeśli jest ustawione. Tymczasowy (transient) NameID zmienia się przy każdym logowaniu i jest odrzucany, chyba że ustawiono principal_attribute.

Zaufanie do adresu e-mail

trust_email decyduje o tym, czy atrybut e-mail jest uznawany za zweryfikowany adres e-mail. Domyślnie ma wartość false, ponieważ SAML nie ma odpowiednika email_verified z OIDC: podpis dowodzi, że dostawca tożsamości wysłał adres, a nie że go sprawdził. Ścieżka użytkownika jest też zakresem dostępu sesji, więc jeśli osoby mogą edytować własny adres e-mail u dostawcy tożsamości, ktoś mógłby ustawić adres współpracownika i zalogować się na jego ścieżce. Bez trust_email uruchamianie odrzuca konfigurację zależną od adresu e-mail:
  • user_path_claim, który go odczytuje, w tym domyślne user_path_claim: email;
  • allowed_domains;
  • groups_claim, który go odczytuje, gdy ustawiono admin_groups lub mapowania grup.
Wybierz więc jedną z możliwości:
Kontrola przy starcie rozpoznaje wyłącznie nazwy: email, atrybut z aliasem email oraz znane atrybuty e-mail http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.xmlsoap.org/claims/EmailAddress, mail, email, EmailAddress, User.Email, urn:oid:0.9.2342.19200300.100.1.3 i urn:oid:1.2.840.113549.1.9.1, wszystkie porównywane bez rozróżniania wielkości liter, bezpośrednio lub przez alias. Atrybut, który pod inną nazwą zawiera adres e-mail albo dowolną inną wartość edytowalną przez użytkowników, przechodzi kontrolę. Nigdy nie używaj w user_path_claim ani groups_claim atrybutu, który użytkownik może edytować.

Co jest sprawdzane w każdej odpowiedzi

Logowanie udaje się tylko wtedy, gdy spełnione są wszystkie poniższe warunki. Każde niepowodzenie ma własny powód odrzucenia.
  • Odpowiada na logowanie rozpoczęte przez tę przeglądarkę. Podpisane ciasteczko transakcji (ważne 10 minut), RelayState i InResponseTo muszą się zgadzać.
  • Jest zaadresowana do tego gatewaya. Destination i Recipient są równe acs_url, a odbiorcą (audience) jest entity ID gatewaya.
  • Pochodzi od skonfigurowanego dostawcy tożsamości. Wystawcą jest entity ID z metadanych.
  • Sama asercja jest podpisana aktualnie ważnym certyfikatem podpisującym z metadanych, algorytmem RSA-SHA256 lub silniejszym i kluczem o długości co najmniej 2048 bitów. Jeśli KeyInfo podpisu zawiera certyfikat, musi to być ten certyfikat; podpis bez KeyInfo jest sprawdzany każdym zaufanym certyfikatem, jak podczas rotacji certyfikatu.
  • Jest dokładnie jedna asercja i nie jest ona zaszyfrowana.
  • Mieści się w swoim oknie ważności, z tolerancją 60 sekund na różnicę zegarów.
  • Dostawca tożsamości zgłasza sukces.
  • Wskazuje stabilny podmiot: NameID inny niż tymczasowy albo principal_attribute.
  • Nie była wcześniej użyta. Zobacz Ochrona przed powtórzeniem.
  • Jest małym, zwykłym dokumentem XML: formularz o rozmiarze do 1 MiB, najwyżej 900 elementów XML, bez DTD, komentarzy i instrukcji przetwarzania.
Każda wartość z asercji używana przy logowaniu (podmiot, atrybuty i warunki takie jak audience i okno ważności) jest odczytywana z asercji w postaci zweryfikowanej przez jej podpis, nigdy z reszty dokumentu. Część kontroli porównuje z oczekiwaniami gatewaya wartości spoza podpisu asercji: RelayState jest polem przesłanego formularza, a Destination, InResponseTo, Issuer i status odpowiedzi należą do koperty odpowiedzi, którą podpis obejmuje tylko wtedy, gdy dostawca tożsamości podpisuje także odpowiedź. Żadna z tych wartości nie służy jako tożsamość. Następnie dopuszczanie działa tak jak dla OIDC.

Metadane dostawcy tożsamości

Z pliku. Plik jest odczytywany raz. Plik nieczytelny lub nieprawidłowy przerywa uruchamianie, a po rotacji certyfikatu podpisującego przez dostawcę tożsamości trzeba podmienić plik i zrestartować gateway. Z adresu URL. Gateway pobiera metadane przy starcie, a potem co metadata_refresh_interval, więc opublikowana tam rotacja certyfikatu jest uwzględniana bez restartu. Nieudane odświeżenie zachowuje ostatnie poprawne metadane. Jeśli adres URL jest nieosiągalny przy starcie, gateway i tak się uruchamia, logowania odpowiadają kodem 503 z powodem identity_provider_unavailable, a pobieranie jest ponawiane w tle (5 sekund, podwajane do 5 minut). Ustaw require_discovery: true (PRO_SSO_REQUIRE_DISCOVERY=true), aby zamiast tego był to błąd uruchamiania. Metadane z obu źródeł nie są używane po upływie ich validUntil; logowania są wtedy niedostępne do czasu załadowania nowszych metadanych.

Co może zmienić odświeżenie

Odświeżenie może zastąpić certyfikaty podpisujące, adres URL logowania i validUntil. Nie może zmienić entity ID dostawcy tożsamości: takie metadane są odrzucane, bieżące metadane pozostają w użyciu, a w logu zapisywany jest błąd. Aby przejść na inne entity ID, zrestartuj gateway. Kto kontroluje adres URL metadanych, może opublikować własny certyfikat podpisujący. Dlatego każde odświeżenie zmieniające zaufane certyfikaty jest logowane na poziomie ostrzeżenia, z odciskami SHA-256 w polach added_fingerprints i removed_fingerprints:
Ustaw alert na tę linię. Przy starcie logowane są odciski, którym gateway ufa.

Przypinanie certyfikatów

Aby rotacja nie była akceptowana automatycznie, podaj odciski SHA-256 certyfikatów podpisujących dostawcy tożsamości:
Odciski są zapisane szesnastkowo, bez rozróżniania wielkości liter, z opcjonalnymi dwukropkami. Zaufane są tylko wymienione certyfikaty, zarówno dla pliku metadanych, jak i adresu URL. Metadane bez żadnego z nich przerywają uruchamianie; przy odświeżeniu są odrzucane, a w użyciu pozostają ostatnie poprawne metadane. Aby przeprowadzić rotację, dodaj nowy odcisk, zanim dostawca tożsamości się przełączy, a stary usuń później. Każdy krok wymaga restartu.

Sesje i wylogowanie

Sesja kończy się po session_ttl albo w chwili SessionNotOnOrAfter z asercji, jeśli ta przypada wcześniej. Asercja, której SessionNotOnOrAfter już minęło, jest odrzucana. Wylogowanie kończy sesję GoModel, a potem przekierowuje do provider_logout_url, jeśli jest ustawione, tak jak dla OIDC; zobacz Wylogowanie na wszystkich replikach.

Ochrona przed powtórzeniem

Każda asercja jest akceptowana raz. Gateway pamięta identyfikatory użytych asercji do czasu ich wygaśnięcia, w pamięci i w skonfigurowanym backendzie storage.
  • PostgreSQL lub MongoDB: powtórzona asercja jest odrzucana na każdej replice współdzielącej storage. Dwie repliki, które otrzymają tę samą asercję w tej samej chwili, mogłyby obie ją zaakceptować; wymaga to dodatkowo ciasteczka transakcji danej osoby.
  • SQLite (domyślnie): ochrona działa w obrębie jednej instancji. Uruchamiaj jedną replikę, tak jak w przypadku wylogowania; gateway zapisuje ostrzeżenie przy starcie.
  • Storage niedostępny: logowanie jest odrzucane z powodem replay_check_unavailable.

Ograniczenia

  • Około 850 grup na osobę. Każda wartość grupy to jeden element XML, a odpowiedź zawierająca ponad 900 elementów jest odrzucana z powodem too_many_elements. Limitu nie można konfigurować. Filtruj u dostawcy tożsamości: wysyłaj tylko grupy przypisane do aplikacji albo te wymienione w admin_groups i group_mappings.
  • Entra ID: najwyżej 150 grup w asercji. Powyżej tej liczby Entra ID zamiast grup wysyła http://schemas.microsoft.com/claims/groups.link, a gdy ustawiono admin_groups lub mapowania grup, logowanie jest odrzucane z powodem groups_overage. Wysyłaj tylko grupy przypisane do aplikacji.
  • Brak logowania rozpoczynanego u dostawcy tożsamości. Logowanie musi zaczynać się w gatewayu (/sso/login poniżej skonfigurowanego BASE_PATH). Niezamówione odpowiedzi są odrzucane.
  • Brak zaszyfrowanych asercji. Są odrzucane z powodem encrypted_assertion.
  • Brak single logout SAML. Gateway nie wysyła żądań wylogowania SAML i nie przetwarza takich żądań od dostawcy tożsamości. Wylogowanie kończy sesję GoModel; sesja u dostawcy tożsamości kończy się tylko przez przekierowanie do provider_logout_url.
  • Jeden dostawca tożsamości na gateway.
Ostatnia modyfikacja 18 listopada 2026