Genel Bakış

Genel Bakış

SAML (Security Assertion Markup Language), Tek Oturum Açma (SSO) özelliğini etkinleştiren, yaygın olarak kullanılan bir kimlik doğrulama protokolüdür. Kullanıcıların bir Kimlik Sağlayıcı (IdP) ile bir kez kimlik doğrulaması yapmasına ve tekrar giriş yapmaya gerek kalmadan birden fazla hizmete erişim sağlamasına olanak tanır.

Ortam Değişkenlerine Dayalı Kimlik Doğrulama Yöntemi Etkinleştirme

Aşağıdaki tablo, ortam değişkeni ayarlarına bağlı olarak hangi kimlik doğrulama yönteminin etkinleştirildiğini gösterir:

SAML Sertifika Formatı ve Yapılandırması

SAML_CERT ortam değişkeni, SAML Yanıtlarını doğrulamak için Kimlik Sağlayıcısının (IdP) imzalama sertifikasını belirtmek amacıyla kullanılır. Bu sertifika PEM formatında sağlanmalı ve aşağıdaki yollardan biriyle belirtilebilir:

Dosya Yolu Olarak (Göreceli veya Mutlak)

SAML_CERT bir dosya yoluna ayarlanmışsa, uygulama sertifikayı belirtilen dosyadan yükleyecektir. Hem göreli yollar hem de mutlak yollar desteklenmektedir.

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

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

Örnek Dosya İçeriği (idp-cert.pem):

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

Tek Satırlık PEM Dizgisi Olarak

Sertifika ayrıca tek satırlık bir PEM dizgisi (Base64 kodlu, satır sonları olmadan) olarak da sağlanabilir.

SAML_CERT="MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W=="

Bu format, sertifikayı doğrudan ortam değişkenlerinde saklarken kullanışlıdır.

Çok Satırlı PEM Dizgisi Olarak (\n kaçış dizileriyle)

Sertifika, yeni satırların \n olarak temsil edildiği çok satırlı bir PEM dizgisi olarak da sağlanabilir.

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

Bu format, .env dosyalarında sertifikaları yapılandırırken tam PEM yapısını korumak için kullanışlıdır.

Sertifika Formatı Gereksinimleri

• Sertifika her zaman PEM formatında (Base64 kodlu X.509 sertifikası) olmalıdır.
• Bir dosya olarak sağlandığında, geçerli bir RFC7468 katı metinsel mesaj PEM formatında olmalıdır.
• Tek satırlık bir sertifika kullanırken, değer içinde satır sonu (line break) olmadığından emin olun.
• Çok satırlı bir dizge kullanırken, yeni satırların \n kaçış dizileri olarak temsil edildiğinden emin olun.

Daha fazla ayrıntı için node-saml documentation bölümüne bakın.

SAML Özniteliklerine Dayalı Görünen Kullanıcı Adı Belirleme Akışı

SAML kimlik doğrulamasında, görünen kullanıcı adı aşağıdaki akışa göre belirlenir.

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

Belirleme Kuralları

1. Eğer SAML_NAME_CLAIM sağlanmışsa, değeri görünen kullanıcı adı olarak kullanılır.
2. Hem SAML_GIVEN_NAME_CLAIM hem de SAML_FAMILY_NAME_CLAIM sağlanmışsa, kullanıcı adını oluşturmak için ilgili değerleri birleştirilir.
3. Yalnızca SAML_GIVEN_NAME_CLAIM sağlanmışsa, değeri kullanılır.
4. Yalnızca SAML_FAMILY_NAME_CLAIM sağlanmışsa, değeri kullanılır.
5. Eğer SAML_USERNAME_CLAIM sağlanmışsa, değeri kullanılır.
6. Yukarıdaki özniteliklerden hiçbiri sağlanmazsa, görünen kullanıcı adı olarak SAML_EMAIL_CLAIM kullanılır.

Bu akışı takip ederek, SAML kimlik doğrulaması sırasında uygun bir kullanıcı adı belirlenir.

Yapılandırma Örnekleri

• Auth0