Cara Pasang Authentik SSO dengan Docker Compose

Satu log masuk untuk setiap aplikasi yang anda hoskan

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

Authentik diedarkan sebagai tiga servis dalam fail Compose tersebut: pangkalan data PostgreSQL, proses server, dan proses worker. Kontena pelayan juga menjalankan outpost terbenam, iaitu komponen yang menjawab "adakah permintaan ini telah log masuk?" bagi setiap aplikasi yang dilindungi. Versi 2026.5 ialah keluaran semasa setakat Julai 2026, dan projek ini memerlukan hos dengan sekurang-kurangnya 2 teras CPU dan 2 GB RAM. Anggap itu sebagai keperluan minimum. PostgreSQL dan worker kedua-duanya akan menggunakan memori sebaik sahaja pelayan telah beroperasi 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.

Pemasangan menggunakan 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, dengan postgresql melaporkan healthy serta server dan worker melaporkan running. Permulaan pertama akan menjalankan migrasi pangkalan data, jadi tunggu selama seminit sebelum antara muka web memberikan respons.

Kedua-dua nilai yang dijana adalah penting atas sebab yang berbeza. PG_PASS ialah kata laluan PostgreSQL, dan ia mempunyai had maksimum 99 aksara. AUTHENTIK_SECRET_KEY menandatangani sesi dan token, jadi menukarnya kemudian akan menyebabkan semua pengguna dilog keluar dan membatalkan setiap token API yang telah anda keluarkan. Pastikan .env berada pada mod 600 dan simpan salinannya di tempat yang selamat, kerana pangkalan data yang dipulihkan tanpa kunci rahsia yang sepadan adalah pangkalan data yang tidak boleh diakses oleh sesiapa pun.

Fail Compose membaca kedua-dua nilai tersebut dengan format ${PG_PASS:?database password required}, yang bermaksud Compose akan enggan bermula apabila fail tersebut tiada. Menjalankan docker compose up -d dari direktori yang salah akan memaparkan required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required dan terhenti. Mesej tersebut merupakan masalah laluan, 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 diabaikan tanpa sebarang amaran, yang merupakan punca paling lazim mengapa sesuatu tetapan kelihatan tidak berfungsi.

• AUTHENTIK_BOOTSTRAP_PASSWORD menetapkan kata laluan bagi pengguna terbina dalam akadmin semasa 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 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 pekerja.
• 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 adalah 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 web. Authentik akan memaparkan aliran persediaan awal dan meminta anda menetapkan kata laluan untuk pengguna lalai akadmin. Jika anda telah menetapkan AUTHENTIK_BOOTSTRAP_PASSWORD, langkah tersebut selesai dan anda akan terus dibawa ke halaman log masuk.

Cipta pengguna pentadbir biasa untuk diri anda di bawah Directory kemudian Users, tambah pengguna itu kepada kumpulan authentik Admins, lalu log masuk menggunakan akaun tersebut. Kekalkan akadmin sebagai akaun break-glass dengan kata laluan yang panjang dan disimpan di luar talian. Kerja harian menggunakan akaun terbina dalam yang dikongsi akan merosakkan log audit kerana setiap peristiwa hanya menunjukkan akadmin dan tidak menunjukkan siapa yang melakukannya. Hujah ini juga terpakai selepas Authentik: sesuatu seperti harness OneCLI yang dihoskan sendiri dan memberikan setiap orang ejen mereka sendiri hanya menghasilkan jejak yang mudah dibaca jika identiti yang tiba padanya milik seorang individu, bukannya log masuk yang dikongsi oleh seluruh pasukan.

Letakkan Authentik di belakang reverse proxy anda

Mendedahkan port 9000 kepada internet memang berfungsi, tetapi anda pasti mahukan 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 perubahan tersebut dengan docker compose up -d. Compose akan menggabungkan override tersebut secara automatik, jadi servis server akan mengekalkan semua tetapan daripada fail rasmi dan menerima label-label tersebut. Semak dengan curl -I https://auth.example.com/if/user/, yang sepatutnya memberikan respons HTTP/2 200. Ralat 404 page not found daripada Traefik bermakna kontena tersebut tidak berada dalam rangkaian proxy, dan Traefik tidak boleh menghalakan trafik ke kontena yang tidak dapat dicapainya.

Setelah nama hos berfungsi, ikat port yang didedahkan kepada 127.0.0.1 dalam fail override, supaya satu-satunya laluan masuk adalah melalui proksi tersebut.

Melindungi satu aplikasi dengan forward auth

Penyedia proksi Authentik mempunyai tiga mod, dan pemilihan mod yang salah boleh membuang masa selama satu jam. Proxy bermaksud outpost itu sendiri memajukan trafik ke aplikasi huluan. Forward auth (single application) bermaksud reverse proxy anda sendiri masih mengendalikan trafik dan hanya bertanya kepada Authentik sama ada permintaan tersebut telah disahkan. Forward auth (domain level) melindungi setiap aplikasi di bawah satu domain induk dengan satu penyedia, tetapi peraturan kebenaran bagi setiap aplikasi tidak dapat ditetapkan secara berasingan. Jika Traefik berada di hadapan, gunakan forward auth (single application). Jika anda mahu aplikasi sebenar untuk latihan, ruang kerja AFFiNE yang dihoskan sendiri ialah calon pertama yang baik kerana ia merupakan alat dalaman yang sepatutnya boleh dicapai daripada peranti anda sendiri dan tidak dari tempat lain. Alat untuk pasukan menjadikan keperluan ini lebih jelas: letakkan meja sokongan Chatwoot yang dihoskan sendiri di belakang penyedia yang sama supaya semua orang yang menjawab peti masuk hanya perlu log masuk sekali untuk hari tersebut, dan tidak perlu berkongsi satu lagi kata laluan.

Dalam antara muka web, buka Applications kemudian Providers, cipta Proxy Provider, pilih mod forward auth single application, dan tetapkan hos luaran kepada https://app.example.com. Cipta Application yang menghala ke penyedia tersebut. Kemudian buka Outposts, sunting authentik Embedded Outpost, dan masukkan aplikasi baharu tersebut ke dalam senarai aplikasi terpilihnya. 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 respons.

Takrifkan middleware sekali sahaja, pada kontena Authentik, dan rujuknya 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-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 dihantarnya ke hulu. Jika anda meninggalkannya, aplikasi tersebut masih dilindungi, tetapi ia tidak akan mengetahui siapa penggunanya, jadi sebarang sistem yang membaca X-authentik-username untuk log masuk automatik akan kekal dalam keadaan log keluar.

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 memberikan ralat 404, dan proses log masuk tidak akan selesai. Nilai priority yang lebih tinggi adalah perkara yang menyebabkan 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, log 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 pembekal identiti luaran secara serentak, serta eksport dan import realm sebagai laluan migrasi yang didokumentasikan. Sokongan komersial di sebaliknya adalah penting bagi sesetengah organisasi atas kertas. Kekurangannya ialah Keycloak tidak mempunyai proksi sendiri, jadi untuk melindungi aplikasi yang tidak menyokong OIDC (OpenID Connect), anda perlu menjalankan perisian seperti oauth2-proxy di sampingnya. Pembekal 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 menjadikan pemulihan boleh dilakukan: 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 fail dump tersebut dan .env bersama-sama. Fail dump sahaja tidak mencukupi, kerana kunci rahsia yang melindungi data sesi dan token berada di dalam .env.

Naik taraf dilakukan dengan menukar tag. Tetapkan AUTHENTIK_TAG di dalam .env kepada keluaran yang anda mahukan, kemudian jalankan docker compose pull diikuti dengan docker compose up -d. Baca nota keluaran terlebih dahulu, kerana Authentik menggunakan versi berasaskan tarikh dan sesetengah keluaran membawa migrasi yang memerlukan anda datang daripada versi sebelumnya. Ambil sandaran pangkalan data sebelum melakukan pull, bukan selepasnya.

FAQ

Adakah Authentik percuma untuk di-self-host?

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

Adakah saya perlukan Traefik untuk menggunakan Authentik?

Tidak. Forward auth berfungsi dengan nginx melalui auth_request dan dengan Caddy melalui forward_auth. Polanya sama dalam setiap kes: reverse proxy bertanya kepada Authentik tentang setiap permintaan, dan awalan laluan (path prefix) /outpost.goauthentik.io/ pada hostname yang dilindungi mesti menghalakan trafik ke Authentik dan bukannya ke aplikasi.

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

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

Berapa banyak RAM yang diperlukan oleh Authentik?

Minimum yang didokumentasikan ialah 2 teras CPU dan 2 GB RAM setakat Julai 2026, merangkumi PostgreSQL, pelayan dan worker secara bersama. Pada mesin 2 GB, worker adalah proses pertama yang dimatikan oleh kernel di bawah tekanan memori, dan simptomnya ialah tugas latar belakang serta e-mel keluar terhenti sementara halaman log masuk masih berfungsi. Berikan 4 GB jika pelayan yang sama turut menjalankan aplikasi yang anda lindungi.