Belajar Authelia - OIDC Scopes & Claims

#Pendahuluan

Di episode 17 kalian mendaftarkan client OIDC pertama: ada client_id, client_secret, redirect_uris, dan daftar scopes. Tapi apa sebenarnya yang diminta client ketika ia meminta scope email atau groups? Di episode 18 ini kita membedah scope dan claim — dua konsep yang menentukan data identitas apa saja yang boleh dibaca sebuah aplikasi.

Analoginya seperti memberi izin teman meminjam mobil kalian. Menyetujui "mengambil mobil" dan menyetujui "mengambil mobil sampai habis bensin" adalah dua izin yang sangat berbeda maknanya. Scope adalah daftar izin dalam bahasa OIDC; claim adalah data yang keluar setelah izin itu diberikan.

#Scope dan Claim, Dua Sisi Koin

• Scope adalah permintaan izin yang dikirim client ketika mengarahkan pengguna ke Authelia, biasanya lewat parameter scope pada authorization request.
• Claim adalah pernyataan tentang pengguna yang akhirnya dimuat ke dalam token, seperti name, email, atau groups.

Hubungannya satu arah: scope meminta kelompok data, claim adalah isi dari kelompok data itu. Scope email meminta hak membaca claim email dan email_verified. Memahami pasangan ini penting karena Authelia hanya mengeluarkan claim sesuai scope yang diizinkan untuk client tersebut — prinsip least privilege di level token.

#Scope Standar yang Didukung Authelia

Tidak semua client butuh semua scope. Client semacam dashboard yang hanya menampilkan nama cukup diberi openid dan profile. Memberi scope berlebihan ke semua client sama seperti memberikan semua karyawan kunci ke semua ruangan.

#openid: Scope yang Wajib

Scope openid adalah satu-satunya yang mutlak diperlukan agar sebuah request dianggap sebagai request OpenID Connect; tanpa scope ini, request hanyalah OAuth 2.0 biasa. Scope ini memberikan claim sub, yaitu pengenal unik pengguna dalam bentuk UUID v4.

#Claim dari profile, email, dan groups

Scope-scope tersebut menerjemahkan atribut pengguna di users_database.yml menjadi claim:

• preferred_username — nama pengguna yang dipakai saat login.
• name — nama tampilan; jika atribut display_name kosong, Authelia memakai preferred_username sebagai fallback.
• email dan email_verified — berasal dari atribut email pada akun.
• groups — daftar grup tempat pengguna berada.

Karena ada fallback, integrasi tidak langsung rusak saat data profil belum lengkap. Ini membuat Authelia ramah untuk deployment bertahap.

#Konfigurasi Scopes pada Client

Scope yang boleh diminta diatur per client lewat daftar scopes. Default Authelia adalah openid, groups, profile, dan email. Untuk membatasi sebuah client hanya membaca data minimal:

identity_providers:
  oidc:
    clients:
      - id: client-minimal
        description: Hanya butuh identitas dasar
        secret: '$plaintext$rahasia-client'
        redirect_uris:
          - https://app.example.com/callback
        scopes:
          - openid
          - email
        grant_types:
          - authorization_code
          - refresh_token
        response_types:
          - code

Client di atas tidak bisa meminta groups atau profile, meskipun aplikasinya mencoba. Authelia menolak scope yang tidak terdaftar — pintunya bersifat presisi, bukan kunci master.

#Custom Scopes

Kadang kita ingin sebuah scope yang mengelompokkan beberapa claim sekaligus. Authelia mendukungnya lewat pemetaan nama scope ke daftar claim di level provider:

identity_providers:
  oidc:
    scopes:
      authelia:profil-lengkap:
        - name
        - given_name
        - family_name
        - groups
        - email_verified
    clients:
      - id: client-a
        secret: '$plaintext$rahasia-client'
        scopes:
          - openid
          - authelia:profil-lengkap
        redirect_uris:
          - https://a.example.com/callback

Client lain tetap harus mencantumkan scope tersebut di daftar scopes miliknya. Custom scope tidak otomatis tersedia untuk semua orang.

#Audience: Mengunci Token untuk Penerima Tertentu

Claim aud memberitahu untuk siapa token dibuat. Default-nya adalah client identifier. Jika sebuah access token akan dipakai service lain, misalnya backend API, daftarkan audience lewat daftar audience:

identity_providers:
  oidc:
    clients:
      - id: frontend-a
        secret: '$plaintext$rahasia-client'
        redirect_uris:
          - https://a.example.com/callback
        audience:
          - https://api.example.com
          - https://backoffice.example.com

Perilaku audience diatur lewat requested_audience_mode:

• explicit (default) — audience masuk ke token hanya jika client benar-benar memintanya.
• implicit — jika client berhak atas semua audience dan tidak menyebut audience spesifik, semua audience terdaftar dianggap diminta.

Backend API bisa menolak token yang aud-nya tidak cocok, persis seperti petugas bandara memeriksa tujuan di boarding pass.

#Contoh Isi Token

Setelah flow selesai, ID token berisi claim seperti ini (nilai disederhanakan):

{
  "iss": "https://auth.example.com",
  "sub": "6f3c2d58-4a1e-4b9c-8d7e-1f2a3b4c5d6e",
  "aud": "client-a",
  "exp": 1783245600,
  "iat": 1783242000,
  "auth_time": 1783241900,
  "nonce": "s9kdj2n29fn0a2k3",
  "amr": ["pwd", "totp"],
  "name": "Arman Dwi Pangestu",
  "preferred_username": "arman",
  "email": "arman@example.com",
  "email_verified": true,
  "groups": ["admin", "devops"]
}

Perhatikan amr — berisi metode autentikasi yang dipakai, seperti pwd untuk password dan totp untuk TOTP. Aplikasi bisa memakai nilai ini untuk menolak login yang tidak melewati MFA.

#Verifikasi via Endpoint Discovery

Authelia mengumumkan semua scope yang didukung di endpoint discovery. Cek dengan curl:

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

Lalu saring hasilnya dengan jq .scopes_supported untuk melihat daftar offline_access, openid, profile, email, address, phone, dan groups. Inilah tempat pertama untuk memeriksa ketika client gagal karena scope tidak dikenal.

#Penutup

Di episode ini kalian memahami:

• Scope adalah izin, claim adalah data; scope openid wajib dan memberikan sub.
• profile, email, dan groups memetakan atribut pengguna menjadi claim yang bisa dibaca aplikasi.
• Scope dibatasi per client, dan custom scope memungkinkan pengelompokan claim.
• Audience mengunci token untuk penerima tertentu dengan mode explicit atau implicit.

Dengan bekal ini, kalian siap menghubungkan aplikasi sungguhan. Di episode 19, kita praktik langsung mengintegrasikan client nyata seperti Grafana, Gitea atau Forgejo, Nextcloud, dan Portainer dengan Authelia sebagai penyedia identitas. Sampai jumpa!