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: samlustawienia klienta OIDC (issuer_url,client_id,client_secret,redirect_url) nie mogą być ustawione ani w YAML, ani w środowisku. Przyprotocol: oidcnie może być ustawione żadne ustawieniesaml. 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.
Skonfiguruj SAML
Wspólne ustawienia z sekcji
Tożsamość i dopuszczanie zachowują
swoje znaczenie.
Zarejestruj gateway
Gateway udostępnia dwa adresy URL, oba poniżej skonfigurowanegoBASE_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 ustawionoadmin_groupslub 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 powodemgroups_overage, gdy ustawionoadmin_groupslub mapowania grup. Zobacz Ograniczenia. - Zmiana
protocolalbo atrybutu, na któryuser_path_claimlubgroups_claimwskazują przezsaml.attributes, kończy istniejące sesje, jak opisano w sekcji Gdy zmienia się konfiguracja. allowed_domainsi domyślneuser_path_claim: emailodczytują atrybut o nazwie lub aliasieemail. Ścieżka użytkownika jest zamieniana na małe litery tylko przyuser_path_claim: emaillubuser_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 ustawionoprincipal_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ślneuser_path_claim: email;allowed_domains;groups_claim, który go odczytuje, gdy ustawionoadmin_groupslub mapowania grup.
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),
RelayStateiInResponseTomuszą się zgadzać. - Jest zaadresowana do tego gatewaya.
DestinationiRecipientsą równeacs_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
KeyInfopodpisu zawiera certyfikat, musi to być ten certyfikat; podpis bezKeyInfojest 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.
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 cometadata_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 ivalidUntil. 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:
Przypinanie certyfikatów
Aby rotacja nie była akceptowana automatycznie, podaj odciski SHA-256 certyfikatów podpisujących dostawcy tożsamości:Sesje i wylogowanie
Sesja kończy się posession_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 wadmin_groupsigroup_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 ustawionoadmin_groupslub mapowania grup, logowanie jest odrzucane z powodemgroups_overage. Wysyłaj tylko grupy przypisane do aplikacji. - Brak logowania rozpoczynanego u dostawcy tożsamości. Logowanie musi
zaczynać się w gatewayu (
/sso/loginponiżej skonfigurowanegoBASE_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.