OIDC / Single Sign-On

SnapOtter mendukung OpenID Connect (OIDC) untuk single sign-on. Pengguna dapat login dengan penyedia identitas eksternal seperti Keycloak, Authentik, atau Google alih-alih (atau bersama) autentikasi username/kata sandi lokal.

Lihat juga

SAML SSO | Provisioning SCIM | Pengguna, Peran & Izin

Mulai cepat

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

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      EXTERNAL_URL: "https://photos.example.com"
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

Redirect URI untuk penyedia Anda selalu:

${EXTERNAL_URL}/api/auth/oidc/callback

Misalnya, jika EXTERNAL_URL adalah https://photos.example.com, konfigurasikan redirect URI penyedia Anda sebagai https://photos.example.com/api/auth/oidc/callback.

Referensi konfigurasi

Variabel	Default	Deskripsi
OIDC_ENABLED	false	Aktifkan login OIDC. Tombol "Sign in with SSO" muncul di halaman login.
OIDC_ISSUER_URL		URL issuer penyedia. Harus mendukung OIDC Discovery (/.well-known/openid-configuration).
OIDC_CLIENT_ID		Client ID OAuth yang terdaftar dengan penyedia Anda.
OIDC_CLIENT_SECRET		Client secret OAuth.
OIDC_SCOPES	openid profile email	Daftar scope yang diminta, dipisahkan spasi.
OIDC_AUTO_CREATE_USERS	true	Buat akun pengguna lokal secara otomatis saat login OIDC pertama.
OIDC_DEFAULT_ROLE	user	Peran yang diberikan ke pengguna OIDC yang dibuat otomatis. Salah satu dari admin, editor, atau user.
OIDC_AUTO_LINK_USERS	false	Tautkan identitas OIDC ke pengguna lokal yang ada jika alamat email cocok.
OIDC_PROVIDER_NAME		Nama tampilan yang ditunjukkan pada tombol login (mis. "Keycloak", "Google"). Jika kosong, tombol bertuliskan "SSO".
OIDC_CLOCK_TOLERANCE	30	Toleransi selisih jam dalam detik untuk validasi token.
OIDC_USERNAME_CLAIM	preferred_username	Klaim ID token yang digunakan sebagai username untuk akun baru.
EXTERNAL_URL		URL publik tempat SnapOtter dapat dijangkau. Diperlukan agar OIDC membangun redirect URI yang benar.
COOKIE_SECRET	dihasilkan otomatis	Secret untuk menandatangani cookie sesi. Setel ini secara eksplisit saat menjalankan beberapa replika.

Panduan penyedia

Keycloak

1. Buat realm baru (atau gunakan yang sudah ada).
2. Buka Clients dan buat client baru:
   • Client ID: snapotter
   • Client authentication: On (confidential)
   • Authentication flow: Standard flow (Authorization Code)
3. Di bawah tab Settings client, setel Valid redirect URIs ke URL callback Anda (mis. https://photos.example.com/api/auth/oidc/callback).
4. Salin Client secret dari tab Credentials.
5. Setel OIDC_ISSUER_URL ke https://keycloak.example.com/realms/your-realm.

Authentik

1. Di antarmuka admin, buka Applications > Providers dan buat OAuth2/OpenID Provider baru.
   • Client type: Confidential
   • Redirect URIs: URL callback Anda
   • Signing key: Pilih key yang ada atau buat satu
2. Buat sebuah Application dan tautkan ke penyedia.
3. Salin Client ID dan Client Secret dari pengaturan penyedia.
4. Setel OIDC_ISSUER_URL ke https://authentik.example.com/application/o/snapotter/ (garis miring di akhir penting).

Google

1. Buka Google Cloud Console.
2. Buat proyek (atau pilih yang sudah ada).
3. Navigasi ke APIs & Services > OAuth consent screen dan konfigurasikan.
4. Buka APIs & Services > Credentials dan buat OAuth 2.0 Client ID:
   • Application type: Web application
   • Authorized redirect URIs: URL callback Anda
5. Salin Client ID dan Client secret.
6. Setel OIDC_ISSUER_URL ke https://accounts.google.com.
7. Setel OIDC_USERNAME_CLAIM ke email (Google tidak menyediakan preferred_username).

Provisioning pengguna

Buat otomatis

Saat OIDC_AUTO_CREATE_USERS bernilai true (default), akun pengguna lokal dibuat pertama kali seseorang login via OIDC. Username diambil dari klaim yang ditentukan oleh OIDC_USERNAME_CLAIM, dan peran disetel ke OIDC_DEFAULT_ROLE.

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

Tautan otomatis

Saat OIDC_AUTO_LINK_USERS bernilai true, SnapOtter menautkan identitas OIDC 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 penyedia OIDC Anda untuk memverifikasi alamat email. Email yang tidak terverifikasi dapat memungkinkan seseorang mengambil alih akun pengguna lain.

Menonaktifkan login lokal

OIDC tidak menonaktifkan login username/kata sandi lokal. Kedua metode tetap tersedia. Admin masih dapat login dengan kredensial lokal jika penyedia OIDC tidak dapat dijangkau.

Sertifikat self-signed

Jika penyedia OIDC Anda menggunakan sertifikat self-signed atau CA privat, mount CA bundle ke dalam container dan arahkan NODE_EXTRA_CA_CERTS ke sana:

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    volumes:
      - ./my-ca.pem:/etc/ssl/certs/custom-ca.pem:ro
    environment:
      NODE_EXTRA_CA_CERTS: /etc/ssl/certs/custom-ca.pem
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://auth.internal.example.com/realms/myrealm"
      OIDC_CLIENT_ID: "snapotter"
      OIDC_CLIENT_SECRET: "your-secret-here"

DANGER

Jangan setel NODE_TLS_REJECT_UNAUTHORIZED=0. Ini menonaktifkan semua verifikasi TLS dan merupakan risiko keamanan.

Pemecahan masalah

Ketidakcocokan redirect URI

Kesalahan paling umum. Periksa perbedaan berikut antara apa yang diharapkan penyedia Anda dan apa yang dikirim SnapOtter:

• http vs https - skema harus cocok persis
• Garis miring di akhir - beberapa penyedia ketat soal ini
• Nomor port - sertakan port jika non-standar
• Path - harus /api/auth/oidc/callback

Periksa ulang EXTERNAL_URL. Nilainya harus cocok dengan URL yang diketik pengguna di browser mereka.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

Penyedia OIDC menggunakan sertifikat yang tidak dipercaya oleh Node.js. Lihat Sertifikat self-signed di atas.

Kesalahan selisih jam

Jika jam server Anda dan jam penyedia OIDC tidak sinkron, validasi token bisa gagal. Naikkan OIDC_CLOCK_TOLERANCE (default 30 detik). Perbaikan yang lebih baik adalah menjalankan NTP di kedua mesin.

"OIDC provider unreachable"

SnapOtter mengambil dokumen discovery penyedia saat startup dan selama login. Periksa:

• Resolusi DNS dari dalam container Docker (docker exec snapotter nslookup auth.example.com)
• Aturan firewall antara container dan penyedia
• Nilai OIDC_ISSUER_URL - harus dapat dijangkau dari server, bukan hanya dari browser Anda

Klaim hilang

Jika username atau email kosong setelah login, penyedia Anda mungkin tidak mengembalikan klaim yang diharapkan. Verifikasi:

• Scope yang dikonfigurasi di OIDC_SCOPES menyertakan profile dan email
• Penyedia dikonfigurasi untuk menyertakan klaim yang ditentukan di OIDC_USERNAME_CLAIM dalam ID token
• Beberapa penyedia memerlukan konfigurasi mapper/scope eksplisit untuk merilis klaim