Jinsi ya kusakinisha Authentik SSO kwa Docker Compose

Kuingia mara moja kwa kila programu unayohost

Authentik ni seva ya SSO (single sign-on) inayojihostiwa: watumiaji wako huingia mara moja, kisha kila programu iliyo nyuma yake hukubali session hiyo badala ya kuomba password yake. Usakinishaji unatumia faili rasmi ya Docker Compose na secrets mbili zilizotengenezwa. Sehemu inayohitaji uamuzi wa makini huja baadaye: kuelekeza reverse proxy kwake, na kuweka programu moja iliyopo nyuma ya forward auth.

Authentik husambazwa kama services tatu katika faili hiyo ya Compose: database ya PostgreSQL, mchakato wa server, na mchakato wa worker. Container ya server pia huendesha outpost iliyopachikwa, ambayo ni component inayojibu swali la “je, ombi hili limeingia?” kwa kila programu iliyolindwa. Toleo 2026.8.5 ndilo release la sasa kufikia 25 October 2026. Lilichapishwa tarehe 21 October 2026 kama patch ya hivi karibuni ya mfululizo wa 2026.8, ulioanza na 2026.8.0 tarehe 18 August, na linachukua nafasi ya 2026.8.4 ya tarehe 14 October kama image tag chaguo-msingi katika faili rasmi ya Compose. Mradi unapendekeza host yenye angalau cores 2 za CPU na 2 GB za RAM. Chukulia hiyo kuwa kiwango cha chini. PostgreSQL na worker zote hutumia memory baada ya mashine kuwa imeendelea kufanya kazi kwa siku moja.

Unachohitaji kabla ya kuanza

Unahitaji Docker Engine ikiwa na Compose v2 plugin, ambayo unaweza kuithibitisha kwa docker compose version. Ikiwa amri hiyo italeta kosa badala ya toleo, sakinisha plugin hiyo kabla ya kuendelea; misingi imeelezewa katika kuendesha programu kwa kutumia Docker Compose kwenye VPS. Pia unahitaji DNS A record inayoelekeza kwenye seva, auth.example.com katika mifano hapa chini, kwa sababu Authentik hutengeneza URL zake za kuelekeza (redirect URLs) kutoka kwa hostname iliyotumiwa na kivinjari.

Endesha stack hii kama mtumiaji wa kawaida aliye katika kundi la docker badala ya kutumia root. Uanachama wa kundi hilo ni sawa na kuwa root kwenye seva, kwa hivyo mpe mtumiaji mmoja tu wa deploy uwezo huo na si mwingine yeyote, kulingana na mwongozo wa akaunti za watumiaji zenye upendeleo mdogo kwenye VPS.

Sakinisha kwa kutumia faili rasmi ya Compose

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 inapaswa kuorodhesha kontena tatu, zote zikiwa zinaendelea, huku postgresql ikiripoti healthy baada ya ukaguzi wake kufaulu. Mwanzo wa kwanza huendesha uhamishaji wa hifadhidata, kwa hiyo subiri takriban dakika moja kabla kiolesura cha wavuti kijibu.

Thamani zote mbili zinazozalishwa ni muhimu, lakini kwa sababu tofauti. PG_PASS ni nenosiri la PostgreSQL. Nyaraka za usakinishaji za Authentik zinasema kuwa manenosiri yenye urefu unaozidi herufi 99 hayatumiki, kwa hiyo nenosiri utakalochagua mwenyewe liwe na urefu usiozidi hapo; lile linalozalishwa ni fupi zaidi. AUTHENTIK_SECRET_KEY ni ufunguo ambao Authentik hutumia kusaini cookies, na nyaraka zake za usanidi zinasema kuwa kuubadilisha hubatilisha sessions zinazotumika. Kwa hiyo, ukiweka ufunguo mpya baadaye, kila mtumiaji aliyeingia atatolewa kwenye akaunti. Weka .env katika mode 600 na uhifadhi nakala yake mahali salama pamoja na backups zako, ili restore irudishe mfumo ukitumia ufunguo uleule uliokuwa unatumika.

Faili ya Compose inaweka thamani zote mbili kuwa za lazima kwa kutumia muundo wa ${VAR:?message}: ${PG_PASS:?database password required} kwenye huduma ya PostgreSQL na ${AUTHENTIK_SECRET_KEY:?secret key required} kwenye server na worker. Hii inamaanisha kuwa Compose inakataa kuanza faili inapokosekana. Kuendesha docker compose up -d ukiwa kwenye directory isiyo sahihi huchapisha mstari kama required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required na kusimama. Ujumbe huo unaonyesha tatizo la path, si tatizo la config.

Thamani za mazingira zilizo muhimu

Kila kitu kingine huwekwa kwenye faili hiyo hiyo ya .env. Authentik hubadilisha alama mbili za underscore kuwa ufunguo wa usanidi uliopachikwa, kwa hiyo AUTHENTIK_EMAIL__HOST huweka email.host. Alama moja ya underscore haibadilishwi kuwa ufunguo uliopachikwa. Hii ndiyo sababu ya kawaida zaidi inayofanya mpangilio uonekane hautekelezwi.

• AUTHENTIK_BOOTSTRAP_PASSWORD huweka nenosiri la mtumiaji wa ndani wa akadmin wakati wa kuanza kwa mara ya kwanza, kwa hiyo huwezi kulazimika kuliandika kwenye fomu ya wavuti iliyo wazi kwa umma. AUTHENTIK_BOOTSTRAP_EMAIL na AUTHENTIK_BOOTSTRAP_TOKEN huweka anwani ya mtumiaji huyo na tokeni ya API kwa njia hiyo hiyo.
• COMPOSE_PORT_HTTP na COMPOSE_PORT_HTTPS huhamisha port zinazoonekana kwa umma kutoka kwenye chaguo-msingi za 9000 na 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS na AUTHENTIK_EMAIL__FROM husanidi barua zinazotumwa nje. Bila hizo, Authentik hujaribu localhost kwenye port 25, kwa hiyo barua za kuweka upya nenosiri huishia kuwa kosa la muunganisho kwenye logi ya worker.
• AUTHENTIK_LOG_LEVEL=debug huwasha maelezo unayohitaji wakati flow ya kuingia haifanyi kazi ipasavyo. Irudishe kwenye info baadaye.
• AUTHENTIK_ERROR_REPORTING__ENABLED ni false kwa chaguo-msingi. Iweke kuwa true tu ikiwa uko tayari kutuma ripoti za kuanguka kwa timu ya juu.

Hizi ni secrets zilizo kwenye faili isiyosimbwa, kwa hiyo ichukulie directory hiyo kama unavyoshughulikia hifadhi nyingine yoyote ya credentials. Password manager kama instance ya Vaultwarden inayojiendesha yenyewe ni mahali bora pa kuweka nakala ya urejeshaji kuliko kuiandika kwenye note kwenye laptop yako.

Kuingia kwa mara ya kwanza na akaunti ya msimamizi

Fungua http://SERVER_IP:9000 kwenye kivinjari. Authentik itaonyesha mchakato wake wa awali wa usanidi na kukuomba uweke nenosiri la mtumiaji chaguo-msingi akadmin. Ikiwa tayari uliweka AUTHENTIK_BOOTSTRAP_PASSWORD, hatua hiyo imekamilika na utaelekezwa moja kwa moja kwenye ukurasa wa kuingia.

Jitengenezee mtumiaji wa kawaida mwenye haki za msimamizi katika Directory kisha Users, umwongeze kwenye kikundi cha authentik Admins, na uingie kwa kutumia akaunti hiyo. Acha akadmin iwe akaunti ya dharura yenye nenosiri refu lililohifadhiwa nje ya mfumo. Ikiwa flow au stage iliyoharibika itakufungia nje, docker compose run --rm server create_recovery_key 10 akadmin, inayoendeshwa kutoka /opt/authentik, huchapisha kiungo kinachokuingiza moja kwa moja kama akadmin. Mtu yeyote mwenye kiungo hicho atakuwa na ufikiaji huo huo, kwa hiyo kichukulie kama nenosiri. Kazi za kila siku kwa kutumia akaunti ya ndani inayoshirikiwa huharibu audit log, kwa sababu kila tukio husema akadmin na hakuna kinachoonyesha ni nani. Hoja hiyo inatumika pia baada ya Authentik: kitu kama harness ya OneCLI inayojihostisha na kumpa kila mtu agent yake huacha mfuatano unaosomeka tu ikiwa utambulisho unaofika humo ni wa mtu mmoja, badala ya login inayoshirikiwa na timu nzima.

Weka Authentik nyuma ya reverse proxy

Kuchapisha port 9000 kwenye Internet hufanya kazi, lakini unataka TLS (transport layer security) na hostname halisi. Ikiwa tayari unatumia usanidi kutoka Traefik kama reverse proxy kwa Compose apps nyingi, iunganishe Authentik kwenye proxy network ileile ya nje kwa kutumia override file. Unda docker-compose.override.yml karibu na 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

Itumie kwa docker compose up -d. Compose huunganisha override automatically, kwa hiyo service ya server huhifadhi kila kitu kutoka kwenye official file na kuongezewa labels. Thibitisha kwa curl -I https://auth.example.com/if/user/, ambayo inapaswa kujibu HTTP/2 200. 404 page not found kutoka Traefik inamaanisha hakuna router iliyolingana na ombi. Hakikisha labels zilifika kwenye container, kwamba rule ya Host() inalingana kikamilifu na hostname, na kwamba ombi lilifika kwenye HTTPS entry point ambayo router inasikiliza.

Hostname ikishafanya kazi, funga ports zilizochapishwa kwenye 127.0.0.1 katika override, ili njia pekee ya kuingia iwe kupitia proxy.

Linda programu moja kwa kutumia forward auth

Proxy provider ya Authentik ina modes tatu, na kuchagua isiyo sahihi kunaweza kupoteza saa moja. Proxy inamaanisha outpost yenyewe inapeleka traffic kwenye upstream app. Forward auth (single application) inamaanisha reverse proxy yako bado inahamisha traffic, na inauliza Authentik pekee ikiwa request imeingia. Forward auth (domain level) hulinda kila app iliyo chini ya parent domain moja kwa kutumia provider mmoja, lakini kwa gharama ya kukosa authorization rules za kila application. Ukiwa na Traefik mbele, tumia forward auth (single application). Ikiwa unataka app halisi ya kufanyia mazoezi, kitu kama workspace ya AFFiNE inayojihostiwa ni mgombea mzuri wa kwanza, kwa sababu ni aina ya internal tool unayotaka ipatikane kutoka kwenye vifaa vyako pekee na isiweze kufikiwa kwingine. Team tool huonyesha umuhimu huo zaidi: weka support desk ya Chatwoot inayojihostiwa nyuma ya provider huyo huyo, ili kila anayejibu inbox aingie mara moja kwa siku badala ya kusambaza password nyingine.

Kwenye web interface, fungua Applications kisha Providers, tengeneza Proxy Provider, chagua mode ya forward auth single application, na weka external host kuwa https://app.example.com. Tengeneza Application inayoelekeza kwenye provider huyo. Kisha fungua Outposts, hariri authentik Embedded Outpost, na uhamishe application mpya kwenye selected applications zake. Outpost hujibu tu kwa applications ilizopewa, kwa hiyo kuruka hatua hiyo ya mwisho ndiko kunakofanya provider iliyosanidiwa vizuri bado isirudishe jibu.

Define middleware mara moja, kwenye Authentik container, na uireference kutoka kwa kila app iliyolindwa:

      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 ni orodha ya headers ambazo Traefik hunakili kutoka kwenye jibu la Authentik na kuziweka kwenye request inayotuma upstream. Ukiiacha, app bado inalindwa, lakini haitambui user ni nani, kwa hiyo kitu chochote kinachosoma X-authentik-username kwa ajili ya automatic login hubaki kikiwa hakijaingia. Pengo hilo huonekana zaidi mbele ya app yenye sign-in yake, kama workout tracker ya openGym inayojihostiwa na passkey login yake, ambapo headers hizo hutofautisha prompt moja na prompts mbili kwa ukurasa huo huo.

App iliyolindwa yenyewe inahitaji routers mbili, si moja:

    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 ya pili ndiyo sehemu ambayo watu wengi huiacha. Baada ya kuingia, Authentik hurudisha browser kwenye path iliyo chini ya /outpost.goauthentik.io/ kwenye hostname ya app, si kwenye auth.example.com. Bila router inayotuma path prefix hiyo kwenye Authentik service, request hufika kwenye app yako, ambayo hurudisha 404, na login haikamiliki. Thamani kubwa zaidi ya priority ndiyo inayofanya specific path rule ishinde dhidi ya plain Host() rule kwenye domain hiyo hiyo.

Ijaribu kwenye private browser window. Unapaswa kutumwa kwenye auth.example.com, uingie, kisha urudi kwenye app. docker compose logs -f server upande wa Authentik huchapisha authorization event kwa kila jaribio, hivyo inakuonyesha ikiwa request ilifika Authentik hata kidogo.

Hitilafu utakazokutana nazo kihalisi

Mzunguko usioisha wa kuelekezwa upya (redirect loop) kati ya programu na ukurasa wa kuingia. Host ya nje kwenye mtoa huduma hailingani na ile inayotumiwa na kivinjari, kwa kawaida http:// kwenye mtoa huduma dhidi ya https:// kwenye upau wa anwani. Cookie ya kikao huwekwa kwa ajili ya asili (origin) tofauti, hivyo kila safari ya kurudi huonekana kama ombi jipya la mtu asiyejulikana. Rekebisha host ya nje na ufute cookies kwa ajili ya domains zote mbili kabla ya kujaribu tena.

404 kwenye /outpost.goauthentik.io/start. Router ya outpost haipo, au kipaumbele chake ni cha chini kuliko router ya jumla (catch-all) kwa host hiyo.

Programu inapakia bila kuomba kuingia. Lebo ya middlewares inataja middleware isiyokuwepo. Traefik haitoi onyo kuhusu hilo, kwa hivyo kosa la uchapaji kwenye authentik@docker linamaanisha kuwa hakuna middleware inayofanya kazi. Fungua dashibodi ya Traefik na uthibitishe kuwa router inaorodhesha middleware hiyo.

403 kutoka Authentik baada ya kuingia kwa mafanikio. Mtumiaji amethibitishwa lakini hana idhini: programu ina fungamano la sera (policy binding), au hitaji la kikundi, ambalo mtumiaji huyu halitimizi. Kumbukumbu ya Events katika kiolesura cha admin inataja sera iliyokataa ufikiaji huo.

Keycloak inapofaa zaidi

Keycloak ni mradi wa zamani zaidi unaoungwa mkono na Red Hat. Ni chaguo bora zaidi kwa kazi za kawaida za utambulisho wa biashara: federation kubwa ya SAML, kuunganisha login kutoka kwa identity provider kadhaa za nje kwa wakati mmoja, na kutumia realm export na import kama njia iliyoandikwa ya migration. Kwa baadhi ya mashirika, uwepo wa support ya kibiashara ni muhimu kwenye karatasi. Hasara yake ni kwamba Keycloak haina proxy yake. Kwa hiyo, ili kulinda app inayotumia OIDC (OpenID Connect) wala SAML, lazima uendeshe kitu kama oauth2-proxy kando yake. Authentik ina built-in proxy provider iliyounganishwa tayari. Ndiyo sababu self-hosters wengi wenye mkusanyiko mchanganyiko wa apps huishia kutumia Authentik.

Hifadhi rudufu na masasisho

Vitu vitatu hufanya urejeshaji uwezekane: database ya PostgreSQL, saraka ya ./data, na .env.

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

Hifadhi dump hiyo pamoja na .env. Dump hiyo haina nakala ya AUTHENTIK_SECRET_KEY, na kurejesha kwa kutumia key tofauti hubatilisha kila session inayotumika. Kwa hiyo, kuhifadhi key ya awali kunamaanisha kuwa seva iliyorejeshwa itaendelea kama ilivyokuwa.

Masasisho ni mabadiliko ya tag. Weka AUTHENTIK_TAG ndani ya .env iwe release unayotaka, kisha endesha docker compose pull ikifuatiwa na docker compose up -d. Ikiwa hujawahi kuweka AUTHENTIK_TAG, version hutoka kwenye default iliyoandikwa ndani ya compose.yml yenyewe. Hivyo, kupakua nakala mpya ya faili hiyo ndilo sasisho, na hiyo ndiyo njia iliyoelezwa katika nyaraka rasmi za kusasisha. Soma release notes kwanza. Authentik hutumia versions zinazotegemea tarehe. Kufikia October 2026, nyaraka zake zinasema kuwa masasisho lazima yafuate mfuatano wa major releases: hamia kwenye patch ya hivi karibuni ya series unayotumia, kisha pitia kila series inayofuata kwa mpangilio bila kuruka yoyote. Authentik haiungi mkono downgrading, kwa hiyo tengeneza database dump kabla ya pull, si baada yake.

FAQ

Je, Authentik ni bure kwa kujiendeshea mwenyewe?

Toleo la open source ni bure na linajumuisha kila kitu kilichoelezwa hapo juu: proxy provider, forward auth, OIDC (OpenID Connect), SAML na flows engine. Kiwango cha enterprise cha kulipia huongeza support na baadhi ya vipengele vya enterprise, lakini hakuna kinachohitaji leseni hapa.

Je, ninahitaji Traefik ili kutumia Authentik?

Hapana. Forward auth hufanya kazi na nginx kupitia auth_request na Caddy kupitia forward_auth. Muundo ni uleule katika kila hali: reverse proxy huuliza Authentik kuhusu kila ombi, na path prefix /outpost.goauthentik.io/ kwenye hostname iliyolindwa lazima ipelekwe kwa Authentik badala ya app.

Kwa nini app yangu iliyolindwa hurudi kati ya ukurasa wa kuingia na hitilafu bila mwisho?

Host ya nje iliyosanidiwa kwenye proxy provider hailingani na URL inayotumiwa na browser, mara nyingi http dhidi ya https. Session cookie hutolewa kwa origin moja na kusomwa kwenye nyingine, hivyo Authentik huona ombi lisilo na mtumiaji aliyeingia kila mara. Rekebisha host ya nje, kisha futa cookies za hostname zote mbili kabla ya kujaribu tena.

Authentik inahitaji RAM kiasi gani?

Kiwango cha chini kilichoandikwa ni cores 2 za CPU na 2 GB za RAM kufikia October 2026, kikijumuisha PostgreSQL, server na worker kwa pamoja. Kwenye mashine yenye 2 GB, shinikizo la memory linaweza kuamsha OOM killer ya kernel, ambayo husitisha process yenye badness score ya juu zaidi: takriban sehemu ya memory iliyoruhusiwa inayotumiwa na process hiyo, pamoja na oom_score_adj yake. Iwapo huyo ni worker, dalili huwa ni kusimama kwa background tasks na email zinazotumwa nje, huku ukurasa wa kuingia ukiendelea kufanya kazi. Ipe 4 GB ikiwa server hiyo hiyo pia inaendesha apps unazolinda.