Belajar Authentik - SAML Service Provider Integrations

#Pendahuluan

Di episode 14 kalian mengonfigurasi SAML provider pertama — Authentik kini bisa menerbitkan assertion. Episode 15 menjawab pertanyaan yang sesungguhnya: bagaimana menghubungkan provider itu dengan Service Provider (SP) nyata? Karena SAML hanya bermakna jika ada dua pihak, dan setiap SP punya cara integrasi serta tuntutan atribut yang sedikit berbeda.

Kuncinya ada pada dua hal: pertukaran metadata yang benar, dan pemetaan atribut yang sesuai ekspektasi SP. Kegagalan SAML hampir selalu berakar di salah satu dari keduanya — bukan di kriptografi, melainkan di data yang tidak cocok.

#Pertukaran Metadata: Dua Arah

Integrasi SAML yang sehat dimulai dari metadata, bukan menyalin nilai manual:

1. IdP → SP. Salin URL metadata IdP Authentik (https://authentik.example.com/application/saml/<slug>/metadata/) atau unduh XML-nya. Tempelkan di form SAML aplikasi. Banyak SP mengizinkan import via URL maupun upload file XML.
2. SP → IdP. Sebaliknya, jika SP menyediakan metadata XML, buat provider baru dengan tipe SAML Provider from Metadata. Authentik membaca endpoint, binding, dan sertifikat SP langsung dari metadata itu.

Keuntungan metadata: nilai yang rawan salah ketik — entity ID, ACS URL, sertifikat — berpindah secara otomatis dan akurat. Sebagian aplikasi tidak mendukung ekspor metadata; untuk itu, isi manual diperlukan dengan membaca dokumentasinya.

#Studi Kasus SP Populer

Untuk GitLab, kalian memasang di /etc/gitlab/gitlab.rb blok OmniAuth yang mengarah ke metadata Authentik. GitLab mengambil ACS URL dan entity ID dari sisi aplikasi, sementara sertifikat IdP diambil dari metadata Authentik — sekali lagi, metadata menghapus sebagian besar kerja manual:

gitlab.rb — blok OmniAuth SAML

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    label: 'authentik',
    args: {
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
      idp_cert_fingerprint: '4E:1E:CD:67:4A:67:5A:E9:6A:D0:3C:E6:DD:7A:F2:44:2E:76:00:6A',
      idp_sso_target_url: 'https://authentik.example.com/application/saml/gitlab/',
      issuer: 'https://gitlab.example.com',
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
      attribute_statements: {
        email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'],
        first_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'],
        nickname: ['http://schemas.goauthentik.io/2021/02/saml/username']
      }
    }
  }
]

Di sisi Authentik, ACS URL diisi https://gitlab.example.com/users/auth/saml/callback, Audience diisi https://gitlab.example.com, dan binding disarankan Post — beberapa versi GitLab bermasalah dengan binding Redirect karena URL assertion yang terlalu panjang.

Untuk Nextcloud, pasang aplikasi user_saml dari app store, pilih mode One Login, lalu tempel metadata IdP. Atur property mapping agar atribut Authentik (username, email, name, groups) mengalir ke user Nextcloud. Nextcloud memakai atribut uid untuk mencocokkan user.

Untuk Google Workspace, buka Apps → Web and mobile apps → Add app → Custom SAML app, lalu unggah metadata XML IdP. Di menu attribute mapping, samakan atribut SAML Authentik (firstname, lastname, email) dengan yang dikirim Authentik.

Untuk AWS SSO (IAM Identity Center), pilih Enable external identity provider, unggah metadata IdP Authentik sebagai IdP metadata, lalu konfigurasi atribut NameID dan formatnya agar cocok dengan nilai persistent Authentik.

#Pemetaan Atribut Sesuai Ekspektasi SP

Sering kali SP menuntut atribut yang belum tersedia di mapping bawaan. Misalnya SP meminta atribut role untuk kontrol akses:

Property mapping SAML — role dari status user

return "admin" if request.user.is_superuser else "user"

Property mapping SAML — role dari keanggotaan grup

return "admin" if ak_is_group_member(request.user, name="admin") else "member"

Buat mapping dengan SAML Attribute Name sesuai yang diminta SP, pilih pada provider, dan uji dengan login. Property mapping yang mengembalikan None akan dilewati Authentik — sehingga ekspresi yang tidak menemukan nilai tidak memecah assertion.

#Troubleshooting SAML

SAML sulit di-debug karena pesannya terbungkus XML dan sering lewat beberapa redirect. Alat paling penting: ekstensi browser SAML tracer (tersedia untuk Firefox dan Chrome). Ia menampilkan seluruh permintaan dan respons SAML di setiap login — termasuk assertion, atribut, dan signature.

Masalah yang paling sering muncul:

• Signature validation error — sertifikat di sisi SP tidak cocok dengan signing certificate Authentik. Pastikan public key yang diimpor SP benar, dan tidak kedaluwarsa.
• Audience/Entity ID mismatch — nilai Audience di Authentik tidak sama dengan entity ID SP. Salah ketik satu karakter saja membuat SP menolak assertion.
• Time sync — SAML assertion berisi timestamp validitas. Server Authentik dan SP harus berselisih waktu seminimal mungkin. Gunakan NTP:

timedatectl status
ntpq -p

• Relay state — parameter yang membawa user kembali ke halaman semula. Jika hilang, user berakhir di halaman muka SP setelah login. Periksa dengan SAML tracer apakah relay state terbawa pada setiap lompatan.
• Atribut tidak muncul — periksa apakah SP menuntut atribut yang tidak dikirim Authentik, atau nama atributnya berbeda. SAML tracer menampilkan assertion mentah sehingga kalian bisa membandingkannya dengan yang diminta SP.
• NameID format tidak cocok — SP meminta format tertentu; pastikan NameID policy Authentik menghasilkan format itu.

#Menguji Integrasi SP

Setelah metadata dan atribut disiapkan, uji dengan alur yang tenang:

1. Buka aplikasi SP dan pilih opsi login SAML (misalnya tombol Sign in with Authentik di GitLab).
2. Login di portal Authentik — kalian harus diarahkan kembali ke aplikasi tanpa login kedua.
3. Buka SAML tracer dan periksa assertion terakhir: NameID, atribut, dan masa berlaku.
4. Periksa user yang muncul di aplikasi — email, nama, dan grup harus cocok dengan mapping yang kalian buat.

Strategi pengujian yang membatasi risiko: mulai dari satu user uji dan satu aplikasi, konfirmasi seluruh atribut benar, baru lalu beri akses ke seluruh organisasi. Sinkronkan juga kunci dan metadata antara kedua sisi setiap kali sertifikat Authentik diganti — perubahan sertifikat adalah momen paling rawan integrasi SAML "mendadak rusak".

#Penutup

Episode ini menghubungkan SAML provider Authentik dengan SP nyata: pertukaran metadata dua arah, studi kasus GitLab, Nextcloud, Google Workspace, dan AWS, pemetaan atribut lewat property mappings kustom, serta teknik troubleshooting dengan SAML tracer, pengecekan signature, audience mismatch, dan sinkronisasi waktu.

Pola yang harus kalian bawa: metadata meminimalkan kesalahan manual, atribut harus cocok dengan nama yang diminta SP, dan assertion mentah di SAML tracer adalah sumber kebenaran diagnosis. Di episode 16, kita membalik arah koneksi — dari Authentik sebagai IdP menjadi Authentik sebagai klien: OAuth sources (social login), menghubungkan GitHub, Google, dan Discord sebagai sumber login. Sampai jumpa!