Przegląd

Przegląd

SAML (Security Assertion Markup Language) to szeroko stosowany protokół uwierzytelniania, który umożliwia logowanie jednokrotne (Single Sign-On, SSO). Pozwala on użytkownikom na jednokrotne uwierzytelnienie się u dostawcy tożsamości (Identity Provider, IdP) i uzyskanie dostępu do wielu usług bez konieczności ponownego logowania.

Aktywacja metody uwierzytelniania na podstawie zmiennych środowiskowych

Poniższa tabela wskazuje, która metoda uwierzytelniania jest włączona w zależności od ustawień zmiennych środowiskowych:

Format i konfiguracja certyfikatu SAML

Zmienna środowiskowa SAML_CERT służy do określenia certyfikatu podpisywania dostawcy tożsamości (IdP) w celu weryfikacji odpowiedzi SAML. Certyfikat ten musi zostać dostarczony w formacie PEM i może zostać określony na jeden z poniższych sposobów:

Jako ścieżka pliku (względna lub bezwzględna)

Jeśli SAML_CERT jest ustawione na ścieżkę do pliku, aplikacja wczyta certyfikat ze wskazanego pliku. Obsługiwane są zarówno ścieżki względne, jak i ścieżki bezwzględne.

# Relative path (resolved based on the application root)
SAML_CERT=idp-cert.pem

# Absolute path
SAML_CERT=/path/to/idp-cert.pem

Przykładowa zawartość pliku (idp-cert.pem):

-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...
-----END CERTIFICATE-----

Jako jednowierszowy ciąg PEM

Certyfikat można również dostarczyć jako jednoliniowy ciąg PEM (zakodowany w Base64, bez znaków nowej linii).

SAML_CERT="MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W=="

Ten format jest przydatny podczas przechowywania certyfikatu bezpośrednio w zmiennych środowiskowych.

Jako wieloliniowy ciąg PEM (z sekwencjami ucieczki \n)

Certyfikat można również dostarczyć jako wieloliniowy ciąg PEM, w którym znaki nowej linii są reprezentowane jako \n.

SAML_CERT="-----BEGIN CERTIFICATE-----\nMIIDazCCAlOgAwIBAgIUKhXaFJGJJPx466rl...\n-----END CERTIFICATE-----\n"

Ten format jest przydatny podczas konfigurowania certyfikatów w plikach .env przy jednoczesnym zachowaniu pełnej struktury PEM.

Wymagania dotyczące formatu certyfikatu

• Certyfikat musi być zawsze w formacie PEM (certyfikat X.509 zakodowany w Base64).
• Jeśli zostanie dostarczony jako plik, musi być w poprawnym formacie RFC7468 strict textual message PEM.
• Podczas używania certyfikatu jednowierszowego upewnij się, że w wartości nie ma znaków nowej linii.
• Podczas używania wieloliniowego ciągu znaków upewnij się, że znaki nowej linii są reprezentowane jako sekwencje ucieczki \n.

Aby uzyskać więcej szczegółów, zapoznaj się z dokumentacją node-saml.

Przepływ ustalania wyświetlanej nazwy użytkownika na podstawie atrybutów SAML

W uwierzytelnianiu SAML wyświetlana nazwa użytkownika jest określana zgodnie z poniższym przepływem.

flowchart TD
    A[Start] --> B{{Is SAML_NAME_CLAIM available?}}
    B -- Yes --> C[Value of SAML_NAME_CLAIM]
    B -- No --> D{{Are both SAML_GIVEN_NAME_CLAIM & SAML_FAMILY_NAME_CLAIM available?}}
    D -- Yes --> E[Value of SAML_GIVEN_NAME_CLAIM / SAML_FAMILY_NAME_CLAIM]
    D -- No --> F{{Is only SAML_GIVEN_NAME_CLAIM available?}}
    F -- Yes --> G[Value of SAML_GIVEN_NAME_CLAIM]
    F -- No --> H{{Is only SAML_FAMILY_NAME_CLAIM available?}}
    H -- Yes --> I[Value of SAML_FAMILY_NAME_CLAIM]
    H -- No --> J{{Is SAML_USERNAME_CLAIM available?}}
    J -- Yes --> K[Value of SAML_USERNAME_CLAIM]
    J -- No --> L[Value of SAML_EMAIL_CLAIM]
    style C fill:#FFDEA5,stroke:#FFA500
    style E fill:#FFDEA5,stroke:#FFA500
    style G fill:#FFDEA5,stroke:#FFA500
    style I fill:#FFDEA5,stroke:#FFA500
    style K fill:#FFDEA5,stroke:#FFA500
    style L fill:#FFDEA5,stroke:#FFA500

Zasady określania

1. Jeśli podano SAML_NAME_CLAIM, jego wartość jest używana jako wyświetlana nazwa użytkownika.
2. Jeśli podano zarówno SAML_GIVEN_NAME_CLAIM, jak i SAML_FAMILY_NAME_CLAIM, ich odpowiadające im wartości są łączone w celu utworzenia nazwy użytkownika.
3. Jeśli podano tylko SAML_GIVEN_NAME_CLAIM, używana jest jego wartość.
4. Jeśli podano tylko SAML_FAMILY_NAME_CLAIM, używana jest jego wartość.
5. Jeśli podano SAML_USERNAME_CLAIM, używana jest jego wartość.
6. Jeśli żaden z powyższych atrybutów nie zostanie podany, SAML_EMAIL_CLAIM jest używany jako wyświetlana nazwa użytkownika.

Postępując zgodnie z tym przepływem, odpowiednia nazwa użytkownika jest określana podczas uwierzytelniania SAML.

Przykłady konfiguracji

• Auth0