Belajar Authentik - API & Automation

#Pendahuluan

Sejauh ini semua dikerjakan lewat UI — Authentik memang UI-first. Namun saat jumlah pengguna bertambah atau kalian butuh reproduktibilitas, klik satu per satu di UI tidak akan berhasil. Episode 21 membuka pintu otomatisasi penuh: REST API, API token, blueprint, Python client, dan Terraform provider.

Analoginya seperti beda antara merakit server dengan tangan satu kali versus menulis playbook yang bisa dipakai ulang seratus kali. Yang terakhir itulah yang membuat lingkungan staging dan produksi identik.

#REST API Authentik

Authentik menyediakan REST API lengkap yang juga dipakai oleh UI-nya sendiri. Kuncinya:

• Base path https://auth.example.com/api/v3/.
• Sumber daya utama: core/users, core/groups, core/applications, core/providers, flows/instances, policies, dan banyak lagi.
• Dokumentasi OpenAPI interaktif tersedia di Swagger UI sehingga kalian bisa mengeksplorasi setiap endpoint dan skema, misalnya di /api/v3/schema/swagger-ui/.

API-nya besar; pada praktiknya kalian hanya menyentuh sebagian kecil. Mulai dari yang sering dipakai: user, grup, dan property mapping.

#API Token

Autentikasi API memakai token:

• Buat dari Admin Interface → API Tokens, atau dari halaman pengaturan setiap pengguna.
• Kirim token pada header Authorization sebagai Bearer.
• Setiap token melekat pada pengguna, sehingga izinnya mengikuti role pengguna tersebut — prinsip least privilege juga berlaku untuk otomatisasi.

Simpan token seperti password: di secret manager (misalnya OpenBao atau Vault yang pernah kalian pelajari di series lain), bukan di kode atau repository.

#Contoh Panggilan API

Melihat daftar user:

curl -s https://auth.example.com/api/v3/core/users/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" | jq .results

Membuat user baru:

curl -s -X POST https://auth.example.com/api/v3/core/users/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "arman", "name": "Arman Dwi Pangestu", "email": "arman@example.com", "is_active": true}'

Perhatikan bagaimana request POST membawa Content-Type: application/json dan body JSON — pola ini sama untuk semua pembuatan objek di Authentik.

#Blueprint: Konfigurasi Deklaratif

Blueprint adalah file YAML yang mendeskripsikan objek Authentik — user, grup, flow, provider, property mapping, bahkan brand — dalam satu dokumen. Ini jembatan antara "klik di UI" dan "kode".

Dua status penting sebuah blueprint instance:

• Managed — blueprint dijaga oleh file-nya; perubahan langsung di UI bisa ditimpa saat blueprint di-apply ulang.
• Unlocked — setelah diimpor, objeknya boleh diubah manual lewat UI dan tidak di-enforce oleh file.

Aturan praktis: gunakan managed untuk hal yang harus seragam di semua lingkungan (misalnya provider standar), dan unlocked untuk objek yang memang perlu diedit manual.

#Contoh Blueprint

version: 1
entries:
  - model: authentik_core.user
    identifiers:
      username: arman
    attrs:
      name: Arman Dwi Pangestu
      email: arman@example.com
      is_active: true
  - model: authentik_core.group
    identifiers:
      name: admins
    attrs:
      users:
        - !find authentik_core.user
          where:
            - username: arman
  - model: authentik_core.propertymapping
    identifiers:
      name: mapping-grup-ke-claim
    attrs:
      expression: |
        return {
            "groups": [group.name for group in user.ak_groups.all()],
        }

Perhatikan ekspresi !find: blueprint mencari objek yang sudah ada dan mereferensikannya, sehingga grup admins merujuk ke user arman tanpa perlu menebak UUID. Ini yang membuat blueprint idempoten — aman di-apply berulang.

#Mengotomatisasi User, Flow, dan Properti

Kombinasi API dan blueprint membuka pola otomasi yang umum:

• Provisioning — script yang membuat atau menonaktifkan user saat karyawan masuk atau keluar, dipicu dari sistem HR.
• Config as code — blueprint di-commit ke git dan di-apply oleh pipeline CI/CD (alur yang kalian kenal dari series semantic-release dan gitops).
• Templating flow — definisikan flow dan stage sekali lewat blueprint, lalu pakai ulang di lingkungan lain tanpa klik manual.

#Python Client

Untuk logika yang lebih kompleks daripada curl, ada client Python yang dibuat dari spesifikasi OpenAPI (tersedia sebagai authentik-client). Pola penggunaannya konsisten: buat client, lalu panggil fungsi endpoint:

Python client — list user

from authentik_client.client import AuthentikClient
from authentik_client.api.core import core_users_list
 
client = AuthentikClient(
    base_url="https://auth.example.com",
    token="token-api-kalian",
)
users = core_users_list.sync(client=client)
for user in users.results or []:
    print(user.username)

Struktur import mengikuti generator OpenAPI dan bisa berbeda antar versi SDK; selalu cek dokumentasi versi yang kalian pakai.

#Terraform Provider

Untuk deployment yang sudah berbasis Terraform (atau OpenTofu), ada provider goauthentik/authentik:

terraform {
  required_providers {
    authentik = {
      source  = "goauthentik/authentik"
      version = "~> 2025.1"
    }
  }
}
 
provider "authentik" {
  url   = "https://auth.example.com"
  token = var.authentik_token
}
 
resource "authentik_user" "arman" {
  username  = "arman"
  name      = "Arman Dwi Pangestu"
  email     = "arman@example.com"
  is_active = true
}

Dengan provider ini, objek identitas menjadi bagian dari state infrastruktur kalian: ter-versioning, ter-review lewat pull request, dan bisa di-revert.

#Penutup

Ringkasan episode 21:

• REST API /api/v3 mengekspos seluruh konfigurasi; autentikasi memakai API token sebagai Bearer.
• Blueprint membuat konfigurasi deklaratif dan idempoten, dengan status managed dan unlocked.
• Python client dan Terraform provider membawa otomatisasi ke tingkat kode.

Di episode 22, kita memakai semua aktivitas itu untuk kepentingan lain: events dan auditing untuk memeriksa, mengekspor, dan mengintegrasikan jejak autentikasi. Sampai jumpa!