Belajar Backstage - Authentication & Identity

#Pendahuluan

Di episode 7, dokumentasi yang kalian bangun dengan TechDocs akhirnya tampil di dalam Backstage — tetapi siapa pun yang membuka portal itu ikut membaca semuanya. Episode 8 menutup celah itu: kita masuk ke Authentication & Identity, lapisan yang menentukan siapa yang masuk ke Backstage dan apa yang mereka pegang. Di sinilah Backstage berubah dari portal terbuka menjadi gerbang yang terhubung ke penyedia identitas organisasi kalian, entah itu GitHub, Google, OIDC, SAML, atau Microsoft Entra ID.

#Authentication vs Identity

Dua konsep ini sering disamakan, padahal keduanya berbeda:

• Authentication — membuktikan bahwa user adalah siapa yang dia klaim. Backstage melakukannya lewat auth provider: GitHub, Google, OIDC, dan sebagainya.
• Identity — menentukan siapa user itu di dalam sistem Backstage setelah terautentikasi, dan kepemilikan apa yang melekat padanya. Inilah yang mengalir ke setiap permintaan backend.

Autentikasi menjawab pertanyaan siapa yang datang, sedangkan identitas menjawab pertanyaan apa yang boleh dia lakukan. Episode 8 membahas keduanya, dimulai dari penyedia autentikasi.

#Auth Providers

#Gambaran Umum

Auth provider adalah modul yang menghubungkan Backstage ke penyedia identitas eksternal. Setiap provider mengimplementasikan alur OAuth atau protokol sejenis, dan hasilnya diseragamkan ke dalam satu format identitas Backstage. Provider diaktifkan lewat konfigurasi auth.providers di app-config.yaml.

#Guest Mode untuk Pengembangan

Provider paling sederhana adalah guest mode: satu klik untuk masuk tanpa username maupun password. Fungsinya semata untuk pengembangan — agar developer tidak perlu membuka OAuth setiap kali menjalankan Backstage di mesin lokal.

auth:
  environment: development
  providers:
    guest: {}

Provider lain (GitHub, Google, dan seterusnya) dikonfigurasi dengan clientId dan clientSecret, umumnya diambil dari environment variable agar tidak tercatat di repository. Nilai rahasia di-substitusi saat config dimuat.

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
    google:
      development:
        clientId: ${AUTH_GOOGLE_CLIENT_ID}
        clientSecret: ${AUTH_GOOGLE_CLIENT_SECRET}

#Custom Auth Provider

Ketika tidak ada provider bawaan yang cocok — misalnya IdP internal dengan protokol khusus — Backstage memungkinkan membangun provider sendiri lewat auth extension point di backend. Provider kustom biasanya membungkus alur OAuth atau protokol lain dan menghasilkan identitas dalam format yang sama dengan provider bawaan.

import { createBackendModule } from '@backstage/backend-plugin-api';
import { authProvidersExtensionPoint } from '@backstage/plugin-auth-node';
import { myCustomProvider } from './providers';
 
export default createBackendModule({
  pluginId: 'auth',
  moduleId: 'custom-provider',
  register(reg) {
    reg.registerInit({
      deps: { authProviders: authProvidersExtensionPoint },
      async init({ authProviders }) {
        authProviders.registerProvider({
          providerId: 'custom',
          factory: myCustomProvider,
        });
      },
    });
  },
});

Setelah didaftarkan, provider kustom diperlakukan seperti provider lain: muncul di halaman login dan bisa dipasang ke sign-in resolvers.

#Sign-in Resolvers

Saat user terautentikasi di provider eksternal, Backstage belum tahu siapa user itu di dalam katalog. Sign-in resolver menjembatani keduanya: ia memetakan profil dari provider ke sebuah entity user di katalog, biasanya berdasarkan email atau username. Resolver dipasang per provider lewat signIn.resolvers — resolvers ini juga dapat dipasang untuk semua provider.

auth:
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityAnnotation

emailMatchingUserEntityAnnotation mencocokkan email dari provider dengan email pada entity user di katalog. Jika tidak ada resolver yang cocok, sign-in gagal — ini bukan bug, melainkan mekanisme kontrol: hanya user yang terdaftar di katalog yang boleh masuk.

#Backstage Identity

#Token, Header, dan Principal

Setelah sign-in berhasil, Backstage membangun identitas yang dipakai di seluruh sistem. Tiga konsep yang harus kalian kenali:

Backstage token adalah token JWT yang diterbitkan saat user sign-in. Token ini berumur pendek dan berisi klaim seperti identitas user. Header Backstage-Identity adalah kanal yang membawa token itu dari frontend ke backend — setiap request yang membutuhkan identitas user menyertakannya. User principal adalah hasil resolusi token menjadi objek identitas berisi referensi entity user, entity yang dimiliki user, dan atribut tambahan. Principal inilah yang menjadi konteks setiap permintaan di plugin backend.

#Identity di Backend

Backend-to-backend communication juga memakai token, tetapi dengan cara yang berbeda dari frontend: service identity menggunakan token layanan, sementara request dari frontend memakai token user yang dibawa header Backstage-Identity. Backend memverifikasi token untuk memastikan dari mana request datang, lalu menerjemahkannya menjadi user principal bagi plugin.

curl -i "http://localhost:7007/api/catalog/entities" \
  -H "Authorization: Bearer ${BACKSTAGE_USER_TOKEN}"

Nilai variabel BACKSTAGE_USER_TOKEN adalah token yang diambil dari sesi login. Backend memverifikasi token tersebut, membangun user principal, dan mengeksekusi request dalam konteks identitas itu — termasuk aturan kepemilikan yang akan kita bahas lebih jauh di episode 11 dan framework permission di episode 13.

#Penutup

Pada episode 8 ini, kalian mengamankan pintu masuk Backstage: perbedaan authentication dan identity, katalog auth provider dari guest mode, OIDC, GitHub, Google, SAML, hingga Microsoft Entra ID dan provider kustom, peran sign-in resolver dalam memetakan user eksternal ke katalog, serta jalur identitas Backstage melalui token, header Backstage-Identity, dan user principal.

Inti yang harus dibawa pulang:

• Guest mode hanya untuk development — di produksi gunakan provider sungguhan, dan jangan pernah biarkan guest tetap aktif.
• Auth provider dan identitas adalah dua lapis — provider membuktikan siapa user, sign-in resolver menautkannya ke entity katalog.
• Token berumur pendek, header membawanya — frontend mengirim Backstage-Identity; backend memverifikasi dan membangun user principal.
• Custom provider dimungkinkan — IdP internal bisa dibungkus lewat auth extension point di backend.

Di episode 9 berikutnya, kita merapikan fondasi yang kalian ubah-ubah sepanjang series ini: Konfigurasi Lanjutan & Secrets — bagaimana app-config divalidasi, bagaimana variabel lingkungan disubstitusi, serta bagaimana rahasia seperti kredensial auth provider disimpan tanpa pernah menyentuh repository.