Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / Keamanan / Cara Mengelola Secret, API Key...
Keamanan

Cara Mengelola Secret, API Key, dan Credential Database Laravel di Production

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
12 min read
35 views

Dari .env yang aman sampai rotasi kunci saat terjadi kebocoran: memisahkan secret dari kode, membaca secret dengan benar lewat config(), user database dengan hak minimal, .env terenkripsi, secret manager, mencegah secret bocor ke log dan browser, serta pemindaian otomatis dengan gitleaks.

Overview

Secret adalah nilai yang memberi akses: password database, APP_KEY, kunci API payment gateway, token WhatsApp gateway, kredensial SMTP, dan kunci S3. Kebocoran satu secret saja bisa berarti seluruh data warga terbuka atau dana di akun payment gateway disalahgunakan.

Cara secret bocor di proyek Laravel biasanya tidak canggih:

Jalur kebocoran Contoh
Repository .env ter-commit; kunci API ditulis langsung di config/services.php
Riwayat Git Secret dihapus di commit terbaru tetapi masih ada di commit lama
Halaman error APP_DEBUG=true di production menampilkan variabel lingkungan
Log Request ke API pihak ketiga dicatat lengkap beserta header Authorization
Browser Variabel VITE_* berisi secret ikut ter-bundle ke JavaScript
Server .env bisa dibaca semua user di server, atau bisa diunduh lewat web
Hak berlebih Aplikasi memakai user database root, sehingga celah SQL injection berdampak maksimal

Hasil akhir:

  • secret terpisah dari kode dan dibaca dengan pola yang benar,
  • .env production yang terlindungi di level server,
  • user database dengan hak minimal,
  • pilihan penyimpanan secret: .env terenkripsi atau secret manager,
  • pencegahan kebocoran ke log, halaman error, dan browser,
  • pemindaian secret otomatis di Git,
  • prosedur rotasi saat secret bocor.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Database MySQL 8.0+ / PostgreSQL 15+
Git 2.40+
gitleaks 8.x
Opsional AWS Secrets Manager / SSM Parameter Store, HashiCorp Vault, atau fitur environment di panel hosting (Laravel Cloud, Forge)

Step-by-step Tutorial

Langkah 1: Inventarisasi Secret

Tulis semua secret yang dipakai aplikasi, beserta pemilik dan cara merotasinya. Daftar ini sendiri bukan secret, tetapi nilainya tidak boleh ada di dalamnya.

Secret Variabel Dipakai untuk Rotasi
Kunci aplikasi APP_KEY Enkripsi cookie, session, data encrypted Dengan APP_PREVIOUS_KEYS (Langkah 9)
Database DB_USERNAME, DB_PASSWORD Koneksi aplikasi Buat user baru, ganti, hapus user lama
Payment gateway PAYMENT_SERVER_KEY, PAYMENT_WEBHOOK_SECRET Transaksi dan verifikasi webhook Dasbor penyedia
WhatsApp gateway WA_API_TOKEN Notifikasi iuran Dasbor penyedia
SMTP MAIL_PASSWORD Email Penyedia email
Object storage AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY Lampiran IAM

Simpan tabel ini di docs/secrets.md.

Langkah 2: Pastikan Secret Tidak Masuk Repository

# .gitignore
.env
.env.*
!.env.example
/storage/*.key
auth.json

.env.example di-commit dengan nilai kosong atau contoh yang jelas palsu:

APP_KEY=
DB_PASSWORD=
PAYMENT_SERVER_KEY=
PAYMENT_WEBHOOK_SECRET=
WA_API_TOKEN=

Periksa apakah .env pernah ter-commit di masa lalu:

git log --all --oneline -- .env
git log --all -p -S "PAYMENT_SERVER_KEY=" | head -40

Bila ditemukan, anggap secret tersebut sudah bocor: rotasi dulu (Langkah 11), baru bersihkan riwayat. Menghapus file dari riwayat tidak menarik kembali salinan yang sudah di-clone atau di-fork orang lain.

Langkah 3: Baca Secret Hanya Lewat File Config

Aturan Laravel yang sering dilanggar: env() hanya dipanggil di dalam folder config/. Di tempat lain, gunakan config().

// config/services.php
'pembayaran' => [
    'server_key'     => env('PAYMENT_SERVER_KEY'),
    'webhook_secret' => env('PAYMENT_WEBHOOK_SECRET'),
    'production'     => env('PAYMENT_IS_PRODUCTION', false),
],

'whatsapp' => [
    'base_url' => env('WA_BASE_URL', 'https://api.wa-gateway.contoh'),
    'token'    => env('WA_API_TOKEN'),
],
// RENTAN / RUSAK di production: env() mengembalikan null setelah config:cache
$token = env('WA_API_TOKEN');

// BENAR
$token = config('services.whatsapp.token');

Setelah php artisan config:cache, Laravel tidak lagi membaca .env, sehingga env() di luar config mengembalikan null. Selain menyebabkan bug, pemakaian env() yang tersebar membuat secret sulit diaudit.

Pastikan aplikasi gagal sejak awal bila secret wajib tidak ada:

// app/Providers/AppServiceProvider.php
public function boot(): void
{
    if ($this->app->isProduction()) {
        foreach (['services.pembayaran.server_key', 'services.pembayaran.webhook_secret', 'services.whatsapp.token'] as $key) {
            if (blank(config($key))) {
                throw new \RuntimeException("Konfigurasi wajib [{$key}] belum diisi.");
            }
        }
    }
}

Langkah 4: Lindungi .env di Server

# Pemilik: user deploy; grup: user PHP-FPM; tidak bisa dibaca user lain
sudo chown deploy:www-data /var/www/rw/.env
sudo chmod 640 /var/www/rw/.env

Pastikan .env tidak bisa diunduh lewat web. Dengan document root ke public/, file di root proyek tidak terjangkau. Tetap tambahkan pengaman di Nginx:

location ~ /\.(?!well-known) {
    deny all;
}

Verifikasi:

curl -s -o /dev/null -w "%{http_code}\n" https://rw.contoh.id/.env        # harus 403 atau 404
curl -s -o /dev/null -w "%{http_code}\n" https://rw.contoh.id/../.env     # harus 400/404

Langkah 5: User Database dengan Hak Minimal

Jangan pernah memakai user root untuk aplikasi. Buat user khusus dengan hak hanya pada database aplikasi:

-- MySQL 8: user aplikasi (dipakai saat runtime)
CREATE USER 'rw_app'@'10.0.1.%' IDENTIFIED BY '<<password-acak-32-karakter>>';
GRANT SELECT, INSERT, UPDATE, DELETE ON rw_production.* TO 'rw_app'@'10.0.1.%';

-- User migrasi (dipakai hanya saat deploy)
CREATE USER 'rw_migrate'@'10.0.1.%' IDENTIFIED BY '<<password-acak-lain>>';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX, REFERENCES
    ON rw_production.* TO 'rw_migrate'@'10.0.1.%';

Pisahkan koneksi migrasi di konfigurasi:

// config/database.php → 'connections'
'mysql_migrate' => [
    'driver'    => 'mysql',
    'host'      => env('DB_HOST', '127.0.0.1'),
    'port'      => env('DB_PORT', '3306'),
    'database'  => env('DB_DATABASE'),
    'username'  => env('DB_MIGRATE_USERNAME'),
    'password'  => env('DB_MIGRATE_PASSWORD'),
    'charset'   => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix'    => '',
    'strict'    => true,
],

Isi DB_MIGRATE_USERNAME dan DB_MIGRATE_PASSWORD hanya di lingkungan deploy (misalnya disuntikkan oleh pipeline), bukan di .env yang dibaca aplikasi saat runtime. Lalu jalankan migrasi saat deploy dengan:

php artisan migrate --database=mysql_migrate --force

Dengan pemisahan ini, celah SQL injection di aplikasi tidak bisa dipakai untuk DROP TABLE. Batasi juga host asal ('10.0.1.%') agar user hanya bisa login dari server aplikasi, dan aktifkan TLS untuk koneksi database lintas jaringan.

Gunakan password acak yang panjang:

php -r "echo bin2hex(random_bytes(24)), PHP_EOL;"

Langkah 6: Opsi A — .env Terenkripsi di Repository

Laravel bisa mengenkripsi file .env agar bisa disimpan di repository dengan aman. Kunci dekripsi disimpan terpisah (misalnya di secret CI).

# Di mesin admin
php artisan env:encrypt --env=production
#   INFO  Environment successfully encrypted.
#   Key ..................... base64:3UVY...
#   Cipher .................. AES-256-CBC
#   Encrypted file .......... .env.production.encrypted

Commit .env.production.encrypted, jangan commit kuncinya. Simpan kunci di secret manager atau secret CI/CD (LARAVEL_ENV_ENCRYPTION_KEY).

Saat deploy:

php artisan env:decrypt --env=production --key="$LARAVEL_ENV_ENCRYPTION_KEY" --force
mv .env.production .env
chmod 640 .env
php artisan config:cache

Kelebihan: perubahan konfigurasi ter-versi dan bisa di-review. Kekurangan: semua yang memegang kunci bisa membaca semua secret production.

Langkah 7: Opsi B — Secret Manager

Untuk tim yang lebih besar atau kebutuhan audit akses, simpan secret di secret manager dan tulis .env saat deploy. Contoh dengan AWS SSM Parameter Store:

# Simpan (sekali, oleh admin)
aws ssm put-parameter --name /rw/production/DB_PASSWORD --type SecureString --value '***'
aws ssm put-parameter --name /rw/production/PAYMENT_SERVER_KEY --type SecureString --value '***'
#!/usr/bin/env bash
# deploy/render-env.sh — dijalankan di server saat deploy
set -euo pipefail

cp .env.base .env      # konfigurasi non-rahasia (APP_URL, LOG_CHANNEL, dsb.)

aws ssm get-parameters-by-path --path /rw/production/ --with-decryption \
  --query 'Parameters[*].[Name,Value]' --output text |
while IFS=$'\t' read -r name value; do
  printf '%s=%q\n' "${name##*/}" "$value" >> .env
done

chmod 640 .env
php artisan config:cache

Server diberi izin IAM untuk membaca path /rw/production/ saja. Prinsip yang sama berlaku untuk HashiCorp Vault, Doppler, atau fitur pengelolaan environment di panel hosting.

.env manual di server .env terenkripsi Secret manager
Kesederhanaan Tinggi Sedang Rendah–sedang
Riwayat perubahan Tidak ada Git Ada (versi parameter)
Kontrol akses per secret Tidak Tidak Ya
Log siapa membaca Tidak Tidak Ya
Cocok untuk Proyek kecil, satu server Tim kecil dengan CI/CD Tim besar, kepatuhan

Langkah 8: Cegah Secret Bocor ke Error, Log, dan Browser

Halaman error. Production wajib:

APP_ENV=production
APP_DEBUG=false

Parameter sensitif di stack trace. Tandai parameter dengan atribut PHP agar nilainya tidak muncul di stack trace:

final class WhatsAppClient
{
    public function __construct(
        private readonly string $baseUrl,
        #[\SensitiveParameter] private readonly string $token,
    ) {}
}

Log HTTP client. Jangan mencatat header Authorization atau body yang berisi kunci:

Http::withToken(config('services.whatsapp.token'))
    ->post($url, $payload)
    ->onError(fn ($response) => Log::warning('wa.gagal', [
        'status' => $response->status(),
        'body'   => Str::limit($response->body(), 500),   // tanpa header request
    ]));

Browser. Semua variabel berawalan VITE_ di .env ikut ter-bundle ke JavaScript dan bisa dibaca siapa pun:

VITE_APP_NAME="${APP_NAME}"        # aman: memang publik
VITE_MAPS_PUBLIC_KEY=pk_...        # aman bila kunci memang publik dan dibatasi domain
# JANGAN: VITE_PAYMENT_SERVER_KEY=...

Periksa hasil build:

npm run build
grep -rE "sk_live|server_key|SECRET|PASSWORD" public/build/ && echo "PERIKSA: kemungkinan secret ter-bundle"

Langkah 9: Kelola APP_KEY dengan Benar

APP_KEY mengenkripsi cookie, session, dan kolom ber-cast encrypted. Kunci yang bocor memungkinkan pemalsuan cookie terenkripsi.

  • Setiap lingkungan (lokal, staging, production) memiliki APP_KEY berbeda.
  • Jangan pernah menyalin APP_KEY production ke laptop.
  • Rotasi tanpa membuat semua pengguna logout dan tanpa merusak data terenkripsi:
APP_KEY=base64:kunci-baru...
APP_PREVIOUS_KEYS=base64:kunci-lama...

Laravel akan mengenkripsi dengan kunci baru dan masih bisa mendekripsi data lama dengan kunci di APP_PREVIOUS_KEYS. Setelah semua data terenkripsi dan session lama berganti (misalnya dengan mengenkripsi ulang kolom encrypted lewat command khusus), hapus kunci lama.

php artisan key:generate --show      # buat kunci baru tanpa menulis ke .env

Langkah 10: Pemindaian Secret Otomatis

Gunakan gitleaks di dua tempat: sebelum commit (lokal) dan di CI.

# Pindai seluruh riwayat repository sekali
gitleaks git --report-path gitleaks-report.json -v

Pre-commit hook:

#!/usr/bin/env bash
# .githooks/pre-commit
gitleaks git --pre-commit --staged --redact -v || {
  echo "Commit dibatalkan: kemungkinan ada secret. Periksa keluaran di atas."
  exit 1
}
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

CI:

# .github/workflows/secrets.yml
name: Secret scan
on: [push, pull_request]
jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Untuk false positive (misalnya contoh kunci di dokumentasi), gunakan file .gitleaksignore berisi fingerprint temuan, bukan menonaktifkan aturannya. Periksa juga syarat lisensi gitleaks-action untuk repository milik organisasi.

Langkah 11: Prosedur Saat Secret Bocor

Tulis prosedur ini sebelum terjadi insiden:

  1. Rotasi segera. Buat kunci baru di penyedia, perbarui di server/secret manager, deploy ulang (config:cache), lalu cabut kunci lama. Urutan ini penting agar aplikasi tidak mati.
  2. Periksa penyalahgunaan. Lihat log penyedia (transaksi payment gateway, pesan WhatsApp terkirim, akses S3) dan log aplikasi sejak waktu perkiraan kebocoran.
  3. Tutup jalur kebocoran. Hapus dari repository, perbaiki konfigurasi debug/log, tambahkan aturan gitleaks bila perlu.
  4. Bersihkan riwayat bila secret ada di Git (git filter-repo), dan minta semua kolaborator meng-clone ulang. Ingat: ini tidak menggantikan rotasi.
  5. Catat kejadian, dampak, dan perbaikan di log insiden.

Contoh urutan rotasi password database tanpa downtime:

CREATE USER 'rw_app_v2'@'10.0.1.%' IDENTIFIED BY '<<password-baru>>';
GRANT SELECT, INSERT, UPDATE, DELETE ON rw_production.* TO 'rw_app_v2'@'10.0.1.%';
# perbarui DB_USERNAME/DB_PASSWORD, lalu:
php artisan config:cache && php artisan queue:restart
# pastikan aplikasi berjalan, kemudian:
DROP USER 'rw_app'@'10.0.1.%';

Langkah 12: Test dan Pemeriksaan Otomatis

// tests/Feature/Security/SecretsTest.php
it('tidak memanggil env() di luar folder config', function () {
    $pelanggaran = collect(\Symfony\Component\Finder\Finder::create()->in(app_path())->name('*.php'))
        ->filter(fn ($file) => preg_match('/\benv\(/', $file->getContents()))
        ->map(fn ($file) => $file->getRelativePathname())
        ->values();

    expect($pelanggaran)->toBeEmpty();
});

Untuk memeriksa .env server yang sebenarnya (misalnya APP_DEBUG=false), gunakan perintah pemeriksa saat deploy seperti app:check-install pada artikel Membuat Dokumentasi API dan Panduan Instalasi Source Code Laravel, bukan test unit.

Dengan Pest, pemeriksaan pertama bisa ditulis lebih ringkas sebagai test arsitektur:

arch('env() hanya di config')
    ->expect('env')
    ->not->toBeUsedIn('App');

Troubleshooting

Error / Gejala Penyebab Solusi
Nilai konfigurasi null di production env() dipanggil di luar config setelah config:cache Pindahkan ke file config, baca dengan config()
Perubahan .env tidak berlaku Konfigurasi masih di-cache php artisan config:cache (atau config:clear), restart queue worker dan Octane
The MAC is invalid setelah ganti APP_KEY Data/cookie lama dienkripsi kunci lama Isi APP_PREVIOUS_KEYS dengan kunci lama
SQLSTATE[42000]: ... command denied to user 'rw_app' saat migrate User runtime memang tidak punya hak DDL Jalankan migrasi dengan koneksi mysql_migrate
env:decrypt gagal Kunci salah atau cipher berbeda Pastikan kunci dan --cipher sama dengan saat enkripsi
gitleaks menandai contoh di dokumentasi Pola menyerupai kunci asli Tambahkan fingerprint ke .gitleaksignore dengan alasan
Secret muncul di bundle JavaScript Variabel berawalan VITE_ Hapus dari VITE_*; ambil data lewat endpoint server bila diperlukan
.env bisa diunduh Document root mengarah ke root proyek Arahkan document root ke public/, tambahkan aturan deny dotfile

Best Practices

Keamanan

  • Secret tidak pernah ada di kode, repository, log, halaman error, atau bundle frontend.
  • env() hanya di folder config/; validasi secret wajib saat aplikasi boot di production.
  • User database dengan hak minimal; pisahkan user migrasi dan user runtime.
  • Secret berbeda untuk setiap lingkungan; kunci uji (sandbox) untuk staging.
  • Batasi kunci API di sisi penyedia (IP, domain, scope) bila tersedia.
  • Pindai secret di pre-commit dan CI; siapkan prosedur rotasi sebelum dibutuhkan.

Performa

  • config:cache di production menghindari pembacaan .env di setiap request.
  • Ambil secret dari secret manager saat deploy, bukan di setiap request.

Maintainability

  • Inventaris secret di docs/secrets.md (tanpa nilai), lengkap dengan pemilik dan cara rotasi.
  • .env.example selalu lengkap dan diperbarui bersama kode.
  • Jadwalkan rotasi berkala untuk secret penting (misalnya setiap 6–12 bulan) dan setiap kali anggota tim yang memegang akses keluar.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
MySQL 8.4 LTS
gitleaks 8.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya