Belajar Authentik - OAuth2/OIDC Provider Setup

#Pendahuluan

Di episode 7, alur autentikasi internal Authentik sudah lengkap dengan MFA. Tapi semua itu masih berdiri sendiri — belum bisa dipakai aplikasi lain. Saatnya membangun jembatan standar industri: OAuth2 dan OpenID Connect (OIDC).

Ada satu perbedaan yang harus jelas sejak awal. OAuth2 adalah protokol otorisasi: ia memberi aplikasi izin untuk mengakses sumber daya atas nama user. OIDC dibangun di atas OAuth2 dan menambahkan lapisan autentikasi: ia membuktikan siapa user itu lewat token berisi identitas. Analoginya, OAuth2 seperti pas masuk area gedung, sedangkan OIDC seperti kartu identitas yang dibawa di dalamnya. Authentik berperan sebagai identity provider yang menerbitkan kedua hal itu.

#Membuat Provider OAuth2

Langkah pertama: buka Admin interface, masuk ke Applications > Providers, lalu buat provider baru bertipe OAuth2/OIDC. Beberapa keputusan penting ada di formulir ini.

#Client Type: Confidential vs Public

Client type menentukan seberapa besar kepercayaan yang bisa diberikan kepada aplikasi peminta:

Confidential: untuk aplikasi dengan backend server, seperti Grafana atau Nextcloud. Aplikasi bisa menyimpan rahasia dengan aman, jadi selain client_id juga diberi client_secret. Analoginya pegawai tetap yang punya kunci ruangan server.
Public: untuk single-page application atau aplikasi mobile yang semua logikanya berjalan di sisi klien. Tidak ada secret yang aman disimpan, sehingga harus mengandalkan PKCE. Analoginya kartu akses tamu yang tidak boleh membawa rahasia.

#Redirect URI

Ini field paling sering menjadi sumber masalah. Redirect URI adalah daftar alamat tujuan setelah login selesai — Authentik hanya akan mengirimkan authorization code ke URI yang terdaftar. Cocokkan dengan persis: skema, host, path, bahkan trailing slash. Jika dikosongkan, Authentik memakai URI pertama yang diminta aplikasi sebagai nilai tersimpan.

#Signing Key

Keputusan kedua yang penting:

Pilih sertifikat RSA: token ditandatangani secara asimetris. Aplikasi memverifikasi tanda tangan lewat kunci publik yang disediakan endpoint JWKS. Ini mode yang disarankan.
Biarkan kosong: Authentik menandatangani token secara simetris memakai client secret sebagai kunci HMAC. Sederhana, tapi pembagian rahasia ke aplikasi menjadi satu-satunya jaminan.

#Scopes dan Sub-Mode

Scopes: pilih scope yang boleh diminta aplikasi. openid wajib untuk OIDC; profile memberi data dasar, email memberi alamat email, dan offline_access memungkinkan penerbitan refresh token. Jika klien tidak meminta scope apa pun, Authentik memperlakukan semua scope default sebagai diminta.
Sub-mode: di bagian advanced protocol settings, kalian bisa mengatur bagaimana nilai sub (subject) dibentuk — misalnya berbasis UUID user atau username — serta issuer mode yang mengontrol nilai iss di token: unik per aplikasi berdasarkan slug, atau seragam untuk semua provider.

Tip

Mulai dengan issuer mode per provider (default) karena sesuai struktur discovery dan JWKS yang berbasis slug aplikasi. Mode global hanya perlu dipertimbangkan jika aplikasi memaksa satu issuer untuk semua klien.

#Endpoint OAuth2 yang Harus Diketahui

Semua endpoint hidup di bawah prefix /application/o/. Tabel ini akan kalian pakai terus saat mengonfigurasi aplikasi:

Fungsi	Endpoint
Authorization	`/application/o/authorize/`
Token	`/application/o/token/`
User Info	`/application/o/userinfo/`
JWKS	`/application/o/<slug>/jwks/`
OpenID Configuration	`/application/o/<slug>/.well-known/openid-configuration`
End Session	`/application/o/<slug>/end-session/`

Important

Karena endpoint di atas bersifat global, kalian tidak boleh membuat aplikasi dengan slug authorize, token, userinfo, introspect, atau revoke — namanya akan bertabrakan dengan endpoint OAuth2 dan merusak routing.

#Authorization Code Flow, Langkah demi Langkah

Ini alur yang paling umum untuk aplikasi web dengan backend. Berjalan seperti antrean check-in di bandara — tiap langkah menyerahkan bukti ke langkah berikutnya:

User menekan tombol login di aplikasi.
Aplikasi mengarahkan browser user ke endpoint authorize dengan client_id, redirect_uri, scope, dan state.
Authentik menjalankan authentication flow — identification, password, lalu MFA dari episode 7.
User menyetujui (consent) scope yang diminta aplikasi.
Authentik mengalihkan browser kembali ke redirect_uri dengan membawa code.
Aplikasi menukar code di endpoint token menggunakan client_id dan client_secret.
Authentik membalas dengan access_token dan id_token (dan refresh_token jika scope offline_access diminta).
Aplikasi memverifikasi token lewat JWKS, lalu mengambil profil dari endpoint userinfo.

Warning

Authorization code hanya bisa dipakai sekali dan kedaluwarsa cepat. Jika aplikasi menerima kode dua kali atau kode sudah lama, proses penukaran akan gagal — ini bukan bug Authentik, melainkan perlindungan terhadap pencurian kode.

#Membuat Application dan Mengikat Provider

Provider belum terlihat oleh user sampai diikat ke sebuah application. Application adalah objek yang mewakili aplikasi sungguhan di depan user: nama, slug, ikon, dan launch URL. Di sinilah provider dihubungkan, dan di sinilah policy dari episode 6 di-bind untuk membatasi siapa yang boleh membuka aplikasi tersebut.

Urutan yang disarankan: buat provider OAuth2 dulu, lalu buat application dan pilih provider tersebut sebagai backend-nya. Slug application ikut menentukan URL discovery dan issuer.

#Menguji dengan OAuth2 Debugger

Sebelum menyambungkan aplikasi sungguhan, uji dulu. Cara tercepat adalah melihat dokumen discovery yang dihasilkan Authentik — file .well-known/openid-configuration yang otomatis memuat semua endpoint.

Ambil konfigurasi OpenID Connect

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

Responsnya berisi semua endpoint, issuer, dan jenis tanda tangan yang didukung. Dari sini, uji pertukaran token memakai grant client_credentials untuk memastikan kredensial klien benar.

Tukar client credentials menjadi token

curl -s https://auth.example.com/application/o/token/ \
  -u "<client-id>:<client-secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=openid profile email"

Lalu ambil profil lewat endpoint userinfo memakai token yang baru didapat.

Ambil profil lewat UserInfo endpoint

curl -s https://auth.example.com/application/o/userinfo/ \
  -H "Authorization: Bearer <access-token>"

Untuk menguji alur penuh dengan browser, pakai OAuth2 debugger — banyak tersedia gratis di web. Isi client_id, redirect_uri, dan scope yang sudah didaftarkan, lalu ikuti alurnya sampai browser kembali membawa code. Ini simulasi paling dekat dengan pengalaman aplikasi sungguhan.

#Standard Claims

Setelah berhasil, perhatikan claim standar yang ada di ID token:

iss: issuer — asal token diterbitkan.
aud: audience — aplikasi yang menjadi tujuan token.
sub: subject — identitas user (bentuknya bergantung sub-mode tadi).
exp dan iat: waktu kedaluwarsa dan waktu diterbitkan.
nonce: nilai acak dari permintaan untuk mencegah replay.

Claim lain seperti email, name, dan groups baru muncul jika scope terkait diminta dan property mapping menyediakannya. Bagaimana isi token dibentuk itulah topik episode berikutnya.

#Penutup

Poin kunci episode ini:

OAuth2 untuk otorisasi, OIDC untuk autentikasi; Authentik menyediakan keduanya dalam satu provider.
Confidential client untuk aplikasi ber-backend, public client dengan PKCE untuk SPA dan mobile.
Redirect URI harus cocok persis; signing key menentukan cara token diverifikasi.
Authorization code flow: authorize, consent, code, token, userinfo.
Uji dengan discovery endpoint dan OAuth2 debugger sebelum integrasi sungguhan.

Token sudah keluar, tapi isinya masih polos. Di episode 9, kalian akan memegang kendali penuh atas isi token lewat property mappings dan claims — menentukan claim mana yang boleh dibawa aplikasi, termasuk mapping grup kustom buatan sendiri.