Gambaran Umum

Ikhtisar

SAML (Security Assertion Markup Language) adalah protokol autentikasi yang digunakan secara luas yang memungkinkan Single Sign-On (SSO). Protokol ini memungkinkan pengguna untuk melakukan autentikasi satu kali dengan Identity Provider (IdP) dan mendapatkan akses ke berbagai layanan tanpa perlu masuk kembali.

Aktivasi Metode Autentikasi Berdasarkan Variabel Lingkungan

Tabel berikut menunjukkan metode autentikasi mana yang diaktifkan tergantung pada pengaturan variabel lingkungan:

Format dan Konfigurasi Sertifikat SAML

Variabel lingkungan SAML_CERT digunakan untuk menentukan sertifikat penandatanganan Identity Provider (IdP) untuk memvalidasi Respons SAML. Sertifikat ini harus disediakan dalam format PEM dan dapat ditentukan dengan salah satu cara berikut:

Sebagai Jalur File (Relatif atau Absolut)

Jika SAML_CERT diatur ke jalur file, aplikasi akan memuat sertifikat dari file yang ditentukan. Baik jalur relatif maupun jalur absolut didukung.

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

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

Contoh Isi Berkas (idp-cert.pem):

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

Sebagai String PEM Satu Baris

Sertifikat juga dapat disediakan sebagai string PEM satu baris (dikodekan Base64, tanpa jeda baris).

SAML_CERT="MIICizCCAfQCCQCY8tKaMc0BMjANBgkqh...W=="

Format ini berguna saat menyimpan sertifikat secara langsung di dalam environment variables.

Sebagai String PEM Multi-Baris (dengan urutan escape \n)

Sertifikat juga dapat disediakan sebagai string PEM multi-baris di mana baris baru direpresentasikan sebagai \n.

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

Format ini berguna saat mengonfigurasi sertifikat di dalam file .env dengan tetap mempertahankan struktur PEM secara utuh.

Persyaratan Format Sertifikat

• Sertifikat harus selalu dalam format PEM (sertifikat X.509 yang dikodekan Base64).
• Jika disediakan sebagai file, file tersebut harus berupa format PEM pesan tekstual ketat RFC7468 yang valid.
• Saat menggunakan sertifikat satu baris, pastikan tidak ada jeda baris dalam nilainya.
• Saat menggunakan string multi-baris, pastikan baris baru direpresentasikan sebagai urutan escape \n.

Untuk detail lebih lanjut, lihat dokumentasi node-saml.

Alur Penentuan Nama Pengguna Tampilan Berdasarkan Atribut SAML

Dalam autentikasi SAML, nama pengguna yang ditampilkan ditentukan berdasarkan alur berikut.

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

Aturan Penentuan

1. Jika SAML_NAME_CLAIM disediakan, nilainya akan digunakan sebagai nama pengguna tampilan.
2. Jika SAML_GIVEN_NAME_CLAIM dan SAML_FAMILY_NAME_CLAIM keduanya disediakan, nilai yang sesuai akan digabungkan untuk membentuk nama pengguna.
3. Jika hanya SAML_GIVEN_NAME_CLAIM yang disediakan, nilainya akan digunakan.
4. Jika hanya SAML_FAMILY_NAME_CLAIM yang disediakan, nilainya akan digunakan.
5. Jika SAML_USERNAME_CLAIM disediakan, nilainya akan digunakan.
6. Jika tidak ada atribut di atas yang disediakan, SAML_EMAIL_CLAIM akan digunakan sebagai nama pengguna tampilan.

Dengan mengikuti alur ini, nama pengguna yang sesuai akan ditentukan selama autentikasi SAML.

Contoh Konfigurasi

• Auth0