Belajar Authentik - Integrating Applications dengan OIDC

#Pendahuluan

Di episode 9, isi token sudah sepenuhnya di tangan kalian lewat property mappings. Sekarang saatnya ujian sesungguhnya: menyambungkan aplikasi sungguhan. Grafana, Nextcloud, Portainer, Gitea — semua mendukung OIDC, dan semuanya bisa memakai Authentik sebagai satu gerbang login.

Triknya adalah mengenali polanya. Setiap aplikasi memiliki titik konfigurasi yang berbeda, tapi parameter yang diminta selalu sama: discovery URL atau endpoint, client ID, client secret, redirect URI, dan scope. Kalian sudah punya semua bahan itu dari episode 8 dan 9. Yang tersisa hanyalah menerjemahkannya ke bahasa konfigurasi masing-masing aplikasi.

#Pola Umum Integrasi OIDC

Sebelum menyentuh aplikasi, pastikan empat hal ini siap:

Provider OAuth2 di Authentik untuk aplikasi tersebut, lengkap dengan redirect URI yang didaftarkan.
Application di Authentik yang mengikat provider, plus policy akses dari episode 6.
Client ID dan secret yang dihasilkan provider (untuk client confidential).
Scopes: minimal openid profile email, tambahkan offline_access jika aplikasi butuh refresh token.

Redirect URI adalah kontrak antara aplikasi dan Authentik: kedua sisi harus menulis nilai yang sama persis.

#Grafana

Grafana mendukung OIDC lewat modul generic OAuth. Pertama, buat provider OAuth2 di Authentik dengan redirect URI https://grafana.example.com/login/generic_oauth. Lalu tambahkan konfigurasi di file grafana.ini.

grafana.ini

[auth.generic_oauth]
enabled = true
name = Authentik
allow_sign_up = true
client_id = <client-id>
client_secret = <client-secret>
scopes = openid profile email
auth_url = https://auth.example.com/application/o/authorize/
token_url = https://auth.example.com/application/o/token/
api_url = https://auth.example.com/application/o/userinfo/

allow_sign_up membuat user baru otomatis dibuat saat login pertama — nyaman untuk homelab. Untuk kontrol peran, kalian bisa memetakan grup dari claim groups (yang dibentuk di episode 9) ke peran Grafana, misalnya Viewer dan Admin.

#Nextcloud

Nextcloud memakai aplikasi user_oidc resmi. Setelah menginstalnya, masuk ke Settings > OpenID Connect clients dan daftarkan Authentik dengan:

Discovery URL: https://auth.example.com/application/o/nextcloud/.well-known/openid-configuration
Client ID dan secret: dari provider OAuth2.
Redirect URI: https://nextcloud.example.com/apps/user_oidc/code

Autodiscovery membuat Nextcloud membaca semua endpoint dan kunci JWKS langsung dari Authentik — keunggulan besar dibanding konfigurasi manual, karena perubahan signing key di provider tidak perlu diterjemahkan ulang.

#Portainer

Portainer dikonfigurasi lewat UI-nya: Settings > Authentication, lalu aktifkan OAuth. Yang diminta hanyalah URL endpoint dan kredensial klien — tidak ada file konfigurasi untuk diedit:

Authorization endpoint: https://auth.example.com/application/o/authorize/
Token endpoint: https://auth.example.com/application/o/token/
Userinfo endpoint: https://auth.example.com/application/o/userinfo/
Client ID dan secret: dari provider.
Redirect URI: https://portainer.example.com (ditampilkan oleh Portainer saat konfigurasi).

Aktifkan Autoprovisioning agar user yang login lewat Authentik otomatis dibuat akunnya. Tanpa ini, user harus dibuat manual terlebih dahulu.

#Gitea

Gitea menyediakan OAuth2 sources lewat Site Administration > Authentication Sources. Pilih provider OpenID Connect, lalu isi:

OpenID Connect Auto Discovery URL: https://auth.example.com/application/o/gitea/.well-known/openid-configuration
Client ID dan secret: dari provider Authentik.
Redirect URI: https://gitea.example.com/user/oauth2/<nama-source>/callback

Untuk referensi, konfigurasi yang sama bisa direpresentasikan di app.ini:

app.ini (contoh)

[oauth2_client.1]
NAME = Authentik
PROVIDER = openidConnect
CLIENT_ID = <client-id>
CLIENT_SECRET = <client-secret>
AUTO_DISCOVERY_URL = https://auth.example.com/application/o/gitea/.well-known/openid-configuration

Tip

Selalu mulai dengan discovery URL daripada menyalin endpoint manual. Ia otomatis memuat endpoint authorize, token, userinfo, dan JWKS. Jika Authentik berubah atau issuer mode disetel ulang, aplikasi dengan autodiscovery akan tetap sinkron.

Saat semua aplikasi terkonfigurasi, alur SSO yang kalian lihat akan persis seperti ini:

User membuka aplikasi dan menekan tombol sign in.
Browser diarahkan ke endpoint authorize Authentik.
Authentik menjalankan alur login: identification, password, lalu MFA jika policy mewajibkan.
User menyetujui consent untuk scope yang diminta aplikasi.
Browser kembali ke redirect URI aplikasi dengan membawa code.
Aplikasi menukar code di endpoint token memakai client credentials.
Aplikasi memverifikasi ID token dan memanggil userinfo untuk membangun sesi lokalnya.

Dari sudut pandang user, login adalah satu pintu yang sama untuk semua aplikasi. Dari sudut pandang admin, satu akun dan satu set policy mengontrol semuanya.

#Verifikasi Token dengan jwt.io

Sesudah login pertama berhasil, verifikasi apa yang sebenarnya dikirim aplikasi. Tempel ID token ke jwt.io — alat ini mendecode header, payload, dan tanda tangan. Yang perlu diperiksa:

iss: issuer sesuai aplikasi.
aud: berisi client id aplikasi.
exp: masa berlaku masuk akal.
Claim dari mapping episode 9: email, groups, atau claim kustom yang kalian buat.

Tanpa membuka browser, kalian bisa mendecode token lewat baris perintah:

Decode ID token tanpa library

echo "<id-token>" | cut -d. -f2 | tr '_-' '/+' | base64 -d 2>/dev/null | jq .

Important

jq dan base64 di sini hanya untuk mengintip isi token — bukan verifikasi keaslian. Untuk memverifikasi tanda tangan, gunakan kunci publik dari JWKS endpoint. Menerima token hanya karena payloadnya terbaca adalah kebiasaan yang berbahaya.

#Troubleshooting Error Umum

Bahkan dengan konfigurasi benar, ada beberapa error yang selalu muncul berulang. Kenali polanya:

Redirect URI mismatch: aplikasi mengirim redirect URI yang tidak terdaftar di provider. Periksa trailing slash, skema http vs https, dan hostname — semuanya harus identik.
Scope tidak valid: aplikasi meminta scope yang tidak dikonfigurasi di provider. Pastikan scope mapping dari episode 9 ditambahkan, dan scope tersebut benar-benar diminta klien.
Signature verification gagal: aplikasi tidak menemukan kunci atau memakai JWKS salah. Cek discovery URL dan pastikan signing key (bukan HMAC) dipilih di provider.
email_verified false: aplikasi menolak login karena claim verifikasi. Buat mapping kustom email_verified seperti di episode 9, atau verifikasi email user.
Issuer tidak cocok: issuer di token tidak sama dengan yang diharapkan aplikasi. Tinjau issuer mode provider.

Warning

Saat mengecek masalah integrasi, buka log Authentik dan log aplikasi secara berdampingan. Kesalahan biasanya muncul dua kali: sekali dari sisi aplikasi (parameter yang dikirim), sekali dari sisi Authentik (parameter yang ditolak). Mencocokkan keduanya mempercepat diagnosis drastis.

#Penutup

Poin kunci episode ini:

Pola integrasi OIDC selalu sama: discovery URL, client ID, client secret, redirect URI, dan scope.
Grafana lewat grafana.ini, Nextcloud lewat aplikasi user_oidc, Portainer lewat UI, Gitea lewat authentication sources.
Alur login SSO berjalan dari redirect, autentikasi, consent, code, hingga pertukaran token.
jwt.io dan base64/jq untuk mengintip isi token; JWKS untuk memverifikasi tanda tangan.
Error umum: redirect mismatch, scope, signature, dan issuer.

Semua aplikasi modern kini login lewat satu pintu. Tapi bagaimana dengan aplikasi yang tidak mendukung OIDC sama sekali — tools lama yang hanya menerima reverse proxy biasa? Di episode 11, kalian akan mengenal proxy provider dan outpost, senjata Authentik untuk membungkus aplikasi apa pun dengan autentikasi, tanpa mengubah kode satu baris pun.