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,
.envproduction yang terlindungi di level server,- user database dengan hak minimal,
- pilihan penyimpanan secret:
.envterenkripsi 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 |
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_KEYberbeda. - Jangan pernah menyalin
APP_KEYproduction 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:
- 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. - Periksa penyalahgunaan. Lihat log penyedia (transaksi payment gateway, pesan WhatsApp terkirim, akses S3) dan log aplikasi sejak waktu perkiraan kebocoran.
- Tutup jalur kebocoran. Hapus dari repository, perbaiki konfigurasi debug/log, tambahkan aturan gitleaks bila perlu.
- Bersihkan riwayat bila secret ada di Git (
git filter-repo), dan minta semua kolaborator meng-clone ulang. Ingat: ini tidak menggantikan rotasi. - 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 folderconfig/; 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:cachedi production menghindari pembacaan.envdi 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.exampleselalu 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
- Laravel Security Hardening: 15 Langkah Penting Sebelum Aplikasi Dipublikasikan
- Checklist Audit Keamanan Website Laravel Menggunakan OWASP ZAP dan OWASP Top 10
- Mencegah SQL Injection, Cross-Site Scripting, dan CSRF pada Aplikasi Laravel
- Membuat Dokumentasi API dan Panduan Instalasi Source Code Laravel untuk Pelanggan
Last Tested
| Komponen | Versi |
|---|---|
| Laravel | 13.x |
| PHP | 8.4 |
| MySQL | 8.4 LTS |
| gitleaks | 8.x |
| Tanggal | 19 Oktober 2026 |