Belajar Authentik - Migration from Other IdPs

#Pendahuluan

Setelah 28 episode, kalian sudah mahir membangun, mengamankan, dan memecahkan masalah Authentik. Tiba waktunya skenario paling nyata di dunia kerja: migrasi. Banyak organisasi berpindah ke Authentik dari Keycloak, Authelia, Dex, atau penyedia komersial seperti Auth0 dan Okta — entah karena lisensi, biaya, kompleksitas, atau kemudahan konfigurasi berbasis UI.

Migrasi identity provider itu seperti pindah rumah: kalian tidak memindahkan seluruh isi rumah dalam sekali angkut saat hujan deras. Kalian pindahkan barang per kamar, pastikan setiap ruangan berfungsi, dan menyimpan kotak-kotak penting di tempat yang mudah dijangkau jika harus kembali. Episode ini akan menyusun strategi pindah rumah itu — dari perencanaan hingga pembersihan rumah lama.

#Strategi: Pindah Bertahap, Bukan Big Bang

Kesalahan terbesar migrasi IdP adalah melakukannya sekaligus: matikan Keycloak, nyalakan Authentik, harap semua aplikasi berfungsi. Satu redirect URI yang salah bisa mematikan login seluruh organisasi tanpa jalan mundur. Sebaliknya, pilih cutover per aplikasi: kedua IdP hidup berdampingan, satu per satu aplikasi dialihkan, dan setiap pengalihan divalidasi sebelum lanjut.

Tiga pilar strategi ini:

1. Parallel running — Authentik dan IdP lama berjalan bersamaan selama periode transisi.
2. App-by-app swap — alihkan aplikasi paling kecil dan paling tidak kritis terlebih dahulu untuk membangun kepercayaan.
3. Rollback plan per aplikasi — setiap aplikasi tahu persis cara dikembalikan ke IdP lama dalam hitungan menit.

#Ekspor User dan Grup

Identitas adalah aset utama yang dipindahkan. Cara ekspor bergantung pada sumbernya:

• Keycloak — ekspor realm lewat Admin REST API atau file realm JSON yang memuat user dan grup.
• Authelia — user terdefinisi dalam file YAML konfigurasi; grup ikut di dalamnya.
• Dex — identity umumnya berasal dari upstream (LDAP, OAuth), sehingga seringkali tidak perlu ekspor sama sekali.

Import ke Authentik bisa dilakukan lewat perintah ak import_users di dalam worker dengan file CSV yang berisi kolom seperti username, email, dan name:

docker compose exec worker ak import_users --filename /tmp/users.csv

Sebelum menjalankan, periksa dulu opsi dan format kolom yang didukung dengan docker compose exec worker ak import_users --help — setiap versi bisa memiliki perilaku sedikit berbeda, dan format yang salah membuat seluruh import ditolak.

Ada satu hal penting yang harus kalian pahami sejak awal: password hampir tidak pernah bisa dipindahkan antar IdP. Hash password dibuat dengan algoritma dan salt yang berbeda antar sistem — file user Authelia tidak bisa langsung menjadi password Authentik. Opsi yang realistis: lakukan migrasi dengan password kosong lalu wajibkan pengguna melakukan recovery/reset saat login pertama, atau alihkan autentikasi ke sumber eksternal seperti LDAP (di bawah) agar tidak perlu memindahkan hash sama sekali.

Grup dan keanggotaannya juga perlu dibangun ulang. Mapping peran dari IdP lama (misalnya role Keycloak menjadi grup Authentik) harus dilakukan dengan sadar, karena nantinya nama grup inilah yang dirujuk oleh policy dan property mapping.

#Sinkronisasi LDAP/AD: Cara Menghindari Ekspor Sama Sekali

Jika organisasi sudah memiliki Active Directory atau LDAP, kalian punya jalan pintas yang elegan: jangan ekspor user ke Authentik, tapi jadikan AD sebagai source of truth lewat LDAP source (episode 17). Authentik akan menyinkronkan user, grup, dan keanggotaan dari LDAP secara berkala — identitas tetap dikelola di AD, dan Authentik mengonsumsi hasilnya.

Pendekatan ini menghapus masalah password (authentikasi di-delegasikan ke LDAP bind) dan membuat ekspor/import yang berisiko tidak diperlukan. Yang perlu dipersiapkan: sinkronisasi grup yang benar, mapping atribut, dan keputusan apakah user dari LDAP boleh masuk ke flow Authentik tanpa autentikasi LDAP setiap kali.

#Membangun Ulang Provider lewat Blueprint

Provider — OAuth2, SAML, proxy, LDAP — adalah objek yang memakan waktu jika dibuat manual satu per satu. Gunakan blueprint (episode 21) untuk mendefinisikannya sebagai kode yang bisa di-review dan diuji di staging dulu:

version: 1
entries:
  - model: authentik_providers_oauth2.oauth2provider
    id: provider-grafana
    attrs:
      name: Grafana
      client_type: confidential
      authorization_flow: !Find [authentik_flows.flow, [slug, default-provider-authorization-flow]]
      redirect_uris:
        - https://grafana.example.com/login/generic_oauth

Buat blueprint untuk IdP lama dan IdP baru dengan konfigurasi yang setara, lalu validasi di environment staging sebelum menyentuh produksi. Ini juga memberi kalian dokumentasi migrasi yang bisa diulang.

#Validasi di Staging: Keringat di Latihan, Bukan di Pertandingan

Environment staging adalah tempat semua risiko dibayar murah: buat instance Authentik terpisah, terapkan blueprint yang sama, dan jalankan seluruh skenario login yang dipakai produksi — login internal, login via LDAP, forward auth, dan provider OIDC/SAML utama. Salah satu verifikasi yang sangat disarankan adalah memastikan endpoint discovery provider baru menjawab dengan benar, karena aplikasi akan mengandalkannya saat cutover:

curl -fsS https://auth.example.com/application/o/grafana/.well-known/openid-configuration

Di staging juga kalian menguji hal yang tidak nyaman: rollback. Matikan staging Authentik, kembalikan konfigurasi aplikasi ke IdP lama, dan buktikan aplikasi kembali login tanpa cacat. Rollback yang pernah diuji adalah jaring pengaman yang membuat cutover di produksi terasa biasa saja.

#Swap Provider Aplikasi per Aplikasi

Saat satu aplikasi siap dialihkan, prosedurnya berulang dan bisa diprediksi:

1. Buat provider yang setara di Authentik dan bind ke application.
2. Konfigurasi aplikasi untuk memakai discovery endpoint Authentik baru — ganti authorization/token endpoint dan client ID/secret.
3. Uji login dari browser incognito dan pastikan claims/atribut yang dibutuhkan aplikasi tersedia.
4. Amati log event selama beberapa hari sebelum mengalihkan aplikasi berikutnya.

Di mana memungkinkan, jaga redirect URI tetap identik antara IdP lama dan baru. URI yang sama berarti perubahan yang harus dilakukan aplikasi semakin kecil, dan rollback semakin sederhana.

#Cutover dan Rollback

Cutover resmi bukanlah momen tunggal, melainkan titik terakhir dari deretan pengalihan per aplikasi. Selama periode ini, pantau tiga hal: volume login sukses per aplikasi, jumlah login gagal, dan alerting dari episode 25. Angka login sukses yang turun tajam setelah pengalihan adalah alarm pertama.

Rollback plan minimal: untuk setiap aplikasi, dokumentasikan langkah mengembalikan konfigurasi IdP ke nilai lama. Karena kedua IdP masih hidup selama masa transisi, rollback cukup dengan mengubah konfigurasi aplikasi kembali — tanpa menghidupkan ulang sesuatu yang sudah dimatikan. Baru setelah beberapa siklus pengamatan (misalnya 2-4 minggu) dengan metrik bersih, IdP lama bisa dimatikan.

#Jebakan yang Harus Dihindari

Beberapa kegagalan yang paling sering ditemui saat migrasi:

1. Redirect URI tidak cocok — URI baru tidak terdaftar persis; aplikasi menolak di tahap akhir.
2. Sesi lama tidak berpindah — user yang sudah login di IdP lama tetap terautentikasi di sana; logout massal dari aplikasi bisa diperlukan agar mereka tidak "terjebak" pada sesi lama.
3. Signing key dan metadata berubah — SAML service provider yang memegang metadata lama akan menolak assertion baru; impor ulang metadata Authentik.
4. Matching user berdasarkan email yang tidak unik — jika ekspor dan sumber lain menghasilkan email duplikat, penggabungan akun menjadi kacau.
5. Perangkat MFA tidak ikut pindah — authenticator TOTP/WebAuthn terikat pada akun IdP lama; siapkan proses re-enrollment.
6. SLO/logout berbeda — single logout di IdP baru bisa memiliki cakupan berbeda; komunikasikan ke pengguna.

#Penutup

Pada episode 29 ini kalian telah belajar bahwa migrasi IdP adalah proyek bertahap, bukan peristiwa sekali jalan: memilih strategi parallel running dan app-by-app swap, mengekspor user dan grup dari Keycloak, Authelia, atau Dex dengan memahami batasannya (termasuk password yang tidak bisa dipindahkan), memanfaatkan sinkronisasi LDAP/AD agar ekspor tak diperlukan, membangun ulang provider lewat blueprint, melakukan pengalihan per aplikasi dengan validasi, merancang cutover dan rollback, serta menghindari jebakan seperti redirect URI, sesi lama, dan perangkat MFA.

Inti yang harus kalian bawa:

• Migrasi bertahap dengan rollback plan lebih aman daripada big bang.
• Password antar IdP tidak bisa dipindahkan; gunakan reset atau federasi LDAP.
• Blueprint mengubah konfigurasi menjadi kode yang bisa diuji.
• Redirect URI yang identik mempermudah swap dan rollback.
• Pantau login sukses/gagal setelah setiap pengalihan.

Perjalanan panjang 29 episode bermuara pada satu pertanyaan terakhir: apakah sistem kalian siap produksi? Di episode 30 — episode final series ini — kita akan menutup dengan Production Checklist & Best Practices: checklist lengkap sebelum produksi, praktik operasional terbaik, jebakan umum, rekap seluruh perjalanan dari episode 0, masa depan Authentik, dan penutup untuk seluruh 31 episode. Sampai jumpa di episode 30!