SAML SSO

SnapOtter mendukung SAML 2.0 untuk single sign-on. Pengguna dapat login via penyedia identitas eksternal (Okta, Azure AD / Entra ID, Google Workspace, atau IdP SAML 2.0 standar apa pun) alih-alih autentikasi username/kata sandi lokal.

Fitur enterprise

SAML SSO memerlukan lisensi team atau enterprise dengan fitur saml_sso. Jika SAML_ENABLED=true disetel tanpa lisensi yang valid, rute SAML dilewati secara diam-diam dan peringatan dicatat.

Prasyarat

• Instance SnapOtter yang berjalan dan dapat dijangkau di URL publik
• EXTERNAL_URL disetel ke URL publik itu (mis. https://photos.example.com)
• Kunci lisensi team atau enterprise dengan fitur saml_sso
• Akses admin ke penyedia identitas SAML Anda

Mulai cepat

Tambahkan variabel lingkungan ini ke docker-compose.yml Anda:

services:
  snapotter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      SNAPOTTER_LICENSE_KEY: "your-license-key"
      SAML_ENABLED: "true"
      SAML_IDP_SSO_URL: "https://idp.example.com/sso/saml"
      SAML_IDP_CERTIFICATE: |
        MIICpDCCAYwCCQDU+pQ4pHgSpDANBgkqhkiG9w0BAQsFADAUMRIw
        ...your IdP's signing certificate in PEM format...
        EAYHKoZIzj0CAQYFK4EEACIDYgAE

Mulai ulang container. Tombol "Sign in with SAML" (atau label yang disetel oleh SAML_PROVIDER_NAME) muncul di halaman login.

Referensi konfigurasi

Variabel	Default	Deskripsi
SAML_ENABLED	false	Aktifkan login SAML.
SAML_IDP_SSO_URL		URL endpoint SSO IdP. Wajib saat SAML diaktifkan.
SAML_IDP_CERTIFICATE		Sertifikat penandatanganan X.509 IdP dalam format PEM (teks sertifikat itu sendiri, bukan path file). Wajib saat SAML diaktifkan.
EXTERNAL_URL		URL publik tempat SnapOtter dapat dijangkau. Wajib saat SAML diaktifkan.
SAML_ENTITY_ID	${EXTERNAL_URL}/api/auth/saml/metadata	SP Entity ID / Audience URI yang dikirim ke IdP.
SAML_CALLBACK_URL	${EXTERNAL_URL}/api/auth/saml/callback	URL Assertion Consumer Service (ACS).
SAML_AUTO_CREATE_USERS	true	Buat akun pengguna lokal secara otomatis saat login SAML pertama.
SAML_AUTO_LINK_USERS	false	Tautkan identitas SAML ke pengguna lokal yang ada jika alamat email cocok.
SAML_DEFAULT_ROLE	user	Peran yang diberikan ke pengguna SAML yang dibuat otomatis. Salah satu dari admin, editor, atau user.
SAML_PROVIDER_NAME		Label tampilan untuk tombol login SAML di frontend (mis. "Okta", "Azure AD"). Jika kosong, tombol bertuliskan "SAML".
SAML_USERNAME_ATTRIBUTE		Atribut assertion SAML yang digunakan sebagai username. Jika kosong, kembali ke local-part email, lalu NameID.
SAML_EMAIL_ATTRIBUTE	email	Atribut assertion SAML yang digunakan sebagai alamat email pengguna.

Server menolak untuk mulai jika SAML_ENABLED=true dan salah satu dari tiga variabel yang wajib (SAML_IDP_SSO_URL, SAML_IDP_CERTIFICATE, EXTERNAL_URL) tidak ada.

Catatan keamanan

Baik wantAuthnResponseSigned maupun wantAssertionsSigned dikodekan tetap (hardcoded) ke true. SnapOtter menolak respons SAML yang tidak ditandatangani atau ditandatangani secara tidak benar. Assertion dari IdP tepercaya diperlakukan sebagai email-terverifikasi.

Hanya login yang diinisiasi SP yang didukung. SnapOtter tidak mendukung login yang diinisiasi IdP (tidak diminta) atau Single Logout (SLO). Logout dari SnapOtter tidak membuat pengguna keluar dari IdP.

Metadata dan URL SP

IdP Anda membutuhkan tiga nilai dari SnapOtter:

Bidang	Nilai
ACS URL (Assertion Consumer Service)	${EXTERNAL_URL}/api/auth/saml/callback
Entity ID / Audience URI	${EXTERNAL_URL}/api/auth/saml/metadata
SP Metadata (XML)	GET ${EXTERNAL_URL}/api/auth/saml/metadata

Misalnya, jika EXTERNAL_URL adalah https://photos.example.com:

• ACS URL: https://photos.example.com/api/auth/saml/callback
• Entity ID: https://photos.example.com/api/auth/saml/metadata
• Endpoint metadata: https://photos.example.com/api/auth/saml/metadata (mengembalikan XML)

Beberapa IdP dapat mengimpor URL metadata SP secara langsung, yang mengisi otomatis ACS URL dan Entity ID.

Penyiapan penyedia

Okta

1. Di konsol admin Okta, buka Applications > Create App Integration.
2. Pilih SAML 2.0 dan klik Next.
3. Setel nama (mis. "SnapOtter") dan klik Next.
4. Konfigurasikan pengaturan SAML:
   • Single sign-on URL: ACS URL Anda (mis. https://photos.example.com/api/auth/saml/callback)
   • Audience URI (SP Entity ID): Entity ID Anda (mis. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EmailAddress
   • Application username: Email
5. Di bawah Attribute Statements, tambahkan email yang dipetakan ke user.email.
6. Klik Next, lalu Finish.
7. Buka tab Sign On, klik View SAML setup instructions, dan salin:
   • Identity Provider Single Sign-On URL ke SAML_IDP_SSO_URL
   • X.509 Certificate ke SAML_IDP_CERTIFICATE

Azure AD / Entra ID

1. Di portal Azure, buka Microsoft Entra ID > Enterprise applications > New application.
2. Klik Create your own application, beri nama "SnapOtter", dan pilih Integrate any other application you don't find in the gallery.
3. Buka Single sign-on > SAML dan klik Edit pada bagian Basic SAML Configuration:
   • Identifier (Entity ID): Entity ID Anda (mis. https://photos.example.com/api/auth/saml/metadata)
   • Reply URL (ACS URL): ACS URL Anda (mis. https://photos.example.com/api/auth/saml/callback)
4. Di bawah SAML Certificates, unduh Certificate (Base64).
5. Di bawah Set up SnapOtter, salin Login URL.
6. Setel SAML_IDP_SSO_URL ke Login URL dan SAML_IDP_CERTIFICATE ke isi sertifikat yang diunduh.
7. Tetapkan pengguna atau grup ke aplikasi di bawah Users and groups.

Google Workspace

1. Di konsol Google Admin, buka Apps > Web and mobile apps > Add app > Add custom SAML app.
2. Beri nama aplikasi "SnapOtter" dan klik Continue.
3. Di halaman Google Identity Provider details, salin SSO URL dan unduh Certificate. Klik Continue.
4. Konfigurasikan detail Service Provider:
   • ACS URL: ACS URL Anda (mis. https://photos.example.com/api/auth/saml/callback)
   • Entity ID: Entity ID Anda (mis. https://photos.example.com/api/auth/saml/metadata)
   • Name ID format: EMAIL
   • Name ID: Basic Information > Primary email
5. Klik Continue, lalu Finish.
6. Aktifkan aplikasi ON untuk unit organisasi Anda.
7. Setel SAML_IDP_SSO_URL ke SSO URL dari langkah 3 dan SAML_IDP_CERTIFICATE ke isi sertifikat yang diunduh.

IdP SAML 2.0 generik

Untuk penyedia identitas apa pun yang patuh SAML 2.0:

1. Buat aplikasi/service provider SAML baru di IdP Anda.
2. Setel ACS URL ke ${EXTERNAL_URL}/api/auth/saml/callback.
3. Setel Entity ID / Audience ke ${EXTERNAL_URL}/api/auth/saml/metadata.
4. Konfigurasikan IdP untuk mengirim email pengguna dalam atribut bernama email (atau setel SAML_EMAIL_ATTRIBUTE agar cocok dengan nama atribut IdP Anda).
5. Salin IdP SSO URL dan sertifikat penandatanganan ke SAML_IDP_SSO_URL dan SAML_IDP_CERTIFICATE.

Provisioning pengguna

Buat otomatis

Saat SAML_AUTO_CREATE_USERS bernilai true (default), akun pengguna lokal dibuat pertama kali seseorang login via SAML. Peran disetel ke SAML_DEFAULT_ROLE.

Username diturunkan dalam urutan ini:

1. Nilai atribut assertion yang ditentukan oleh SAML_USERNAME_ATTRIBUTE (jika disetel dan ada)
2. Local-part alamat email (semua yang sebelum @)
3. NameID SAML

Jika terjadi tabrakan username, sufiks numerik ditambahkan (mis. jane menjadi jane_2).

Tautan otomatis

Saat SAML_AUTO_LINK_USERS bernilai true, SnapOtter menautkan identitas SAML ke akun lokal yang ada jika alamat email cocok. Ini berguna saat Anda telah membuat akun pengguna sebelumnya dan ingin mereka mulai menggunakan SSO tanpa kehilangan data.

WARNING

Hanya aktifkan tautan otomatis jika Anda memercayai IdP SAML Anda untuk memverifikasi alamat email. Email yang tidak terverifikasi dari IdP yang salah konfigurasi dapat memungkinkan seseorang mengambil alih akun pengguna lain.

Pemetaan atribut

Bidang SnapOtter	Sumber	Konfigurasi
Email	Atribut assertion	SAML_EMAIL_ATTRIBUTE (default: email)
Username	Atribut assertion, email, atau NameID	SAML_USERNAME_ATTRIBUTE (lihat urutan penurunan di atas)
External ID	NameID	Selalu NameID SAML, tidak dapat dikonfigurasi

Penegakan SSO

Jika Anda ingin mewajibkan semua pengguna login via SAML (atau OIDC) dan memblokir login kata sandi lokal, aktifkan penegakan SSO:

1. Pastikan fitur enterprise sso_enforcement dilisensikan (tersedia pada paket team dan enterprise).
2. Di Admin Settings > Security, aktifkan SSO Enforcement.
3. Setel break-glass username: ini adalah satu-satunya akun lokal yang masih dapat login dengan kata sandi, untuk akses darurat jika IdP tidak dapat dijangkau.

Saat penegakan SSO aktif, setiap upaya login lokal (kecuali untuk pengguna break-glass) mengembalikan kesalahan 403 dengan pesan "Local password login is disabled. Please use SSO."

TIP

Selalu konfigurasikan break-glass username sebelum mengaktifkan penegakan SSO. Tanpanya, Anda bisa terkunci dari SnapOtter jika IdP Anda mati.

Menggunakan SAML bersama OIDC

SAML dan OIDC dapat diaktifkan secara bersamaan. Saat keduanya aktif, halaman login menampilkan tombol terpisah untuk setiap penyedia (diberi label oleh SAML_PROVIDER_NAME dan OIDC_PROVIDER_NAME). Pengguna dapat login dengan metode mana pun.

Kedua penyedia berbagi pengaturan buat-otomatis, tautan-otomatis, dan penegakan SSO yang sama secara independen: masing-masing memiliki variabel *_AUTO_CREATE_USERS, *_AUTO_LINK_USERS, dan *_DEFAULT_ROLE sendiri.

Pemecahan masalah

Validasi assertion gagal

Tanda tangan respons SAML atau tanda tangan assertion tidak dapat diverifikasi. Periksa:

• Sertifikat di SAML_IDP_CERTIFICATE cocok dengan sertifikat penandatanganan saat ini di IdP Anda (sertifikat berotasi, jadi periksa kedaluwarsa)
• Sertifikat dalam format PEM (dimulai dengan -----BEGIN CERTIFICATE-----)
• Sertifikat adalah teks lengkap, bukan path file
• ACS URL dan Entity ID yang dikonfigurasi di IdP Anda cocok persis dengan nilai SnapOtter (skema, host, port, path)

Atribut hilang

Jika username atau email kosong setelah login, IdP Anda mungkin tidak mengirim atribut yang diharapkan. Periksa:

• IdP Anda dikonfigurasi untuk merilis atribut email (atau apa pun yang disetel di SAML_EMAIL_ATTRIBUTE)
• Jika menggunakan SAML_USERNAME_ATTRIBUTE, verifikasi bahwa atribut itu disertakan dalam assertion
• Beberapa IdP memerlukan konfigurasi pemetaan atribut eksplisit sebelum merilis klaim

Selisih jam

Assertion SAML menyertakan kondisi stempel waktu (NotBefore, NotOnOrAfter). Jika jam server Anda dan jam IdP tidak sinkron, validasi assertion gagal. Jalankan NTP di kedua mesin untuk menjaga jam tetap selaras.

"SAML is enabled via env but saml_sso enterprise feature is not licensed"

Peringatan ini muncul di log server saat SAML_ENABLED=true tetapi lisensi tidak menyertakan fitur saml_sso. Verifikasi kunci lisensi dan paket Anda. Fitur saml_sso tersedia pada paket team dan enterprise.

Login mengalihkan kembali dengan kesalahan

Jika mengklik tombol login SAML mengalihkan kembali ke halaman login dengan kesalahan, periksa log server untuk detail. Penyebab umum:

• IdP SSO URL tidak dapat dijangkau dari server
• IdP menolak permintaan autentikasi (periksa log audit IdP)
• IdP mengembalikan respons yang tidak ditandatangani (SnapOtter memerlukan baik respons maupun assertion untuk ditandatangani)