Cara Sediakan Authentik SSO dengan Docker Compose

Satu log masuk untuk setiap aplikasi yang anda hoskan

Authentik ialah pelayan SSO (log masuk tunggal) yang dihos 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: mengarahkan proksi terbalik kepadanya dan meletakkan satu aplikasi sedia ada di belakang pengesahan hadapan.

Authentik disediakan sebagai tiga perkhidmatan dalam fail Compose tersebut: pangkalan data PostgreSQL, proses server dan proses worker. Bekas pelayan juga menjalankan outpost terbenam, iaitu komponen yang menjawab soalan "adakah permintaan ini telah dilog masuk?" untuk setiap aplikasi yang dilindungi. Versi 2026.5 ialah keluaran semasa pada 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 menggunakan memori selepas mesin tersebut berjalan selama sehari.

Keperluan sebelum bermula

Anda memerlukan Docker Engine dengan pemalam Compose v2. Anda boleh mengesahkannya dengan docker compose version. Jika arahan itu memaparkan ralat dan bukannya versi, pasang pemalam tersebut sebelum meneruskan. Asasnya 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. Authentik membina URL ubah hala berdasarkan nama hos yang digunakan oleh pelayar.

Jalankan tindanan tersebut sebagai pengguna biasa dalam kumpulan docker, bukan sebagai root. Keahlian kumpulan itu setara dengan akses root pada hos. Oleh itu, berikan keahlian tersebut kepada satu akaun deployment sahaja dan jangan berikan kepada orang lain, seperti yang diterangkan dalam 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 bekas, dengan postgresql melaporkan healthy dan server melaporkan worker serta running. Permulaan pertama menjalankan migrasi pangkalan data. Tunggu kira-kira seminit sebelum antara muka web mula memberikan respons.

Kedua-dua nilai yang dijana itu penting atas sebab yang berbeza. PG_PASS ialah kata laluan PostgreSQL dan mempunyai had maksimum 99 aksara. AUTHENTIK_SECRET_KEY menandatangani sesi dan token. Jika anda mengubahnya kemudian, semua pengguna akan dilog keluar dan setiap token API yang telah dikeluarkan akan menjadi tidak sah. Kekalkan .env pada mod 600 dan simpan satu salinan di tempat yang selamat. Pangkalan data yang dipulihkan tanpa kunci rahsia yang sepadan ialah pangkalan data yang tiada sesiapa boleh log masuk.

Fail Compose membaca kedua-dua nilai menggunakan bentuk ${PG_PASS:?database password required}. Oleh itu, Compose enggan bermula apabila fail tersebut tiada. Menjalankan docker compose up -d dari direktori yang salah akan mencetak required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required lalu berhenti. Mesej itu menunjukkan masalah laluan, bukan masalah konfigurasi.

Nilai persekitaran yang penting

Semua yang lain dimasukkan ke dalam fail .env yang sama. Authentik memetakan garis condong bawah berganda kepada kunci konfigurasi bersarang, jadi AUTHENTIK_EMAIL__HOST menetapkan email.host. Garis condong bawah tunggal diabaikan tanpa amaran. Ini ialah sebab paling biasa tetapan kelihatan tidak berfungsi.

• AUTHENTIK_BOOTSTRAP_PASSWORD menetapkan kata laluan pengguna akadmin terbina dalam pada permulaan pertama, supaya anda tidak perlu menaipnya dalam borang web awam. AUTHENTIK_BOOTSTRAP_EMAIL dan AUTHENTIK_BOOTSTRAP_TOKEN menetapkan alamat pengguna tersebut dan token API dengan cara yang sama.
• COMPOSE_PORT_HTTP dan COMPOSE_PORT_HTTPS mengalihkan 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 mel keluar. Tanpa nilai ini, Authentik cuba menggunakan localhost pada port 25, jadi mel penetapan semula kata laluan berakhir dengan ralat sambungan dalam log worker.
• AUTHENTIK_LOG_LEVEL=debug mengaktifkan butiran yang diperlukan semasa aliran log masuk bermasalah. Kembalikan nilainya kepada info selepas itu.
• AUTHENTIK_ERROR_REPORTING__ENABLED ialah false secara lalai. Tetapkannya kepada true hanya jika anda bersetuju menghantar laporan ranap kepada pihak huluan.

Ini ialah rahsia dalam fail teks biasa, jadi lindungi direktori tersebut seperti mana-mana stor kelayakan lain. Pengurus kata laluan seperti instans Vaultwarden yang dihoskan sendiri ialah tempat yang lebih sesuai 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 telah menetapkan AUTHENTIK_BOOTSTRAP_PASSWORD, langkah itu telah selesai dan anda terus ke halaman log masuk.

Cipta pengguna pentadbir biasa untuk diri anda di bawah Directory dan kemudian Users, tambah pengguna itu ke kumpulan authentik Admins, dan log masuk menggunakan akaun tersebut. Kekalkan akadmin sebagai akaun pemulihan kecemasan 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 identiti pengguna.

Letakkan Authentik di belakang proksi songsang

Menerbitkan port 9000 ke Internet berfungsi, tetapi anda memerlukan TLS (keselamatan lapisan pengangkutan) dan nama hos sebenar. Jika anda sudah menggunakan persediaan daripada Traefik sebagai proksi songsang untuk berbilang aplikasi Compose, sambungkan Authentik ke rangkaian proxy luaran yang sama menggunakan fail penggantian. Cipta docker-compose.override.yml di sebelah 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 docker compose up -d untuk menggunakannya. Compose menggabungkan fail penggantian secara automatik. Oleh itu, perkhidmatan server mengekalkan semua kandungan daripada fail rasmi dan memperoleh label tersebut. Semak menggunakan curl -I https://auth.example.com/if/user/. Perintah itu sepatutnya memberikan respons HTTP/2 200. Respons 404 page not found daripada Traefik bermaksud kontena itu tidak berada pada rangkaian proxy. Traefik tidak dapat menghalakan trafik ke kontena yang tidak dapat dicapainya.

Selepas nama hos berfungsi, ikat port yang diterbitkan kepada 127.0.0.1 dalam fail penggantian. Dengan itu, satu-satunya cara untuk mengakses perkhidmatan adalah melalui proksi.

Lindungi satu aplikasi dengan forward auth

Proxy provider Authentik mempunyai tiga mod, dan pemilihan mod yang salah boleh membazirkan masa sehingga sejam. Proxy bermaksud outpost itu sendiri memajukan trafik ke aplikasi huluan. Forward auth (single application) bermaksud reverse proxy anda sendiri masih mengendalikan trafik dan hanya meminta Authentik menyemak sama ada permintaan itu telah disahkan. Forward auth (domain level) melindungi setiap aplikasi di bawah satu domain induk menggunakan satu provider, tetapi peraturan kebenaran bagi setiap aplikasi tidak dapat ditetapkan secara berasingan. Dengan Traefik di hadapan, gunakan forward auth (single application).

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 merujuk provider itu. Kemudian buka Outposts, edit authentik Embedded Outpost, dan pindahkan aplikasi baharu ke dalam senarai selected applications. Outpost hanya memberikan respons untuk aplikasi yang ditetapkan kepadanya. Jika langkah terakhir ini dilangkau, provider yang dikonfigurasikan dengan betul tetap tidak memberikan respons.

Takrifkan middleware sekali sahaja pada kontena Authentik, kemudian rujuk middleware itu 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 yang disalin oleh Traefik daripada respons Authentik ke dalam permintaan yang dihantar kepada aplikasi huluan. Jika bahagian ini ditinggalkan, aplikasi masih dilindungi, tetapi aplikasi itu tidak mengetahui identiti pengguna. Oleh itu, apa-apa yang membaca X-authentik-username untuk log masuk automatik akan kekal dalam keadaan belum log masuk.

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 ialah bahagian yang sering ditinggalkan. Selepas log masuk, Authentik menghantar pelayar kembali ke laluan di bawah /outpost.goauthentik.io/ pada nama hos aplikasi, bukan pada auth.example.com. Tanpa router yang menghantar awalan laluan itu kepada servis Authentik, permintaan tersebut sampai ke aplikasi anda. Aplikasi itu membalas dengan 404, lalu proses log masuk tidak selesai. Nilai priority yang lebih tinggi menyebabkan peraturan laluan khusus mengatasi peraturan Host() biasa pada domain yang sama.

Uji konfigurasi ini dalam tetingkap pelayar peribadi. Anda sepatutnya dihantar ke auth.example.com, log masuk, kemudian kembali ke aplikasi. docker compose logs -f server pada bahagian Authentik mencetak satu peristiwa kebenaran bagi setiap percubaan. Ini menunjukkan sama ada permintaan tersebut sampai kepada Authentik atau tidak.

Kegagalan yang akan anda hadapi

Gelung ubah hala berterusan antara aplikasi dengan halaman log masuk. Hos luaran pada pembekal tidak sepadan dengan hos yang digunakan oleh pelayar, biasanya http:// pada pembekal berbanding https:// dalam bar alamat. Kuki sesi kemudian ditetapkan untuk asal yang berbeza, maka setiap permintaan kembali kelihatan seperti permintaan tanpa nama yang baharu. Betulkan hos luaran dan padamkan kuki untuk kedua-dua domain sebelum menguji semula.

404 pada /outpost.goauthentik.io/start. Penghala outpost tiada, atau keutamaannya lebih rendah daripada penghala tangkap semua untuk hos tersebut.

Aplikasi dimuatkan tanpa meminta log masuk. Label middlewares merujuk kepada middleware yang tidak wujud. Traefik tidak memberikan amaran tentang perkara ini, jadi kesilapan taip dalam authentik@docker bermakna tiada middleware dijalankan. Buka papan pemuka Traefik dan sahkan bahawa penghala menyenaraikan middleware tersebut.

403 daripada Authentik selepas log masuk berjaya. Pengguna telah disahkan tetapi tidak dibenarkan: aplikasi mempunyai pengikatan dasar atau keperluan kumpulan yang tidak dipenuhi oleh pengguna ini. Log Events dalam antara muka pentadbiran menyatakan dasar yang menafikan akses.

Apabila Keycloak lebih sesuai

Keycloak ialah projek yang lebih lama, disokong oleh Red Hat, dan merupakan pilihan yang lebih kukuh untuk kerja identiti perusahaan klasik: persekutuan SAML yang kompleks, pengantara log masuk daripada beberapa pembekal identiti luaran serentak, serta pengeksportan dan pengimportan realm sebagai laluan migrasi yang didokumenkan. Sokongan komersial di sebaliknya penting bagi sesetengah organisasi dari sudut rasmi. Pertukarannya ialah Keycloak tidak mempunyai proksi sendiri. Oleh itu, untuk melindungi aplikasi yang tidak menyokong OIDC (OpenID Connect), anda perlu menjalankan sesuatu seperti oauth2-proxy bersamanya. Penyedia proksi terbina dalam Authentik menyediakan fungsi itu dan telah disepadukan, sebab itu kebanyakan pengguna yang mengehos sendiri pelbagai aplikasi memilihnya.

Sandaran dan peningkatan

Tiga perkara membolehkan pemulihan 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 dump itu bersama-sama dengan .env. Dump sahaja tidak mencukupi kerana kunci rahsia yang melindungi data sesi dan token disimpan dalam .env.

Peningkatan ialah perubahan tag. Tetapkan AUTHENTIK_TAG dalam .env kepada keluaran yang dikehendaki, 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 mengandungi migrasi yang menjangkakan anda menaik taraf daripada keluaran sebelumnya. Ambil 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: pembekal proksi, pengesahan hadapan, OIDC (OpenID Connect), SAML dan enjin aliran kerja. Tahap perusahaan berbayar menambah sokongan serta beberapa ciri perusahaan, tetapi tiada apa-apa dalam panduan ini memerlukan lesen.

Adakah saya memerlukan Traefik untuk menggunakan Authentik?

Tidak. Pengesahan hadapan berfungsi dengan nginx melalui auth_request dan dengan Caddy melalui forward_auth. Coraknya sama dalam setiap kes: proksi terbalik meminta Authentik menyemak setiap permintaan, dan awalan laluan /outpost.goauthentik.io/ pada hos yang dilindungi mesti dihalakan ke Authentik dan bukannya ke aplikasi.

Mengapakah aplikasi yang dilindungi berulang-alik antara log masuk dan ralat tanpa henti?

Hos luaran yang dikonfigurasikan pada pembekal proksi tidak sepadan dengan URL yang digunakan oleh pelayar, biasanya http berbanding https. Kuki sesi dikeluarkan untuk satu asal dan dibaca pada asal yang lain, maka Authentik menganggap setiap permintaan sebagai permintaan tanpa nama. Betulkan hos luaran, kemudian padamkan kuki untuk kedua-dua nama hos sebelum menguji semula.

Berapa banyak RAM yang diperlukan oleh Authentik?

Minimum yang didokumenkan ialah 2 teras CPU dan 2 GB RAM setakat Julai 2026, untuk PostgreSQL, pelayan dan pekerja secara keseluruhan. Pada mesin dengan 2 GB RAM, pekerja ialah proses pertama yang dihentikan oleh kernel apabila tekanan memori berlaku. Kesannya ialah tugas latar belakang dan e-mel keluar berhenti, manakala halaman log masuk masih berfungsi. Peruntukkan 4 GB jika pelayan yang sama turut menjalankan aplikasi yang anda lindungi.