Jinsi ya kusakinisha Authentik SSO kwa Docker Compose

Ingia mara moja kwa kila programu unayohifadhi

Authentik ni seva ya SSO (single sign-on) inayojiendesha: watumiaji wako huingia mara moja, na kila programu iliyo nyuma yake hukubali kikao hicho badala ya kuomba nenosiri lake. Usakinishaji hutumia faili rasmi ya Docker Compose na siri mbili zilizozalishwa. Sehemu inayohitaji umakini zaidi inakuja baadaye: kuelekeza reverse proxy kwake, na kuweka programu moja iliyopo nyuma ya forward auth.

Authentik husafirishwa kama huduma tatu katika faili hiyo ya Compose: database ya PostgreSQL, mchakato wa server, na mchakato wa worker. Kontena la seva pia huendesha outpost iliyopachikwa, ambayo ni sehemu inayojibu "je, ombi hili limeingia?" kwa kila programu iliyolindwa. Toleo la 2026.5 ndilo toleo la sasa kufikia Julai 2026, na mradi huu unahitaji seva yenye angalau CPU 2 na 2 GB ya RAM. Ichukulie hiyo kama kiwango cha chini. PostgreSQL na worker wote huhifadhi kumbukumbu mara tu seva inapokuwa imewashwa 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, huku postgresql ikiripoti healthy na server na worker ikiripoti running. Uanzishaji wa kwanza huendesha migrates za hifadhidata, kwa hivyo ipe dakika moja kabla ya kiolesura cha wavuti kuanza kujibu.

Thamani zote mbili zilizozalishwa ni muhimu, kwa sababu tofauti. PG_PASS ni nenosiri la PostgreSQL, na lina ukomo wa juu wa vibambo 99. AUTHENTIK_SECRET_KEY husaini vikao na tokeni, kwa hivyo kuibadilisha baadaye kutawatoa watumiaji wote nje na kubatilisha kila tokeni ya API uliyotoa. Weka .env katika mode 600 na uweke nakala mahali salama, kwa sababu hifadhidata iliyorejeshwa bila ufunguo wake wa siri unaolingana ni hifadhidata ambayo hakuna mtu anayeweza kuingia.

Faili ya Compose inasoma thamani zote mbili kwa kutumia fomu ya ${PG_PASS:?database password required}, ambayo inamaanisha Compose inakataa kuanza wakati faili haipo. Kuendesha docker compose up -d kutoka saraka isiyo sahihi huchapisha required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required na kusimama. Ujumbe huo ni tatizo la njia (path), si tatizo la usanidi.

Vigezo vya mazingira vinavyohitajika

Kila kitu kingine huwekwa kwenye faili ileile ya .env. Authentik hubadilisha alama ya mstari wa chini mara mbili (double underscore) kuwa ufunguo wa usanidi wa ndani (nested configuration key), kwa hivyo AUTHENTIK_EMAIL__HOST huweka email.host. Alama ya mstari wa chini mmoja hupuuzwa bila onyo lolote, na hii ndiyo sababu kuu inayofanya mpangilio kuonekana haufanyi kazi.

• AUTHENTIK_BOOTSTRAP_PASSWORD huweka nenosiri la mtumiaji wa ndani wa akadmin wakati wa kuanza kwa mara ya kwanza, ili usilazimike kuliandika kwenye fomu ya wavuti ya umma. AUTHENTIK_BOOTSTRAP_EMAIL na AUTHENTIK_BOOTSTRAP_TOKEN huweka anwani ya mtumiaji huyo na token ya API kwa njia hiyo hiyo.
• COMPOSE_PORT_HTTP na COMPOSE_PORT_HTTPS hubadilisha bandari (ports) zilizochapishwa kutoka zile za awali 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 utumaji wa barua pepe. Bila hizi, Authentik hujaribu localhost kwenye port 25, hivyo barua pepe za kuweka upya nenosiri huishia kuwa hitilafu ya muunganisho kwenye log ya worker.
• AUTHENTIK_LOG_LEVEL=debug huwasha maelezo ya kina unayohitaji wakati mtiririko wa kuingia (login flow) haufanyi kazi vizuri. Irudishe kwenye info baada ya kumaliza.
• AUTHENTIK_ERROR_REPORTING__ENABLED ni false kwa chaguomsingi. Iweke kwenye true tu ikiwa uko tayari kutuma ripoti za hitilafu (crash reports) kwa watengenezaji.

Hizi ni siri zilizohifadhiwa kwenye faili ya maandishi ya kawaida, kwa hivyo lishughulikie saraka (directory) hiyo kama unavyoshughulikia hifadhi nyingine yoyote ya vitambulisho. Meneja wa nenosiri kama vile instance ya Vaultwarden unayojiendeshea mwenyewe ni mahali bora zaidi pa kuhifadhi nakala ya kurejeshea (recovery copy) kuliko dokezo kwenye kompyuta yako ndogo.

Kuingia kwa mara ya kwanza na akaunti ya admin

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

Unda mtumiaji wa kawaida wa admin kwa matumizi yako kupitia Directory kisha Users, mwongeze kwenye kikundi cha authentik Admins, halafu ingia kwa kutumia akaunti hiyo. Acha akadmin kama akaunti ya break-glass yenye nenosiri refu lililohifadhiwa nje ya mtandao. Kazi za kila siku chini ya akaunti ya built-in inayoshirikiwa huharibu audit log, kwa sababu kila tukio linasema akadmin na hakuna kinachoonyesha ni nani aliyelifanya. Hoja hiyo inaendelea pia upande wa Authentik: kitu kama harness ya OneCLI inayojihostisha na kumpa kila mtu agent wake huacha trail inayosomeka tu ikiwa utambulisho unaofika humo ni wa mtu mmoja, badala ya login inayoshirikiwa na timu nzima.

Weka Authentik nyuma ya reverse proxy yako

Kufungua port 9000 kwenye Internet kunafanya kazi, lakini unahitaji TLS (transport layer security) na hostname halisi. Ikiwa tayari unaendesha usanidi kutoka Traefik kama reverse proxy kwa programu nyingi za Compose, unganisha Authentik kwenye mtandao uleule wa nje wa proxy kwa kutumia faili ya override. Unda docker-compose.override.yml kando ya 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

Tekeleza kwa kutumia docker compose up -d. Compose huunganisha override hiyo kiotomatiki, kwa hivyo huduma ya server huhifadhi kila kitu kutoka kwenye faili rasmi na kupata lebo hizo. Hakikisha kwa kutumia curl -I https://auth.example.com/if/user/, ambayo inapaswa kujibu HTTP/2 200. 404 page not found kutoka Traefik inamaanisha kuwa container haipo kwenye mtandao wa proxy, na Traefik haiwezi kuelekeza trafiki kwenye container ambayo haiwezi kuifikia.

Mara tu hostname inapofanya kazi, funga port zilizochapishwa kwenye 127.0.0.1 ndani ya override, ili njia pekee ya kuingia iwe kupitia proxy.

Linda programu moja kwa kutumia forward auth

Provider wa proxy wa Authentik una modes tatu, na kuchagua mode isiyofaa kunaweza kupoteza saa moja. Proxy inamaanisha outpost yenyewe inapeleka traffic kwenye upstream app. Forward auth (single application) inamaanisha reverse proxy yako bado inapeleka traffic, na inauliza Authentik pekee ikiwa request imeingia kwa usahihi. 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. Ikiwa Traefik iko mbele, unahitaji forward auth (single application). Ikiwa unataka app halisi ya kufanyia mazoezi, kitu kama workspace ya AFFiNE inayojihostiwa ni chaguo zuri la kwanza, kwa sababu ni aina ya internal tool unayotaka ipatikane kutoka kwenye vifaa vyako mwenyewe na isiweze kufikiwa kwingine. Team tool huonyesha sababu hii kwa uwazi zaidi: weka desk ya usaidizi ya Chatwoot inayojihostiwa nyuma ya provider huyo huyo, na kila mtu anayejibu inbox ataingia mara moja kwa siku hiyo badala ya kushirikiana tena password nyingine.

Katika kiolesura cha wavuti, fungua Applications kisha Providers, tengeneza Proxy Provider, chagua njia ya forward auth single application, na uweke external host kuwa https://app.example.com. Tengeneza Application inayoelekeza kwenye mtoa huduma huyo. Kisha fungua Outposts, hariri authentik Embedded Outpost, na uweke programu hiyo mpya kwenye orodha ya selected applications. Outpost hujibu tu kwa programu ilizopewa, kwa hivyo kuruka hatua hiyo ya mwisho ndiyo sababu mtoa huduma aliyesanidiwa kwa usahihi bado anaweza asirudishe chochote.

Fafanua middleware mara moja, kwenye container ya Authentik, na uirejelee kutoka kwa kila programu inayolindwa:

      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 ni orodha ya headers ambazo Traefik hunakili kutoka kwa jibu la Authentik kwenda kwenye ombi inalotuma upstream. Ukiiondoa, programu bado itakuwa imelindwa, lakini haitafahamu mtumiaji ni nani, kwa hivyo chochote kinachosoma X-authentik-username kwa ajili ya kuingia kiotomatiki kitasalia kikiwa hakijaingia.

Programu inayolindwa 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 kila mtu husahau. Baada ya kuingia, Authentik hutuma kivinjari kurudi kwenye njia iliyo chini ya /outpost.goauthentik.io/ kwenye hostname ya programu, si kwenye auth.example.com. Bila router inayotuma prefix hiyo ya njia kwenye huduma ya Authentik, ombi hufika kwenye programu yako, ambayo hujibu 404, na mchakato wa kuingia haukamiliki. priority ya juu zaidi ndiyo inayofanya sheria ya njia mahususi ishinde sheria ya kawaida ya Host() kwenye domain hiyo hiyo.

Ijaribu katika dirisha la kivinjari la faragha (private browser window). Unapaswa kuelekezwa kwenye auth.example.com, uingie, na urudi kwenye programu. docker compose logs -f server kwa upande wa Authentik huchapisha tukio la uthibitisho kwa kila jaribio, jambo linalokuambia kama ombi lilifika kwa Authentik au la.

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.

Wakati Keycloak inapofaa zaidi

Keycloak ni mradi wa zamani zaidi, unaoungwa mkono na Red Hat, na ndilo chaguo imara zaidi kwa kazi za utambulisho wa kibiashara (enterprise identity): ushirikiano mkubwa wa SAML, kusimamia maingizo kutoka kwa watoa huduma wengi wa utambulisho kwa wakati mmoja, na uwezo wa kusafirisha (export) na kuingiza (import) realm kama njia iliyoandikwa ya kuhama mifumo. Usaidizi wa kibiashara nyuma yake ni muhimu kwa mashirika fulani kulingana na nyaraka zao. Hasara yake ni kwamba Keycloak haina proxy yake yenyewe, hivyo kulinda programu isiyotumia OIDC (OpenID Connect) inamaanisha kuendesha kitu kama oauth2-proxy kando yake. Mtoa huduma wa proxy aliyejengwa ndani ya Authentik ndiyo sehemu hiyo, ambayo tayari imejumuishwa, na ndiyo sababu watumiaji wengi wa self-hosting wenye mkusanyiko wa programu mbalimbali huchagua mfumo huu.

Hifadhi rudufu na maboresho

Mambo matatu hufanya urejeshaji uwezekane: hifadhidata 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 na .env pamoja. Dump pekee haitoshi, kwa sababu ufunguo wa siri (secret key) unaolinda data za session na token unapatikana ndani ya .env.

Maboresho ni mabadiliko ya tag. Weka AUTHENTIK_TAG katika .env kwenye toleo unalotaka, kisha endesha docker compose pull ikifuatiwa na docker compose up -d. Soma maelezo ya toleo kwanza, kwa sababu Authentik hutumia matoleo yanayozingatia tarehe na baadhi ya matoleo huleta mabadiliko (migrations) yanayohitaji uwe umetoka kwenye toleo lililotangulia. Chukua dump ya hifadhidata kabla ya kufanya pull, si baada ya hapo.

FAQ

Je, Authentik ni bure kwa self-hosting?

Toleo la open source ni bure na linajumuisha kila kitu kilichotajwa hapo juu: proxy provider, forward auth, OIDC (OpenID Connect), SAML, na injini ya flows. Toleo la enterprise linalolipwa huongeza msaada wa kiufundi na baadhi ya vipengele vya kibiashara, lakini hakuna kinachohitajika hapa kinachohitaji leseni.

Je, ninahitaji Traefik ili kutumia Authentik?

Hapana. Forward auth inafanya kazi na nginx kupitia auth_request na na Caddy kupitia forward_auth. Mfumo ni uleule katika kila hali: reverse proxy humuuliza Authentik kuhusu kila ombi, na path prefix /outpost.goauthentik.io/ kwenye hostname inayolindwa lazima ielekeze kwenye Authentik badala ya kuelekeza kwenye programu husika.

Kwa nini programu yangu inayolindwa inaruka kati ya login na error bila kukoma?

External host iliyosanidiwa kwenye proxy provider hailingani na URL inayotumiwa na kivinjari, mara nyingi ni http dhidi ya https. Session cookie hutolewa kwa origin moja na kusomwa kwenye nyingine, kwa hivyo Authentik huona ombi la mtumiaji asiyejulikana kila wakati. Sahihisha external host, kisha futa cookies kwa hostname zote mbili kabla ya kujaribu tena.

Authentik inahitaji RAM kiasi gani?

Kiwango cha chini kilichopendekezwa ni CPU cores 2 na 2 GB ya RAM kufikia Julai 2026, ikijumuisha PostgreSQL, seva, na worker kwa pamoja. Kwenye mashine ya 2 GB, worker ndiyo mchakato wa kwanza ambao kernel huusitisha (kill) wakati wa msongo wa kumbukumbu, na dalili yake ni kazi za nyuma (background tasks) na barua pepe zinazotumwa nje kusimama wakati ukurasa wa login bado unafanya kazi. Ipe 4 GB ikiwa seva hiyo hiyo inaendesha pia programu unazozilinda.