Cara Pasang Authentik SSO dengan Docker Compose

Satu log masuk untuk setiap aplikasi yang dihoskan

Authentik ialah pelayan SSO (single sign-on) yang dihoskan sendiri: pengguna anda log masuk sekali, dan setiap aplikasi di belakangnya menerima sesi tersebut tanpa meminta kata laluan sendiri. Pemasangan ini menggunakan fail Docker Compose rasmi dan dua rahsia yang dijana. Bahagian yang memerlukan pertimbangan sebenar datang selepas itu: menghalakan reverse proxy kepadanya dan meletakkan satu aplikasi sedia ada di belakang forward auth.

Authentik disediakan sebagai tiga servis dalam fail Compose tersebut: pangkalan data PostgreSQL, proses server dan proses worker. Kontena pelayan turut menjalankan outpost terbenam, iaitu komponen yang menjawab soalan "adakah permintaan ini sudah dilog masuk?" untuk setiap aplikasi yang dilindungi. Versi 2026.8.5 ialah keluaran semasa pada 25 October 2026. Versi ini diterbitkan pada 21 October 2026 sebagai patch terkini bagi siri 2026.8, yang bermula dengan 2026.8.0 pada 18 August, dan menggantikan 2026.8.4 dari 14 October sebagai tag imej lalai dalam fail Compose rasmi. Projek ini memerlukan host dengan sekurang-kurangnya 2 teras CPU dan 2 GB RAM. Anggap nilai itu sebagai had minimum. PostgreSQL dan worker kedua-duanya menggunakan memori selepas pelayan berjalan selama sehari.

Keperluan sebelum bermula

Anda memerlukan Docker Engine dengan pemalam Compose v2, yang boleh disahkan dengan docker compose version. Jika arahan tersebut memaparkan ralat dan bukannya versi, pasang pemalam tersebut sebelum meneruskan; asasnya telah diterangkan dalam menjalankan aplikasi dengan Docker Compose pada VPS. Anda juga memerlukan rekod DNS A yang menghala ke pelayan, iaitu auth.example.com dalam contoh di bawah, kerana Authentik membina URL ubah hala (redirect) berdasarkan nama hos yang digunakan oleh pelayar.

Jalankan stack sebagai pengguna biasa dalam kumpulan docker dan bukannya sebagai root. Keahlian dalam kumpulan tersebut adalah setara dengan root pada hos, jadi berikan akses ini kepada satu akaun penggunaan sahaja dan tiada akaun lain, mengikut panduan akaun pengguna dengan keistimewaan minimum pada VPS.

Pasang dengan fail Compose rasmi

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps sepatutnya menyenaraikan tiga kontena yang semuanya aktif, dengan postgresql melaporkan healthy selepas semakannya berjaya. Permulaan pertama menjalankan migrasi pangkalan data, jadi tunggu seminit sebelum antara muka web memberikan respons.

Kedua-dua nilai yang dijana itu penting atas sebab yang berbeza. PG_PASS ialah kata laluan PostgreSQL. Dokumentasi pemasangan Authentik menyatakan bahawa kata laluan melebihi 99 aksara tidak disokong, jadi pastikan sebarang kata laluan yang anda pilih sendiri kurang daripada had itu; kata laluan yang dijana jauh lebih pendek. AUTHENTIK_SECRET_KEY ialah kunci yang digunakan Authentik untuk menandatangani kuki, dan dokumentasi konfigurasinya menyatakan bahawa perubahan kunci ini akan membatalkan sesi aktif. Oleh itu, kunci baharu akan melog keluar setiap pengguna yang sedang log masuk. Tetapkan .env kepada mod 600 dan simpan salinannya di tempat yang selamat bersama sandaran anda, supaya pemulihan menggunakan kunci yang sama seperti pelayan asal.

Fail Compose menandakan kedua-dua nilai sebagai wajib menggunakan bentuk ${VAR:?message}: ${PG_PASS:?database password required} pada servis PostgreSQL dan ${AUTHENTIK_SECRET_KEY:?secret key required} pada server serta worker. Ini bermakna Compose enggan bermula apabila fail tersebut tiada. Menjalankan docker compose up -d dari direktori yang salah mencetak baris seperti required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required lalu berhenti. Mesej itu menunjukkan masalah path, bukan masalah konfigurasi.

Nilai persekitaran yang penting

Segala tetapan lain diletakkan dalam fail .env yang sama. Authentik memetakan garis bawah berkembar kepada kunci konfigurasi bersarang, jadi AUTHENTIK_EMAIL__HOST menetapkan email.host. Garis bawah tunggal tidak memetakan kepada kunci bersarang, yang merupakan punca paling lazim mengapa sesuatu tetapan kelihatan tidak berfungsi.

• AUTHENTIK_BOOTSTRAP_PASSWORD menetapkan kata laluan pengguna terbina dalam akadmin pada permulaan pertama, supaya anda tidak perlu menaipnya ke dalam borang web awam. AUTHENTIK_BOOTSTRAP_EMAIL dan AUTHENTIK_BOOTSTRAP_TOKEN menetapkan alamat pengguna tersebut serta token API dengan cara yang sama.
• COMPOSE_PORT_HTTP dan COMPOSE_PORT_HTTPS menukar port yang diterbitkan daripada nilai lalai 9000 dan 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS dan AUTHENTIK_EMAIL__FROM mengkonfigurasi e-mel keluar. Tanpanya, Authentik akan mencuba localhost pada port 25, menyebabkan e-mel tetapan semula kata laluan berakhir sebagai ralat sambungan dalam log worker.
• AUTHENTIK_LOG_LEVEL=debug menghidupkan perincian yang anda perlukan semasa aliran log masuk tidak berfungsi dengan betul. Kembalikan kepada info selepas selesai.
• AUTHENTIK_ERROR_REPORTING__ENABLED ditetapkan kepada false secara lalai. Tetapkan kepada true hanya jika anda bersetuju untuk menghantar laporan ranap ke hulu (upstream).

Ini adalah rahsia dalam fail teks biasa, jadi kendalikan direktori tersebut seperti mana-mana stor kelayakan lain. Pengurus kata laluan seperti instans Vaultwarden yang dihoskan sendiri adalah tempat yang lebih baik untuk menyimpan salinan pemulihan berbanding nota pada komputer riba anda.

Log masuk pertama dan akaun pentadbir

Buka http://SERVER_IP:9000 dalam pelayar. Authentik memaparkan aliran persediaan awal dan meminta anda menetapkan kata laluan untuk pengguna akadmin lalai. Jika anda sudah menetapkan AUTHENTIK_BOOTSTRAP_PASSWORD, langkah itu telah selesai dan anda terus ke halaman log masuk.

Cipta pengguna pentadbir biasa untuk diri sendiri di bawah Directory dan kemudian Users, tambah pengguna itu ke kumpulan authentik Admins, lalu log masuk menggunakan akaun tersebut. Kekalkan akadmin sebagai akaun break-glass dengan kata laluan panjang yang disimpan di luar talian. Jika flow atau stage yang rosak menyebabkan anda terkunci, docker compose run --rm server create_recovery_key 10 akadmin yang dijalankan dari /opt/authentik mencetak pautan untuk log masuk terus sebagai akadmin. Sesiapa yang memiliki pautan itu mempunyai akses yang sama, jadi anggap pautan tersebut seperti kata laluan. Kerja harian menggunakan akaun terbina dalam yang dikongsi akan merosakkan log audit kerana setiap peristiwa menunjukkan akadmin dan tidak menunjukkan identiti sebenar. Hujah ini turut terpakai selepas Authentik: sesuatu seperti harness OneCLI yang dihoskan sendiri dan memberikan setiap orang agent mereka sendiri hanya menghasilkan jejak yang boleh dibaca jika identiti yang tiba padanya dimiliki oleh seorang manusia, bukannya log masuk yang dikongsi oleh seluruh pasukan.

Meletakkan Authentik di belakang reverse proxy anda

Mendedahkan port 9000 kepada internet memang berfungsi, tetapi anda memerlukan TLS (transport layer security) dan nama hos yang sebenar. Jika anda sudah menjalankan persediaan daripada Traefik sebagai reverse proxy untuk pelbagai aplikasi Compose, sertakan Authentik ke dalam rangkaian proxy luaran yang sama menggunakan fail override. Cipta docker-compose.override.yml bersebelahan dengan compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Gunakan ia dengan docker compose up -d. Compose akan menggabungkan override tersebut secara automatik, jadi servis server mengekalkan semua tetapan daripada fail rasmi dan menerima label-label tersebut. Semak dengan curl -I https://auth.example.com/if/user/, yang sepatutnya memberikan jawapan HTTP/2 200. 404 page not found daripada Traefik bermakna tiada router yang sepadan dengan permintaan tersebut. Pastikan label telah sampai ke dalam container, peraturan Host() sepadan tepat dengan nama hos, dan permintaan sampai ke entry point HTTPS yang dipantau oleh router.

Apabila nama hos sudah berfungsi, ikat port yang didedahkan kepada 127.0.0.1 di dalam override, supaya satu-satunya laluan masuk adalah melalui proxy.

Melindungi satu aplikasi dengan forward auth

Penyedia proksi Authentik mempunyai tiga mod, dan memilih mod yang salah akan membuang masa anda selama sejam. Proxy bermaksud outpost itu sendiri yang memajukan trafik ke aplikasi hulu (upstream). Forward auth (single application) bermaksud reverse proxy anda sendiri yang menggerakkan trafik dan hanya bertanya kepada Authentik sama ada permintaan tersebut telah dilog masuk. Forward auth (domain level) melindungi setiap aplikasi di bawah satu domain induk dengan satu penyedia, namun anda akan kehilangan keupayaan untuk menetapkan peraturan kebenaran bagi setiap aplikasi. Dengan Traefik di hadapan, anda disarankan menggunakan forward auth (single application). Jika anda mahukan aplikasi konkrit untuk latihan, sesuatu seperti ruang kerja AFFiNE yang dihoskan sendiri adalah calon pertama yang baik, kerana ia merupakan jenis alat dalaman yang anda mahu boleh dicapai daripada peranti anda sendiri sahaja. Alat pasukan menjadikan keperluan ini lebih mendesak: letakkan meja bantuan Chatwoot yang dihoskan sendiri di belakang penyedia yang sama supaya setiap orang yang menjawab peti masuk hanya perlu melog masuk sekali sehari, bukannya berkongsi satu lagi kata laluan.

Dalam antara muka web, buka Applications dan kemudian Providers, cipta Proxy Provider, pilih mod forward auth single application, dan tetapkan external host kepada https://app.example.com. Cipta Application yang menghala kepada penyedia tersebut. Kemudian buka Outposts, edit authentik Embedded Outpost, dan masukkan aplikasi baharu tersebut ke dalam selected applications. Outpost hanya menjawab bagi aplikasi yang telah diberikan kepadanya, jadi melangkau langkah terakhir ini adalah sebab mengapa penyedia yang dikonfigurasikan dengan betul masih tidak memberikan sebarang hasil.

Takrifkan middleware sekali sahaja, pada kontena Authentik, dan rujuk ia daripada setiap aplikasi yang dilindungi:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders ialah senarai pengepala (headers) yang disalin oleh Traefik daripada jawapan Authentik ke atas permintaan yang dihantar ke hulu. Jika anda meninggalkannya, aplikasi tersebut masih dilindungi, tetapi ia tidak akan mengetahui siapa penggunanya, jadi sebarang aplikasi yang membaca X-authentik-username untuk log masuk automatik akan kekal dalam keadaan log keluar. Jurang ini paling ketara di hadapan aplikasi yang mempunyai sistem log masuk sendiri, seperti penjejak senaman openGym yang dihoskan sendiri dan log masuk passkey-nya, di mana pengepala tersebut menentukan sama ada anda perlu melalui satu atau dua gesaan untuk halaman yang sama.

Aplikasi yang dilindungi itu sendiri memerlukan dua router, bukan satu:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

Router kedua adalah bahagian yang sering dilupakan oleh semua orang. Selepas log masuk, Authentik menghantar pelayar kembali ke path di bawah /outpost.goauthentik.io/ pada hostname aplikasi, bukan pada auth.example.com. Tanpa router yang menghantar awalan path tersebut ke servis Authentik, permintaan itu akan sampai ke aplikasi anda, yang kemudiannya akan memberikan ralat 404, dan proses log masuk tidak akan selesai. Nilai priority yang lebih tinggi adalah sebab mengapa peraturan path khusus mengatasi peraturan Host() biasa pada domain yang sama.

Uji perkara ini dalam tetingkap pelayar peribadi. Anda sepatutnya dihantar ke auth.example.com, melog masuk, dan kembali ke aplikasi tersebut. docker compose logs -f server pada bahagian Authentik akan mencetak peristiwa kebenaran bagi setiap percubaan, yang memberitahu anda sama ada permintaan tersebut sampai ke Authentik atau tidak.

Kegagalan yang akan anda temui

Gelung ubah hala (redirect loop) yang tidak berkesudahan antara aplikasi dan halaman log masuk. Host luaran pada penyedia tidak sepadan dengan apa yang digunakan oleh pelayar, biasanya http:// pada penyedia berbanding https:// pada bar alamat. Kuki sesi kemudian ditetapkan untuk origin yang berbeza, jadi setiap perjalanan kembali kelihatan seperti permintaan tanpa nama yang baharu. Betulkan host luaran dan kosongkan kuki untuk kedua-dua domain sebelum menguji semula.

404 pada /outpost.goauthentik.io/start. Router outpost tiada, atau keutamaannya lebih rendah daripada router tangkap-semua (catch-all) untuk host tersebut.

Aplikasi dimuatkan tanpa meminta log masuk. Label middlewares menamakan middleware yang tidak wujud. Traefik tidak memberi amaran tentang perkara itu, jadi kesilapan taip pada authentik@docker bermakna tiada middleware yang dijalankan. Buka papan pemuka Traefik dan sahkan router menyenaraikan middleware tersebut.

403 daripada Authentik selepas log masuk berjaya. Pengguna disahkan tetapi tidak dibenarkan: aplikasi membawa pengikatan polisi (policy binding), atau keperluan kumpulan, yang tidak dipenuhi oleh pengguna ini. Log Events dalam antara muka pentadbir menamakan polisi yang menafikannya.

Apabila Keycloak menjadi pilihan yang lebih sesuai

Keycloak merupakan projek yang lebih lama, disokong oleh Red Hat, dan merupakan pilihan yang lebih mantap untuk tugasan identiti perusahaan klasik: federasi SAML yang berat, pengantaraan log masuk daripada beberapa penyedia identiti luaran secara serentak, serta eksport dan import realm sebagai laluan migrasi yang didokumentasikan. Sokongan komersial di sebaliknya penting bagi sesetengah organisasi atas dasar pematuhan. Kekurangannya ialah Keycloak tidak mempunyai proksi sendiri, jadi untuk melindungi aplikasi yang tidak menyokong OIDC (OpenID Connect) mahupun SAML, anda perlu menjalankan perisian seperti oauth2-proxy di sampingnya. Penyedia proksi terbina dalam Authentik merupakan komponen tersebut yang telah disepadukan, itulah sebabnya kebanyakan pengguna yang melakukan self-hosting dengan pelbagai jenis aplikasi memilih platform ini.

Sandaran dan naik taraf

Tiga perkara diperlukan untuk membolehkan pemulihan: pangkalan data PostgreSQL, direktori ./data dan .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Simpan dump tersebut bersama .env. Dump itu tidak mengandungi salinan AUTHENTIK_SECRET_KEY, dan pemulihan menggunakan kunci yang berbeza akan membatalkan setiap sesi aktif. Oleh itu, menyimpan kunci asal membolehkan pelayan yang dipulihkan meneruskan operasi seperti sebelumnya.

Naik taraf dilakukan dengan menukar tag. Tetapkan AUTHENTIK_TAG dalam .env kepada keluaran yang anda mahu, kemudian jalankan docker compose pull diikuti docker compose up -d. Jika anda tidak pernah menetapkan AUTHENTIK_TAG, versi tersebut datang daripada nilai lalai yang ditulis dalam compose.yml itu sendiri. Oleh itu, memuat turun salinan fail yang lebih baharu ialah proses naik taraf, dan itulah kaedah yang diterangkan dalam dokumentasi naik taraf rasmi. Baca nota keluaran terlebih dahulu. Authentik menggunakan versi berasaskan tarikh, dan setakat October 2026 dokumentasinya menyatakan bahawa naik taraf mesti mengikut urutan keluaran utama: beralih dahulu ke patch terkini bagi siri yang sedang digunakan, kemudian ikuti setiap siri seterusnya mengikut urutan tanpa melangkau mana-mana siri. Authentik tidak menyokong downgrade, jadi buat dump pangkalan data sebelum pull, bukan selepasnya.

FAQ

Adakah Authentik percuma untuk dihoskan sendiri?

Edisi sumber terbuka adalah percuma dan merangkumi semua perkara di atas: penyedia proksi, forward auth, OIDC (OpenID Connect), SAML, dan enjin aliran. Peringkat perusahaan berbayar menambah sokongan dan beberapa ciri perusahaan, tetapi tiada apa-apa di sini yang memerlukan lesen.

Adakah saya memerlukan Traefik untuk menggunakan Authentik?

Tidak. Forward auth berfungsi dengan nginx melalui auth_request dan dengan Caddy melalui forward_auth. Polanya adalah sama dalam setiap kes: reverse proxy bertanya kepada Authentik tentang setiap permintaan, dan awalan laluan /outpost.goauthentik.io/ pada nama hos yang dilindungi mesti menghala ke Authentik dan bukannya ke aplikasi.

Mengapa aplikasi saya yang dilindungi melantun antara log masuk dan ralat selama-lamanya?

Hos luaran yang dikonfigurasikan pada penyedia proksi tidak sepadan dengan URL yang digunakan oleh pelayar, paling kerap http berbanding https. Kuki sesi dikeluarkan untuk satu asal dan dibaca pada yang lain, jadi Authentik melihat permintaan tanpa nama setiap kali. Betulkan hos luaran, kemudian kosongkan kuki untuk kedua-dua nama hos sebelum anda menguji semula.

Berapa banyak RAM yang diperlukan oleh Authentik?

Minimum yang didokumenkan ialah 2 teras CPU dan 2 GB RAM setakat Oktober 2026, merangkumi PostgreSQL, pelayan dan pekerja secara bersama. Pada kotak 2 GB, tekanan memori boleh mengejutkan OOM killer kernel, yang menamatkan proses dengan skor keburukan tertinggi: secara kasarnya bahagian memori dibenarkan yang digunakannya, ditambah oom_score_adj miliknya. Apabila ia ternyata adalah pekerja, simptomnya ialah tugas latar belakang dan e-mel keluar terhenti sementara halaman log masuk masih berfungsi. Berikan 4 GB jika pelayan yang sama juga menjalankan aplikasi yang anda lindungi.