How to Use Authentik: The Beginner's Guide to Self-Hosted SSO

CodexFuse Team · 2026-10-31T03:57:27.257Z · 13 min read min read

Authentik gives your homelab or small team one login for every app. Docker install, initial setup, first OAuth2 provider, the proxy provider, and the one-login rule — the complete beginner guide.

How to Use Authentik: The Beginner's Guide to Self-Hosted SSO

Learning how to use Authentik is the moment your homelab or small team stops juggling a dozen passwords and gets one login for everything. Authentik is an open-source, self-hosted identity provider that puts a single sign-on (SSO) gate in front of your apps — OAuth2/OIDC, SAML, LDAP, and even apps with no login support at all via its proxy provider.

It installs as a Docker Compose stack and takes about twenty minutes to reach the first admin dashboard. The current release line is date-versioned (2026.8.5, released October 21, 2026). This authentik tutorial runs the full beginner arc: Docker install, the initial-setup flow, your first OAuth2/OIDC provider wired into a real app, the proxy provider for the app that never learned SSO, and the one-login rules that keep it all sane.

When your first login round-trip succeeds, paste the access token into a JWT decoder — seeing your own claims in the token is the fastest way to understand what an identity provider actually does.

You will build in this order: provision a server, download the compose file and generate secrets, run the stack, finish the initial-setup flow, create your first OAuth2 provider plus application, wire one app's login to it, then protect a second app with the proxy provider. Nothing here assumes you have run an identity provider before — only that you have used Docker Compose once. If the compose file feels new, read the Docker beginner guide first; this guide starts where that one ends.

How do you use Authentik?

You use Authentik by running its Docker Compose stack, finishing the web-based initial-setup flow to create the admin account, then registering each of your apps as an Application with the right provider type: OAuth2/OIDC for modern apps, SAML for enterprise tools, LDAP for legacy ones, and the proxy provider for apps with no SSO support at all. After that, your users log in once at Authentik and every connected app trusts that login. The whole beginner path is five steps:

1. Download the official compose file, generate the two secrets, and run docker compose up -d on a server with at least 2 CPU cores and 2 GB of RAM.
2. Open http://your-server:9000/if/flow/initial-setup/ (the trailing slash matters) and create the akadmin bootstrap account.
3. Create an OAuth2/OIDC provider and an Application for your first app, and copy the Client ID and Client Secret.
4. Paste the Client ID, Secret, and the exact redirect URI into the app's own login settings.
5. Log in through Authentik once — then add a second app, and a proxy provider for anything that has no login at all.

What is Authentik?

Authentik is a Python-based, open-source identity provider you run yourself: it becomes the one place your users log in, and it vouches for them to every app you connect. The official docs describe it as self-hosted with no hosted offering at all — your server, your users, your data.

It speaks the protocols the app world already knows: OAuth2/OIDC (OpenID Certified), SAML, SCIM, LDAP, RADIUS, WS-Fed, plus its own proxy provider that adds SSO to apps with no native login support. There are 180-plus integration guides in the docs, and the free Open Source tier covers OIDC, SAML, LDAP, SCIM, RADIUS, Kerberos, and the proxy provider with no user limit — the project promises no open-source feature ever becomes enterprise-only.

The authentik sso idea is simple but worth saying plainly: instead of each app storing its own passwords, each app redirects logins to Authentik, Authentik checks the user (password, second factor, policies you define with its flows-and-stages engine), and hands the app a signed token proving it.

Change the password once in Authentik and it changes for every app. Disable one user and they lose all of them. That is the whole point of the product.

Authentik vs Keycloak: which one should a beginner pick?

Both are open-source self-hosted identity providers, and Keycloak is the older, more famous one — so the authentik vs keycloak question comes up in every thread. The honest beginner answer is about the shape of the tool, not which is "better." Here is the decision in one table, with the authentik side verified against its current docs:

Keycloak is a comparison member here, never a second guide — this page owns the authentik lane only. If your apps all speak OIDC already, either one works and the choice is taste. If your shelf has apps with no login support at all — the wiki, the camera UI, the dashboard from 2014 — the proxy provider is why Authentik wins for beginners, and the rest of this guide leans on exactly that.

What do you need before you install Authentik?

Four things. First, a Linux server you can SSH into with at least 2 CPU cores and 2 GB of RAM — the official install page's own minimums. If the concept is new, start with what is VPS hosting; a $5 virtual server covers it.

Second, Docker Compose v2 (or Podman), since the whole product ships as a compose stack. Third, a domain name pointed at the server — optional for the first setup (the install page accepts your server's IP or hostname for day one), but required before production because OAuth redirect URIs and real HTTPS certificates depend on it. Fourth, about twenty minutes and one coffee.

How do you install Authentik with Docker?

The authentik install is the official compose file plus two generated secrets, then one compose command. Authentik's docs moved recently (the live install page is at docs.goauthentik.io/install-config/install/docker-compose/ — old /docs/installation/ paths redirect), and the whole current flow is:

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

Three details beginners always trip on. The secrets go in a local .env file the compose file reads — keep PostgreSQL passwords under 99 characters, because longer ones are unsupported. The compose file pins the Authentik version at download time, so upgrading later means downloading a fresh compose.yml, not just pulling images.

And do not mount /etc/timezone or /etc/localtime into the containers: all internal operations run in UTC, and a timezone mount breaks OAuth and SAML signatures. Internally the stack listens on 9000 (HTTP) and 9443 (HTTPS); set COMPOSE_PORT_HTTP and COMPOSE_PORT_HTTPS in the .env if you need different host ports.

The Docker socket gets mounted into the worker so Authentik can auto-deploy its outposts (the pieces that sit in front of your apps) — that is by design, and the docs note you can harden it with a socket proxy later. After docker compose up -d, confirm with docker compose ps and move to the setup flow.

Authentik initial setup: the first five minutes

The authentik initial setup is a web flow, not a config file: open http://your-server's-IP-or-hostname:9000 and you land on the initial-setup flow at /if/flow/initial-setup/. Two things about that path are load-bearing.

The trailing slash is required — without it you get a Not Found page and an unnecessary debugging session. And the IP-or-hostname choice the docs allow is fine for the first install, but switch to your real domain before you wire real apps, because every redirect URI you are about to configure will contain it.

The flow creates the bootstrap admin account akadmin and asks you to set its password. Generate something long with a password generator and store it in your vault — then log in and change it again from the admin interface after your first session, so the bootstrap credential is fresh history, not a permanent secret. If you ever lock yourself out, the last-resort recovery is docker compose exec server ak changepassword akadmin from the server shell, then log in through the default authentication flow.

How do you connect your first app with OAuth2?

You connect it in the admin interface: go to Applications, run the wizard to create an application with an OAuth2/OIDC provider, and copy the Client ID and Client Secret it issues. Authentik's authentik oauth2 wiring has two objects you must not confuse: a provider is the protocol configuration (OAuth2/OIDC settings, redirect URIs, scopes), and an application is the thing your users see (name, icon, launch URL, policy bindings). Each app gets its own provider — never reuse one provider for two apps, because the redirect URIs and client credentials are per-app secrets and sharing them is how cross-app login bugs are born.

The provider's Redirect URIs field is an exact-match list: the URI your app sends during login must appear there character for character (regex is allowed if you escape literal dots as \.). The docs' own Grafana example uses https://grafana.company/login/generic_oauth; for Gitea, check Gitea's OAuth2 docs for the exact callback path on your version and paste it in the same field.

Leave the field empty and Authentik auto-saves the first URI used — convenient for a first test, but fill it in explicitly for anything you keep. Typical scopes are openid profile email; add offline_access only if you need refresh tokens.

Authentik's OIDC endpoints live under predictable paths — /application/o/authorize/, /application/o/token/, /application/o/userinfo/, and the discovery document at /application/o/<slug>/.well-known/openid-configuration. The product is OpenID Certified for OIDC, which means a standards-compliant app will accept those endpoints without custom code. Your worked example for this section: the authentik gitea combo is the classic first win (your git forge now logs in through Authentik) — wire one real app, confirm the round trip, then move to the app that has no login at all.

Authentik proxy provider: what do you do about apps with no SSO?

The authentik proxy provider exists for the app that was never going to learn OAuth: it protects it with forward auth instead of asking it to change. You deploy an Authentik outpost (or point your existing reverse proxy — nginx, Caddy, Traefik, HAProxy, or Envoy — at the outpost), and the outpost either proxies traffic upstream itself (proxy mode) or answers auth checks from your reverse proxy (forward-auth mode, single-app or domain-level). Either way, the user hits Authentik's login first, and only authenticated requests reach the app.

The mechanism is header injection: after a successful login the outpost adds X-authentik-* headers — username, groups, entitlements, email, name, uid — to the upstream request, so the app can tell who is visiting without running any login code. This is the beginner superpower: the internal wiki, the printer UI, the dashboard from 2014 all get one login and you never touched their code. One provider per app still applies, and the proxy provider is the second worked example of this guide, never a separate article.

The one-login rule: how do you keep Authentik sane as you add apps?

Every beginner's Authentik dies the same way: one shared provider, sloppy redirect URIs, and the admin password from setup day still in use. The one-login rule is four habits.

One provider per application, always — the Client ID and Secret are per-app. Redirect URIs entered exactly, never auto-saved in production. The akadmin password rotated after first login and stored in a vault.

And HTTPS in front of ports 9000/9443 before any real user touches it, because tokens over plain HTTP are credentials over plain HTTP.

Beginner mistakes that break a first Authentik install

These are the six ways first installs actually fail, collected from the docs' troubleshooting pages and the 2026 guides. The table is the citable asset — pin it next to your compose file.

Is Authentik actually free?

The direct answer: the Open Source tier is free with no user limit and no hosted offering exists — you self-host, period. The verified pricing from the project's site at write time: Enterprise is $5 per user per month billed annually ($0.02 per external user per month) and adds PAM, agent accounts, Entra ID and Google Workspace integrations, mTLS client certificates, and audit extras; Enterprise Plus starts at $20k per year for SLAs and multi-instance setups. For a homelab or small team, the free tier is the whole product you need.

Sources

Every version number, command, path, and price in this guide was checked against the live source on October 30–31, 2026 — nothing was copied from search snippets.

• Authentik Docker Compose install — docs.goauthentik.io/install-config/install/docker-compose/ (requirements, secrets, COMPOSE_PORT_HTTP/HTTPS, timezone warning, upgrade flow)
• First steps and the initial-setup flow — docs.goauthentik.io/install-config/first-steps/ (/if/flow/initial-setup/, trailing slash, akadmin)
• Login troubleshooting and akadmin recovery — docs.goauthentik.io/troubleshooting/login/ (docker compose exec server ak changepassword akadmin)
• OAuth2/OIDC provider reference — docs.goauthentik.io/add-secure-apps/providers/oauth2/ (redirect URIs, grant types, endpoints, OpenID Certified)
• Proxy provider reference — docs.goauthentik.io/add-secure-apps/providers/proxy/ (forward-auth vs proxy mode, X-authentik-* headers)
• Release version 2026.8.5 (2026-10-21) — github.com/goauthentik/authentik/releases (date-versioned scheme)
• Pricing: Open Source free, Enterprise $5/user/mo, Enterprise Plus from $20k/yr — goauthentik.io/pricing/
• Self-hosted SSO walkthrough on Ubuntu VPS — massivegrid.com/blog/self-host-authentik-ubuntu-vps/ (published 2026-01-24, updated 2026-09-07)
• Authentik as an IdP for NetBird — docs.netbird.io/manage/team/single-sign-on/authentik (updated October 6, 2026)
• LibreChat OAuth2/OIDC wiring with Authentik — librechat.ai/docs/configuration/authentication/OAuth2-OIDC/authentik

Frequently asked questions

Is Authentik free for a homelab?

Yes. The Open Source tier is free with no user limit and includes OIDC, SAML, LDAP, SCIM, RADIUS, Kerberos, and the proxy provider. There is no hosted version — you run it on your own server, which is exactly the homelab use case.

Authentik vs Keycloak — which is easier for a beginner?

Authentik's single Docker Compose install and guided web setup are the shorter path for a first identity provider, and its proxy provider covers apps with no native SSO — the case beginners hit most. Keycloak suits teams already committed to its ecosystem. Both are fully open source at the core.

Do I need a domain name to use Authentik?

Not for the first install — the docs accept your server's IP or hostname for the initial-setup flow. You do need a domain before production: OAuth redirect URIs embed it, and real HTTPS certificates require it.

How do I reset the Authentik admin password?

From the server shell, run docker compose exec server ak changepassword akadmin, then log in again. After recovery, rotate the password from the admin interface so the emergency credential is not permanent.

Can Authentik give SSO to an app that has no login at all?

Yes — that is the proxy provider's job. It sits in front of the app (proxy mode) or answers auth checks from your reverse proxy (forward auth), and injects X-authentik-* headers so the app knows who is visiting. The app itself never changes.