Belajar Authelia - OIDC Client Integrations

#Pendahuluan

Di episode 18 kalian memahami scope dan claim — bahasa yang dipakai client untuk meminta data identitas. Sekarang saatnya berbicara dengan aplikasi sungguhan. Episode 19 ini memandu integrasi empat client nyata — Grafana, Gitea atau Forgejo, Nextcloud, dan Portainer — dengan Authelia sebagai penyedia identitas.

Alur yang kita pakai selalu sama, terlepas dari aplikasinya: client mengarahkan pengguna ke endpoint authorization Authelia, pengguna login dan menyetujui consent, Authelia mengembalikan kode, client menukarnya dengan token, lalu memakai token itu untuk mengambil identitas pengguna.

#Registrasi Client di Sisi Authelia

Semua integrasi dimulai dari satu tempat: mendaftarkan client di identity_providers.oidc.clients. Empat hal yang paling sering menjadi biang masalah:

• redirect_uris — harus cocok persis dengan yang diminta aplikasi, termasuk skema, host, path, dan trailing slash.
• scopes — scope yang didaftarkan harus mencakup semua yang diminta aplikasi.
• grant_types — untuk aplikasi web interaktif, authorization_code adalah standarnya; tambahkan refresh_token jika aplikasi butuh sesi panjang.
• secret — disarankan memakai hash alih-alih plaintext; prefix $plaintext$ memudahkan pengembangan.

#Grafana

Grafana mendukung OAuth lewat auth.generic_oauth. Daftarkan client di Authelia, lalu set konfigurasi di grafana.ini:

[auth.generic_oauth]
enabled = true
name = Authelia
client_id = grafana
client_secret = rahasia-client
scopes = openid profile email groups
auth_url = https://auth.example.com/api/oidc/authorization
token_url = https://auth.example.com/api/oidc/token
api_url = https://auth.example.com/api/oidc/userinfo
allowed_groups = grafana-admin grafana-editor

allowed_groups mencocokkan claim groups dari token. Dengan ini, hanya pengguna yang masuk grup grafana-admin atau grafana-editor yang boleh login — kontrol akses terpusat di Authelia, bukan tersebar di tiap aplikasi.

#Gitea atau Forgejo

Gitea dan Forgejo memakai pola yang sama: aktifkan dukungan OAuth2, lalu daftarkan Authelia sebagai authentication source melalui admin panel, bukan file konfigurasi.

[oauth2_client]
ENABLE = true

Di admin panel Gitea atau Forgejo, buat Authentication Source baru dengan tipe OAuth2 dan provider OpenID Connect. Isi OpenID Connect Auto Discovery URL dengan https://auth.example.com/.well-known/openid-configuration, lalu masukkan client_id, client_secret, dan scope openid profile email groups. Kedua aplikasi ini memakai discovery untuk menemukan semua endpoint Authelia secara otomatis, jadi tidak perlu mengisi URL authorization dan token secara manual.

#Nextcloud

Nextcloud memakai aplikasi oidc_login. Konfigurasinya diletakkan di config/config.php:

'oidc_login_provider_url' => 'https://auth.example.com/.well-known/openid-configuration',
'oidc_login_client_id' => 'nextcloud',
'oidc_login_client_secret' => 'rahasia-client',
'oidc_login_auto_redirect' => false,
'oidc_login_disable_registration' => true,
'oidc_login_scope' => 'openid profile email',
'oidc_login_default_claim' => 'preferred_username',

oidc_login_default_claim menentukan claim yang dipakai untuk membuat akun lokal. Ingat pelajaran episode 18: preferred_username dan email hanya untuk provisioning akun, sedangkan relasi akun yang stabil tetap mengacu ke sub di sisi Authelia.

#Portainer

Portainer dikonfigurasi lewat menu Settings → Authentication → OAuth. Karena tidak punya discovery otomatis, semua endpoint diisi manual. Client di Authelia:

identity_providers:
  oidc:
    clients:
      - id: portainer
        description: Portainer management
        secret: '$plaintext$rahasia-client'
        redirect_uris:
          - https://portainer.example.com
        scopes:
          - openid
          - profile
          - email
          - groups
        grant_types:
          - authorization_code
        response_types:
          - code

Di sisi Portainer, isi field berikut:

• Provider: Custom.
• Client ID: portainer.
• Authorization URL: https://auth.example.com/api/oidc/authorization.
• Access Token URL: https://auth.example.com/api/oidc/token.
• UserInfo URL: https://auth.example.com/api/oidc/userinfo.
• Redirect URL: https://portainer.example.com — harus sama persis dengan redirect_uris.
• User Identifier: sub.
• Scopes: openid profile email groups.

Perhatikan bahwa redirect URL Portainer hanya berupa host tanpa path. Ketidakcocokan satu karakter saja akan membuat flow gagal di langkah callback.

#Alur Login OIDC yang Terjadi

Ketika semuanya terpasang, alur di belakang layar berjalan seperti ini:

1. Pengguna membuka aplikasi dan memilih tombol login dengan OIDC.
2. Aplikasi mengarahkan pengguna ke https://auth.example.com/api/oidc/authorization beserta client_id, redirect_uri, scope, dan state.
3. Authelia memeriksa session; jika belum login, portal ditampilkan.
4. Setelah login, Authelia menampilkan layar consent lalu mengembalikan kode ke redirect_uri.
5. Aplikasi menukar kode dengan token di https://auth.example.com/api/oidc/token.
6. Aplikasi memanggil UserInfo untuk mengambil identitas dan membuat sesi lokal.

Seluruh langkah ini otomatis — kalian hanya perlu memastikan konfigurasi di kedua sisi cocok.

#Verifikasi Integrasi

Verifikasi dasar yang bisa dilakukan:

curl -s https://auth.example.com/.well-known/openid-configuration | jq .
curl -s https://auth.example.com/jwks.json | jq .keys[0].alg

Endpoint pertama harus mengembalikan metadata OIDC lengkap; endpoint kedua memuat kunci RSA publik untuk memvalidasi tanda tangan token. Setelah login pertama berhasil, dekode token yang dihasilkan — misalnya lewat panel developer browser — dan periksa claim sub, name, serta groups.

#Penutup

Di episode ini kalian mengintegrasikan empat client nyata:

• Grafana memakai auth.generic_oauth dengan endpoint authorization, token, dan userinfo Authelia.
• Gitea atau Forgejo dan Nextcloud menggunakan auto discovery dari .well-known/openid-configuration.
• Portainer diisi manual karena tidak mendukung discovery.
• Redirect URI harus cocok persis, dan claim sub menjadi kunci relasi akun yang stabil.

Satu komponen yang belum kita bahas tuntas adalah layar consent yang muncul saat login. Di episode 20, kita membahas Consent Management — cara mengatur mode consent per client, pre-configured consent, hingga mencabut izin yang sudah diberikan. Sampai jumpa!