Pamiętaj, że dostarczamy również możliwość integracji poprzez Microsoft Entra ID - jest to rozwiązanie prostsze i szybsze. Aby dowiedzieć się więcej, kliknij tutaj.
Integracja z aplikacją za pomocą SAML 2.0
Instrukcja dla administratora Identity Providera (IdP)
1. Informacje ogólne
Aplikacja obsługuje logowanie jednokrotne (SSO) za pomocą protokołu SAML 2.0.
W ramach integracji:
Twój system tożsamości (IdP – Identity Provider) odpowiada za uwierzytelnienie użytkownika.
Aplikacja pełni rolę SP (Service Provider).
Po poprawnym uwierzytelnieniu IdP przekazuje do aplikacji odpowiedź SAML zawierającą informacje o zalogowanym użytkowniku.
Instrukcja jest niezależna od konkretnego dostawcy tożsamości. Możesz użyć m.in.:
Auth0
Okta
ADFS
PingFederate
innego systemu obsługującego SAML 2.0
Uwaga: Nazwy sekcji, pól i przycisków mogą się różnić w zależności od dostawcy tożsamości.
2. Rozpoczęcie integracji – przekaż nam IdP Metadata URL
Pierwszym krokiem jest udostępnienie nam metadanych Twojego Identity Providera (IdP) oraz nazwy domeny, pod którą będą logowali się użytkownicy.
Wymagany jest URL do metadanych IdP
Przekaż nam IdP Metadata URL, czyli adres URL, pod którym dostępny jest dokument XML zawierający metadane Twojego dostawcy tożsamości.
Przykład:
Ważne: Sam plik XML nie jest wystarczający. Wymagany jest URL, pod którym metadane są dostępne.
Metadata URL powinien:
używać protokołu HTTPS,
prowadzić bezpośrednio do dokumentu XML z metadanymi SAML,
być dostępny dla systemu aplikacji,
nie wymagać logowania użytkownika,
pozostać dostępny pod tym samym adresem podczas korzystania z integracji.
Metadane IdP zawierają informacje niezbędne do komunikacji SAML, w szczególności:
Entity ID IdP,
adres usługi Single Sign-On (SSO),
informacje o obsługiwanych bindingach SAML,
publiczny certyfikat X.509 używany do weryfikacji podpisów SAML,
pozostałe informacje wymagane do konfiguracji połączenia.
Dzięki temu wszystkie wymagane informacje dotyczące IdP są dostępne w jednym dokumencie pod jednym adresem URL.
Gdzie znaleźć Metadata URL?
W zależności od dostawcy może on być nazwany np.:
IdP Metadata URL
Identity Provider Metadata URL
Federation Metadata URL
SAML Metadata URL
Metadata Endpoint
Federation Metadata Endpoint
Dodatkowo w mailu z danymi przekaż nam nazwę domeny, pod którą będą logowali się użytkownicy do systemu eRecruiter, np. nazwadomeny.pl
3. Konfiguracja po stronie eRecruiter
Po otrzymaniu od Ciebie IdP Metadata URL rozpoczniemy konfigurację integracji SAML po naszej stronie.
Po zakończeniu tej konfiguracji otrzymasz od nas SP Metadata URL.
SP Metadata URL będzie zawierał metadane naszej aplikacji jako Service Providera (SP).
Przykład:
Ważne: To właśnie ten adres należy wykorzystać w kolejnym kroku do skonfigurowania aplikacji SAML w Twoim IdP.
4. Konfiguracja aplikacji SAML w IdP
Po otrzymaniu od nas SP Metadata URL zaloguj się do panelu administracyjnego swojego dostawcy tożsamości.
Utwórz nową aplikację lub integrację obsługującą SAML 2.0.
W zależności od dostawcy opcja może nazywać się np.:
SAML Application
SAML 2.0 Application
Custom SAML Application
Enterprise Application
SAML Service Provider
SSO Application
Nadaj aplikacji nazwę umożliwiającą jej łatwą identyfikację, np. eRecruiter.
5. Import metadanych SP
W konfiguracji utworzonej aplikacji SAML znajdź sekcję dotyczącą konfiguracji Service Providera.
Może ona nazywać się np.:
SAML Settings
Basic SAML Configuration
Service Provider Configuration
Application Configuration
SSO Configuration
Import za pomocą SP Metadata URL
Jeżeli Twój IdP umożliwia import metadanych za pomocą URL:
Wybierz opcję importu metadanych SAML.
Wprowadź otrzymany od nas SP Metadata URL.
Uruchom import.
Sprawdź, czy IdP poprawnie pobrał konfigurację.
Zapisz konfigurację.
Import metadanych za pomocą URL jest zalecaną metodą konfiguracji.
Metadane zawierają wszystkie informacje wymagane do skonfigurowania połączenia, w tym informacje dotyczące endpointów oraz certyfikatów i kluczy publicznych wymaganych przez konfigurację SAML.
Dzięki wykorzystaniu metadanych nie ma potrzeby ręcznego przepisywania poszczególnych parametrów.
Jeżeli IdP nie obsługuje importu metadanych za pomocą URL
Otwórz otrzymany SP Metadata URL, pobierz lub wyświetl dokument XML i wykorzystaj zawarte w nim informacje do skonfigurowania aplikacji SAML.
W takim przypadku wszystkie wymagane wartości należy odczytać bezpośrednio z naszego dokumentu metadanych.
6. Najważniejsze parametry SP
Jeżeli Twój IdP wymaga ręcznego skonfigurowania parametrów na podstawie metadanych, zwróć szczególną uwagę na poniższe wartości.
Entity ID
Wprowadź dokładnie wartość Entity ID znajdującą się w naszych metadanych SP.
W zależności od dostawcy pole może nazywać się:
Entity ID
Audience
Audience URI
SP Entity ID
Service Provider Entity ID
ACS URL
Wprowadź dokładnie adres znajdujący się w naszych metadanych SP.
W zależności od dostawcy pole może nazywać się:
ACS URL
Assertion Consumer Service URL
Single Sign-On URL
SSO URL
Reply URL
Callback URL
Ważne: Nie należy zastępować ACS URL adresem strony logowania aplikacji.
ACS URL jest adresem, na który IdP przesyła odpowiedź SAML po poprawnym uwierzytelnieniu użytkownika.
Certyfikaty i pozostałe parametry
Jeżeli Twój IdP wymaga dodatkowych parametrów lub informacji kryptograficznych, odczytaj je bezpośrednio z naszego SP Metadata URL.
Wszystkie wymagane informacje są dostępne w metadanych.
7. Konfiguracja atrybutów użytkownika
IdP musi przekazywać do aplikacji w odpowiedzi SAML dwa wymagane atrybuty:
Nazwa atrybutu SAML | Wymaganie | Opis |
UserId | Wymagany | Unikalny i stabilny identyfikator użytkownika |
Wymagany | Adres e-mail użytkownika |
W zależności od dostawcy atrybuty te mogą być konfigurowane w sekcjach nazywanych:
Claims
Attributes
Attribute Statements
User Attributes
Claims Mapping
Attribute Mapping
W tej instrukcji określamy je jako atrybuty SAML (claims).
7.1. Atrybut UserId
Dodaj atrybut SAML o dokładnej nazwie:
UserId
Jego wartością powinien być unikalny identyfikator użytkownika w Twoim systemie tożsamości.
Może to być np.:
identyfikator pracownika,
employeeID,
object ID,
user ID,
userPrincipalName,
inny identyfikator jednoznacznie identyfikujący użytkownika.
Przykład
Jeżeli użytkownik w IdP posiada:
employeeID = 123456
odpowiedź SAML powinna zawierać:
UserId = 123456
Wymagania dotyczące UserId
Wartość UserId:
musi być unikalna dla każdego użytkownika,
musi jednoznacznie wskazywać użytkownika,
powinna być stabilna w czasie,
nie powinna zmieniać się podczas korzystania z aplikacji.
Ważne: Nie zalecamy używania adresu e-mail jako UserId, jeżeli adres e-mail może się zmienić.
Zmiana UserId może spowodować, że aplikacja potraktuje użytkownika jako inną osobę.
7.2. Atrybut Email
Dodaj drugi atrybut SAML o dokładnej nazwie:
Jego wartością powinien być aktualny adres e-mail użytkownika.
Przykład:
Email = [email protected]
7.3. Nazwy atrybutów
Nazwy atrybutów muszą być przekazywane dokładnie jako:
UserId
Nie należy zmieniać ich na inne nazwy, takie jak:
userid
userId
UserID
user_id
email
emailAddress
EmailAddress
Dostawca tożsamości może posiadać własne pola konfiguracyjne, takie jak:
Namespace
Name Format
Claim URI
Friendly Name
Attribute Type
Ich konfiguracja zależy od konkretnego IdP.
Najważniejsze: W końcowej odpowiedzi SAML przesyłanej do aplikacji muszą znajdować się atrybuty o dokładnych nazwach UserId oraz Email.
8. Przypisanie użytkowników do aplikacji
Po zakończeniu konfiguracji SAML nadaj użytkownikom lub grupom użytkowników dostęp do utworzonej aplikacji.
W zależności od IdP może to oznaczać np.:
przypisanie użytkownika do aplikacji,
przypisanie grupy do aplikacji,
nadanie użytkownikowi odpowiedniej roli,
włączenie aplikacji dla określonej grupy użytkowników.
Tylko użytkownicy posiadający dostęp do aplikacji SAML będą mogli korzystać z logowania SSO.
10. Test logowania
Po zakończeniu konfiguracji wykonaj test logowania za pomocą użytkownika przypisanego do aplikacji SAML.
Testowy użytkownik powinien:
mieć dostęp do aplikacji SAML w IdP,
posiadać poprawny i unikalny UserId,
posiadać poprawny adres Email,
otrzymać z IdP odpowiedź SAML zawierającą oba wymagane atrybuty.
Po poprawnej konfiguracji powyższych punktów wykonaj testowe logowanie:
Otwórz stronę logowania aplikacji system.erecruiter.pl
Wybierz opcję Zaloguj się domeną (lub równoważną) widoczną pod standardowym formularzem logowania.
W kolejnym oknie wpisz nazwę domeny, która została podana podczas zgłoszenia (np. twojafirma.pl) i kliknij Zaloguj.
Spróbuj zalogować się danymi domenowymi (konto w IdP).
Oczekiwany rezultat pierwszej próby:
Powinien pojawić się błąd związany z brakiem powiązania konta w aplikacji z kontem w IdP.
Komunikat może mieć postać:
„Zaloguj się loginem i hasłem, aby móc przejść do logowania domenowego”
Jeśli pojawi się inny błąd:
1. Sprawdź, czy wszystkie atrybuty (szczególnie UserId) są ustawione zgodnie z instrukcją.
2. Jeśli konfiguracja jest poprawna, prześlij zrzut ekranu z tej sekcji do zespołu wdrażającego wraz z informacją:
kiedy była próba logowania (data i godzina),
jaki błąd wystąpił (treść komunikatu).
Jeśli wszystkie kroki zostały wykonane i pojawił się oczekiwany błąd informujący o braku powiązania konta:
Prześlij do zespołu wdrażającego:
datę i godzinę testowej próby logowania,
proponowany termin włączenia logowania domenowego (data i godzina).
11. Co dalej po włączeniu logowania domenowego?
Gdy wszystkie powyższe kroki zostały wykonane i potwierdzono dzień oraz godzinę uruchomienia logowania domenowego:
Przygotuj komunikację wewnętrzną informującą użytkowników o:
dacie i godzinie uruchomienia logowania domenowego,
zmianie sposobu logowania (po tej dacie logowanie tradycyjnym loginem i hasłem nie będzie już możliwe).
Udostępnij użytkownikom bezpośredni link do logowania (bez konieczności ręcznego wpisywania domeny), np.:
W miejscu NazwaTwojejDomeny wpisz nazwę domeny wybraną do logowania (np. twojafirma.pl).
Poinformuj użytkowników, że:
przy pierwszym logowaniu po włączeniu SSO mogą zobaczyć informację, że ich konto nie jest powiązane z kontem w aplikacji,
w takiej sytuacji powinni:
2. zalogować się tradycyjnie (login i hasło aplikacji),
3. po zalogowaniu system automatycznie powiąże ich konto z kontem w IdP,
4. przy kolejnych logowaniach będą już logowani wyłącznie przez dostawcę tożsamości (SSO).
pamiętaj, że po uruchomieniu logowania domenowego, każdy istniejący użytkownik przy próbie logowania, dostanie informacje o tym, że jego konto nie jest powiązane z kontem erecruiter. W tej sytuacji wystarczy użyć loginu i hasła eRecruiter. Po zalogowaniu się do systemu, system będzie miał już powiązane konta i przy kolejnym logowaniu domeną użytkownik zostanie zalogowany bez użycia danych logowania eRecruiter.
dla nowozałożonych kont w systemie, w mailu powitalnym dla użytkownika wyślemy tzw magiclink - dzięki niemu nowi użytkownicy systemu nie będą musieli przeprowadzać łączenia konta eRecruiter z kontem domenowym. Po wejściu w link z wiadomości powitalnej, automatycznie parujemy dane domenowe użytkownika ze stworzonym kontem w systemie dzięki czemu od samego początku użytkownik będzie mógł logować się domenowo do swojego konta w eRecruiter
Integracja SAML a wiele tenantów
Jeżeli w swojej firmie korzystacie Państwo z kilku tenantów i chcielibyście dokonać integracji logowania z eRecruiter - poprosimy o bezpośredni kontakt z Państwa Opiekunem Klienta, który przekaże dalsze informacje w temacie i poinformuje o możliwościach technicznych.