Belajar Authentik - Property Mappings & Claims

#Pendahuluan

Di episode 8, kalian berhasil menerbitkan token lewat OAuth2 provider. Tapi token itu seperti koper yang masih kosong: semua identitas user sudah tersedia di Authentik, namun belum ada yang memutuskan apa yang masuk ke dalamnya.

Keputusan itu ada di tangan property mappings. Analoginya begini: token adalah koper, property mapping adalah kurir yang memilih barang yang boleh dibawa keluar. Aplikasi hanya bisa membaca data yang dikirim — jadi memahami mapping adalah cara kalian mengendalikan apa yang dilihat setiap aplikasi, dan apa yang bocor keluar.

#Apa Itu Property Mapping

Property mapping adalah ekspresi Python yang mengembalikan sebuah nilai untuk dikirim ke aplikasi. Jenis mapping bergantung pada provider:

• Scope mapping: untuk provider OAuth2/OIDC. Nilai yang dikembalikan ditambahkan sebagai claim kustom ke ID token dan access token.
• SAML property mapping: mengisi attribute statements pada assertion SAML.
• LDAP property mapping: memetakan atribut user ke format yang diharapkan klien LDAP.

Ada satu aturan penting: mengembalikan None berarti mapping dilewati — nilainya tidak muncul sama sekali. Konteks yang tersedia dalam ekspresi umumnya meliputi user, request, dan provider (untuk scope mapping), plus helper yang sama seperti di episode 6: regex_match, regex_replace, dan ak_is_group_member.

#Mapping Bawaan yang Sudah Ada

Authentik menyertakan beberapa scope mapping standar yang langsung bisa dipakai:

• OpenID Profile: username, nama, dan informasi dasar profil.
• OpenID Email: alamat email beserta status verifikasi.
• OpenID Groups: daftar grup yang dimiliki user.

Scope profile di provider OAuth2 menunjuk ke mapping profile, scope email menunjuk ke mapping email, dan seterusnya. Jadi ketika sebuah aplikasi meminta scope, inilah isi yang otomatis ikut.

#Bentuk Umum Ekspresi Mapping

Scope mapping biasanya mengembalikan dictionary. Setiap pasangan kunci-nilai menjadi claim dalam token. Contoh paling sederhana: mapping kustom yang mengirim daftar grup user.

Scope mapping kustom: daftar grup user

return {
    "groups": [group.name for group in request.user.ak_groups.all()],
}

Relasi ak_groups.all() mengambil semua grup tempat user terdaftar, lalu list comprehension mengumpulkan nama-namanya. Hasilnya, token berisi claim groups berisi daftar seperti ["dev", "ops"] yang bisa dipakai aplikasi untuk menetapkan peran.

#Membuat Scope Mapping Kustom

Untuk membuat mapping sendiri: masuk ke Customization > Property Mappings, klik Create, lalu pilih tipe Scope Mapping. Ada tiga field penting: nama, scope yang akan diisi, dan ekspresi.

Contoh klasik yang sering dibutuhkan: memperbaiki claim email agar email_verified mengikuti status yang kalian simpan sebagai atribut user.

Scope mapping: email dengan status verifikasi

return {
    "email": request.user.email,
    "email_verified": request.user.attributes.get("email_verified", False),
}

Atau mengambil atribut kustom yang disetel di episode 5:

Scope mapping: atribut kustom user

return {
    "department": request.user.attributes.get("department", "unknown"),
}

#Scope vs Claim: Perbedaan yang Sering Terbalik

Scope dan claim adalah dua hal berbeda yang saling terkait:

• Scope adalah paket izin yang diminta klien: openid, profile, email, atau scope kustom buatan kalian.
• Claim adalah isi yang benar-benar dikembalikan dalam token, ditentukan oleh property mapping.

Aplikasi yang meminta scope profile menerima claim dari mapping yang terikat ke scope itu. Jika kalian membuat scope kustom bernama roles dengan mapping yang mengembalikan daftar peran, aplikasi harus meminta scope roles agar claim-nya muncul. Request scope yang tidak terkonfigurasi akan ditolak — dan ini salah satu sumber error integrasi yang akan kalian temui di episode 10.

Perlu diingat juga: jika klien tidak meminta scope apa pun, Authentik memperlakukan semua scope default sebagai diminta (pelajaran dari episode 8). Scope kustom tidak termasuk dalam perilaku itu.

#Menggunakan Mapping di Token OIDC

Setelah mapping dibuat, tambahkan ke provider OAuth2 pada bagian scope mappings. Alur lengkapnya:

1. Buat scope mapping kustom, misalnya dengan scope roles.
2. Tambahkan ke daftar scope mappings provider.
3. Pastikan aplikasi meminta scope roles saat inisialisasi klien OIDC-nya.
4. Verifikasi token: claim dari mapping harus muncul di ID token dan access token.

Untuk keputusan otorisasi berbasis scope yang lebih ketat, episode 6 juga memberi alat: expression policy bisa memeriksa scope yang diminta lewat konteks khusus, misalnya menolak scope admin kecuali user anggota grup tertentu.

#Debugging Mapping

Mapping adalah kode — jadi ia bisa error, dan debugging-nya butuh alat yang tepat:

• Property mapping tester: jalankan ekspresi terhadap user contoh langsung dari antarmuka, tanpa perlu alur login. Ini alat pertama yang harus dipakai.
• Execution logging: aktifkan logging eksekusi pada mapping untuk melihat konteks dan hasil di log.
• Token preview dan jwt.io: setelah token terbit, decode dan periksa claim yang muncul — perbandingkan dengan yang kalian harapkan.
• Event logs: error Python saat eksekusi mapping tercatat di sini lengkap dengan traceback.

#Penutup

Poin kunci episode ini:

• Property mapping adalah ekspresi Python yang menentukan isi claim untuk scope mapping OIDC, SAML, dan LDAP.
• Mapping bawaan mencakup profile, email, dan groups; email_verified defaultnya False.
• Scope mapping kustom mengembalikan dictionary yang menjadi claim, misalnya daftar grup atau atribut user.
• Scope adalah izin yang diminta, claim adalah isi yang dikembalikan; aplikasi harus meminta scope agar claim-nya muncul.
• Gunakan property mapping tester dan token preview untuk debugging sebelum integrasi.

Sekarang koper token sudah diisi sesuai keinginan. Tinggal mempraktikkannya ke aplikasi sungguhan. Di episode 10, kalian akan mengintegrasikan Grafana, Nextcloud, Portainer, dan Gitea dengan OIDC Authentik — lengkap dengan walkthrough alur login dan troubleshooting error yang paling sering membuat admin garuk kepala.