Authentik SSO ya Kujihifadhi kwa Programu Zako

Kuingia mara moja kwa kila programu unayohifadhi

Authentik ni seva ya SSO (single sign-on) inayojihifadhiwa: 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 zinazozalishwa. Sehemu inayohitaji uamuzi wa makini huanza baada ya hapo: kuelekeza proksi ya reverse kwake na kuweka programu moja iliyopo nyuma ya forward auth.

Authentik hutolewa ikiwa na huduma tatu katika faili hiyo ya Compose: hifadhidata ya PostgreSQL, mchakato wa server, na mchakato wa worker. Kontena ya seva pia huendesha outpost iliyopachikwa, ambayo ni sehemu inayojibu swali la "je, ombi hili limeingia?" kwa kila programu iliyolindwa. Toleo la 2026.5 ndilo toleo la sasa kufikia Julai 2026, na mradi unapendekeza hosti yenye angalau cores 2 za CPU na 2 GB za RAM. Chukulia huo kuwa kiwango cha chini. PostgreSQL na worker zote huhifadhi matumizi ya kumbukumbu baada ya mashine kufanya kazi kwa siku moja.

Unachohitaji kabla ya kuanza

Unahitaji Docker Engine yenye programu-jalizi ya Compose v2, ambayo unaweza kuthibitisha kwa docker compose version. Ikiwa itaonyesha kosa badala ya toleo, sakinisha programu-jalizi hiyo kabla ya kuendelea; misingi imeelezwa katika kuendesha programu kwa Docker Compose kwenye VPS. Pia unahitaji rekodi ya DNS A inayoelekeza kwenye seva, auth.example.com katika mifano iliyo hapa chini, kwa sababu Authentik huunda URL za uelekezaji upya kutokana na jina la mwenyeji lililotumiwa na kivinjari.

Endesha stack kama mtumiaji wa kawaida aliye katika kikundi cha docker, badala ya kutumia root. Uanachama katika kikundi hicho ni sawa na kuwa na root kwenye host, kwa hiyo mpe akaunti moja ya deployment pekee, na si mtu mwingine yeyote, kama ilivyoelezwa katika akaunti za watumiaji zenye ruhusa chache kwenye VPS.

Install with the official Compose file

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 should list three containers, with postgresql reporting healthy and server and worker reporting running. The first start runs the database migrations, so give it a minute before the web interface answers.

Both generated values matter, for different reasons. PG_PASS is the PostgreSQL password, and it has a hard limit of 99 characters. AUTHENTIK_SECRET_KEY signs sessions and tokens, so changing it later logs every user out and invalidates every API token you have issued. Keep .env at mode 600 and keep a copy somewhere safe, because a database restored without its matching secret key is a database nobody can log into.

The Compose file reads both values with the ${PG_PASS:?database password required} form, which means Compose refuses to start when the file is missing. Running docker compose up -d from the wrong directory prints required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required and stops. That message is a path problem, not a config problem.

Thamani za mazingira zinazohusika

Kila kitu kingine kinawekwa katika faili ile ile ya .env. Authentik hubadilisha alama mbili za underscore kuwa ufunguo wa usanidi uliowekwa ndani, kwa hiyo AUTHENTIK_EMAIL__HOST huweka email.host. Underscore moja hupuuzwa bila onyo. Hii ndiyo sababu ya kawaida zaidi ya mpangilio kuonekana hauleti athari yoyote.

• AUTHENTIK_BOOTSTRAP_PASSWORD huweka nenosiri la mtumiaji wa ndani wa akadmin wakati wa kuanza kwa mara ya kwanza, kwa hiyo hutaandika nenosiri hilo katika fomu ya wavuti ya 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 porti zilizochapishwa kutoka katika 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 pepe zinazotumwa nje. Bila mipangilio hiyo, Authentik hujaribu localhost kwenye porti 25, kwa hiyo barua pepe za kuweka upya nenosiri huishia kwa hitilafu ya muunganisho katika logi ya worker.
• AUTHENTIK_LOG_LEVEL=debug huwasha maelezo ya ziada unayohitaji wakati mtiririko wa kuingia haufanyi kazi vizuri. Irudishe kuwa info baadaye.
• AUTHENTIK_ERROR_REPORTING__ENABLED ni false kwa chaguo-msingi. Iweke kuwa true tu ikiwa unakubali kutuma ripoti za kuacha kufanya kazi kwa msanidi wa programu.

Hizi ni siri zilizo katika faili isiyosimbwa, kwa hiyo ishughulikie saraka hiyo kama unavyoshughulikia hifadhi nyingine yoyote ya vitambulisho. Kidhibiti cha nywila kama instansi ya Vaultwarden inayojihifadhi ni mahali salama zaidi pa kuhifadhi nakala ya urejeshaji kuliko dokezo kwenye laptop yako.

Kuingia kwa mara ya kwanza na akaunti ya msimamizi

Fungua http://SERVER_IP:9000 kwenye kivinjari. Authentik huonyesha mtiririko wake wa awali wa usanidi na kukuomba uweke nenosiri la mtumiaji chaguomsingi akadmin. Ikiwa tayari umeweka AUTHENTIK_BOOTSTRAP_PASSWORD, hatua hiyo imekamilika na utaelekezwa moja kwa moja kwenye ukurasa wa kuingia.

Jitengenezee mtumiaji wa kawaida wa msimamizi katika Directory na kisha Users, umwongeze kwenye kikundi cha authentik Admins, na uingie ukitumia akaunti hiyo. Acha akadmin kama akaunti ya dharura yenye nenosiri refu lililohifadhiwa nje ya mtandao. Kazi za kila siku kwa kutumia akaunti iliyojengewa ndani na inayoshirikiwa huharibu kumbukumbu ya ukaguzi, kwa sababu kila tukio linasema akadmin na hakuna kinachoonyesha ni nani.

Weka Authentik nyuma ya reverse proxy

Kuchapisha port 9000 kwenye intaneti hufanya kazi, lakini unahitaji TLS (usalama wa safu ya usafirishaji) na jina halisi la hosti. 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 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 kiotomatiki, kwa hiyo huduma ya server huhifadhi kila kitu kutoka kwenye faili rasmi na kupata labels hizo. Kagua kwa curl -I https://auth.example.com/if/user/, ambayo inapaswa kujibu HTTP/2 200. 404 page not found kutoka Traefik inamaanisha kuwa kontena halipo kwenye mtandao wa proxy, na Traefik haiwezi kuelekeza trafiki kwenye kontena ambayo haiwezi kuifikia.

Baada ya jina la hosti kufanya kazi, funga port 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 mode isiyo sahihi kunaweza kukugharimu saa moja. Proxy inamaanisha kuwa outpost yenyewe inapeleka traffic kwenye programu ya upstream. Forward auth (single application) inamaanisha kuwa reverse proxy yako bado inapeleka traffic, na inauliza Authentik tu ikiwa ombi limeingia kwa uthibitishaji. Forward auth (domain level) inalinda kila programu iliyo chini ya parent domain moja kwa kutumia provider mmoja, lakini inahitaji sheria za uidhinishaji kwa kila programu. Traefik ikiwa mbele, unahitaji forward auth (single application).

Kwenye kiolesura cha wavuti, fungua Applications kisha Providers, unda Proxy Provider, chagua mode ya forward auth single application, na weka external host kuwa https://app.example.com. Unda Application inayoelekeza kwenye provider huyo. Kisha fungua Outposts, hariri authentik Embedded Outpost, na uhamishe programu mpya kwenye selected applications zake. Outpost hujibu tu programu ilizopewa, kwa hiyo kuruka hatua hiyo ya mwisho ndiyo sababu provider iliyosanidiwa kwa usahihi bado hairudishi jibu.

Fafanua middleware mara moja, kwenye Authentik container, kisha irejelee kutoka 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 kwenye jibu la Authentik na kuweka kwenye ombi linalotumwa upstream. Ukiiacha, programu bado italindwa, lakini haitajua mtumiaji ni nani, kwa hiyo kitu chochote kinachosoma X-authentik-username kwa ajili ya kuingia kiotomatiki kitabaki bila kuingia.

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 watu wengi huiacha. Baada ya kuingia kwa uthibitishaji, Authentik hurudisha browser kwenye path iliyo chini ya /outpost.goauthentik.io/ kwenye hostname ya programu, si kwenye auth.example.com. Bila router inayotuma path prefix hiyo kwenye Authentik service, ombi hufika kwenye programu yako, ambayo hurudisha 404, na kuingia hakukamiliki. priority iliyo juu ndiyo hufanya sheria ya path maalum ishinde sheria ya kawaida ya Host() kwenye domain hiyo hiyo.

Ijaribu kwenye dirisha la browser la faragha. Unapaswa kutumwa kwenye auth.example.com, uingie, kisha urudi kwenye programu. docker compose logs -f server upande wa Authentik huchapisha authorization event kwa kila jaribio, na kukuonyesha ikiwa ombi lilifika Authentik kabisa.

Hitilafu utakazokumbana nazo

Mzunguko usioisha wa uelekezaji upya kati ya programu na ukurasa wa kuingia. Jina la seva la nje kwenye mtoa huduma halilingani na jina linalotumiwa na kivinjari, kwa kawaida http:// kwenye mtoa huduma dhidi ya https:// kwenye sehemu ya anwani. Kisha cookie ya kipindi huwekwa kwa origin tofauti, hivyo kila ombi la kurudi huonekana kuwa ombi jipya kutoka kwa mtumiaji asiyejulikana. Rekebisha jina la seva la nje na ufute cookies za vikoa vyote viwili kabla ya kujaribu tena.

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

Programu inapakia bila kamwe kuomba kuingia. Lebo ya middlewares inataja middleware ambayo haipo. Traefik haitoi onyo kuhusu hilo, kwa hiyo kosa la kuandika katika authentik@docker husababisha tu middleware kutotekelezwa. Fungua dashibodi ya Traefik na uthibitishe kuwa router inaorodhesha middleware hiyo.

403 kutoka Authentik baada ya kuingia kwa mafanikio. Mtumiaji amethibitishwa lakini hana ruhusa: programu ina policy binding au hitaji la kikundi ambalo mtumiaji huyu hatimizi. Kumbukumbu ya Events katika kiolesura cha msimamizi hutaja policy iliyokataa ombi.

Wakati Keycloak ni chaguo linalofaa zaidi

Keycloak ni mradi wa zamani zaidi, unaoungwa mkono na Red Hat, na ni chaguo bora zaidi kwa matumizi ya kawaida ya utambulisho wa biashara: uunganishaji mzito wa SAML, kuratibu kuingia kutoka kwa watoa huduma kadhaa wa utambulisho wa nje kwa wakati mmoja, na kuhamisha realm kwa kutumia export na import kama njia iliyoandikwa ya uhamishaji. Kwa baadhi ya mashirika, msaada wa kibiashara unaounga mkono Keycloak ni muhimu kwa mujibu wa sera na nyaraka zao. Hasara ni kwamba Keycloak haina proxy yake, kwa hiyo kulinda programu isiyotumia OIDC (OpenID Connect) kunahitaji kuendesha kitu kama oauth2-proxy kando yake. Authentik ina built-in proxy provider ya kufanya kazi hiyo, ikiwa tayari imeunganishwa, ndiyo maana wasimamizi wengi wa mifumo yao wenyewe walio na programu mbalimbali huishia kuitumia.

Nakala rudufu na masasisho

Mambo matatu huwezesha urejeshaji: 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 dampo hilo pamoja na .env. Dampo pekee halitoshi, kwa sababu ufunguo wa siri unaolinda data ya vipindi na tokeni uko katika .env.

Masasisho ni mabadiliko ya lebo. Weka AUTHENTIK_TAG katika .env iwe toleo unalotaka, kisha endesha docker compose pull ikifuatiwa na docker compose up -d. Soma maelezo ya toleo kwanza, kwa sababu Authentik hutumia matoleo yanayotegemea tarehe, na baadhi ya matoleo yana uhamishaji wa data unaotarajia ufike kutoka toleo lililotangulia. Tengeneza dampo la hifadhidata kabla ya pull, si baada yake.

FAQ

Je, Authentik ni ya bure kwa kujiendeshea mwenyewe?

Toleo la open source ni la bure na linajumuisha kila kitu kilichoelezwa hapo juu: mtoa huduma wa proxy, forward auth, OIDC (OpenID Connect), SAML, na injini ya flows. Kiwango cha enterprise kinacholipiwa huongeza usaidizi na baadhi ya vipengele vya enterprise, lakini hakuna kitu hapa kinachohitaji leseni.

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 kiambishi awali cha njia /outpost.goauthentik.io/ kwenye hostname iliyolindwa lazima kielekeze kwa Authentik badala ya programu.

Kwa nini programu yangu iliyolindwa inarudia kati ya kuingia na hitilafu bila mwisho?

Host ya nje iliyosanidiwa kwenye mtoa huduma wa proxy hailingani na URL inayotumiwa na kivinjari, mara nyingi http dhidi ya https. Kuki ya kipindi hutolewa kwa origin moja na kusomwa kwenye origin nyingine, hivyo Authentik huona ombi lisilotoka kwa mtumiaji aliyeingia kila mara. Sahihisha host ya nje, kisha futa kuki 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 ya RAM kufikia Julai 2026, kikijumuisha PostgreSQL, server na worker kwa pamoja. Kwenye kompyuta yenye 2 GB, worker huwa mchakato wa kwanza ambao kernel huumaliza wakati wa shinikizo la kumbukumbu, na dalili yake ni kusimama kwa kazi za chinichini na barua pepe zinazotumwa nje huku ukurasa wa kuingia ukiendelea kufanya kazi. Ipe 4 GB ikiwa server hiyo hiyo pia inaendesha programu unazolinda.