Authentik

Purpose

Authentik provides centralized identity and access management for the Bytek homelab.

Authentik allows users to access multiple applications with one account while applying consistent authentication, multi-factor authentication, group membership, and access policies.

Authentik provides:

Service Information

Authentik portal:

Open Authentik

Architecture Role

Authentik is the trusted identity provider for the Bytek environment.

Applications rely on Authentik to answer these questions:

Authentik does not normally replace application-specific permissions.

For example:

Request Flow

A normal OIDC login follows this process:

Core Components

Authentik Server

The Authentik server provides:

Authentik Worker

The worker performs background tasks such as:

PostgreSQL

PostgreSQL stores Authentik configuration and identity data.

PostgreSQL contains critical information including:

PostgreSQL is the most important Authentik data component to protect.

Redis

Redis supports Authentik’s runtime and task-processing requirements.

Redis is required for normal stack operation but PostgreSQL remains the authoritative persistent data source.

Embedded Outpost

The embedded outpost provides:

Application Portal

The Authentik user portal displays applications available to the signed-in user.

The portal should show only applications that the user is allowed to access.

Normal users may see:

Administrators may additionally see:

Application visibility is controlled by:

Group Model

bytek-users

The bytek-users group grants access to normal user-facing applications.

Applications using this group include:

Users should be added to bytek-users only when access to normal Bytek applications is required.

bytek-admin

The bytek-admin group grants access to administrative applications.

Applications using this group include:

Membership in bytek-admin must be limited to trusted infrastructure administrators.

Administrator Membership

An administrator may belong to both groups:

This allows access to both normal applications and administrative interfaces.

Shared Email-Domain Policy

Applications also use the policy:

The policy validates the user according to the configured Bytek email-domain rules.

The application policy engine is normally set to ALL.

For a normal application, access requires:

For an administrative application, access requires:

Policy Engine Mode

Authentik applications normally use policy engine mode ALL.

With ALL, every enabled binding must pass.

A normal application should therefore have:

An administrative application should have:

Do not attach both bytek-users and bytek-admin to the same application using ALL unless every permitted user must belong to both groups.

An earlier access-denied event occurred because both groups were attached to the same application with ALL.

Application Integration Matrix

Native OIDC Applications

Nextcloud

Nextcloud uses native OIDC so desktop clients, mobile clients, WebDAV, CalDAV, and CardDAV can communicate directly with Nextcloud.

Do not add ForwardAuth to the Nextcloud Traefik router.

Vikunja

Vikunja creates or matches users after a successful Authentik login.

BookStack

BookStack does not automatically link users solely by matching email addresses.

BookStack links an OIDC identity using the token’s sub claim.

The local BookStack administrator must use a different email address from the normal Authentik account unless the account is deliberately linked using the correct external authentication ID.

Proxmox VE

Proxmox authentication and authorization are separate.

Authentik allows the user to authenticate, but Proxmox requires a separate ACL before the user can see or manage VMs.

OIDC Provider Standard

New OIDC providers should normally use:

A signing key is required so applications can validate tokens.

An encryption key should remain empty unless the target application explicitly supports encrypted OIDC tokens.

BookStack login failed when an encryption key was selected.

Clearing the encryption key while retaining the RSA signing key resolved the token-validation failure.

OIDC Scope Mappings

Providers must include the scopes required by the application.

Common scopes include:

The mapping names may appear as Authentik default OAuth scope mappings.

Missing scope mappings can allow the initial browser authorization to complete while causing the application to fail later when requesting profile or userinfo data.

Proxmox Scope Issue

Proxmox initially returned an authentication failure because the Authentik provider did not have the expected scopes selected.

The detailed Proxmox log reported a failure while contacting the userinfo endpoint.

Selecting the required mappings resolved the issue.

Scope Review Procedure

When an OIDC application fails:

Redirect URI Requirements

Redirect URIs must match the application exactly.

A mismatch can cause:

Known Redirect URIs

Do not add unneeded wildcard redirect URIs.

Strict redirect matching is preferred.

Post-Logout Redirects

Where supported, providers should include approved post-logout destinations.

BookStack uses destinations such as:

Post-logout redirects must use the actual production hostname.

Do not use obsolete provisional hostnames such as wiki.bytek.ca.

ForwardAuth Applications

Traefik Dashboard

The Traefik dashboard uses a Proxy Provider configured for single-application ForwardAuth.

The Traefik middleware sends authentication checks to Authentik.

The callback path under /outpost.goauthentik.io/ must remain reachable without applying the same ForwardAuth middleware.

The outpost ping endpoint should return HTTP 204.

Uptime Kuma

Uptime Kuma uses an Authentik Proxy Provider.

Public status-page, badge, push, and asset paths may require selected unauthenticated-path exceptions.

Do not disable Uptime Kuma’s local authentication until the Authentik proxy path has been tested successfully.

Embedded Outpost

The embedded outpost handles Authentik proxy integrations.

Applications assigned to the embedded outpost include:

The outpost must be able to reach each protected application backend.

For Uptime Kuma, Authentik at 192.168.2.162 must be permitted to reach 192.168.2.115 on TCP port 3001.

The outpost callback path must remain accessible through Traefik.

Outpost Health

The outpost health endpoint should return HTTP 204.

For the Traefik dashboard, test:

curl -k -I https://proxy.bytek.ca/outpost.goauthentik.io/ping

Expected result:

A 204 response contains no page body and is expected.

If the endpoint redirects to login or loops repeatedly, review:

Reverse-Proxy Requirements

Traefik must preserve the original request information for Authentik.

Important forwarded values include:

Incorrect forwarded headers can cause:

An Authentik CSRF error previously reported that the CSRF cookie was not set.

When diagnosing a CSRF error, review:

DNS Requirements

Authentik must be reachable from:

Internal Resolution

LAN clients using Pi-hole resolve:

Proxmox Resolution

Proxmox uses Quad9 and normally resolves:

This sends Proxmox’s server-to-server OIDC requests through:

Container Resolution

Application containers that require private split DNS should use Pi-hole at 192.168.2.65.

If an OIDC discovery endpoint becomes unreachable after a power failure, verify DNS from inside the application container before changing provider credentials.

Health Endpoints

Direct Readiness

Direct backend:

http://192.168.2.162:9000/-/health/ready/

Expected result:

Routed Readiness

Public hostname:

Open Authentik Readiness

Expected result:

Embedded Outpost

The outpost ping endpoint should return:

Container Management

Move to the Authentik deployment directory:

cd /opt/authentik

Check container state:

sudo docker compose ps

List Compose service names:

sudo docker compose config --services

View recent logs:

sudo docker compose logs --tail 100

View server logs:

sudo docker compose logs --tail 100 server

View worker logs:

sudo docker compose logs --tail 100 worker

The exact service names should be confirmed using the Compose service listing before running service-specific commands.

Expected Container State

The Authentik stack should have healthy or running equivalents of:

The server should not be considered ready until PostgreSQL and Redis are available.

A running Docker container does not necessarily mean the application is ready.

Use the readiness endpoint for application-level validation.

User Administration

When creating a user:

Do not add normal users to bytek-admin.

Administrator Administration

An Authentik administrator should:

Administrative group membership should be reviewed periodically.

MFA

Authentik provides MFA for applications using OIDC or proxy authentication.

MFA should be required for:

Preserve recovery codes or backup authentication devices.

Do not rely on one physical authenticator without a documented recovery method.

Local Application Recovery Accounts

Authentik must not be the only recovery path.

Proxmox

Use:

Nextcloud

Use:

BookStack

Switch:

Then sign in using the dedicated local administrator.

Uptime Kuma

Restore direct private access and re-enable local authentication.

Traefik

Restore a known-good dashboard file or use retained Basic Auth.

Common Failure Scenarios

Application Shows Permission Denied

Possible causes:

Review the Authentik denial explanation.

A binding shown as None in the explanation may correspond to a direct group-membership check.

Discovery Endpoint Is Unreachable

Possible causes:

Test discovery from the application host and container.

CSRF Cookie Not Set

Possible causes:

Test using a new private browser window.

Token Payload Cannot Be Parsed

Possible cause:

Correction:

User’s Email Is Already Taken

The application may not automatically link an OIDC account to a local account based only on email.

For BookStack:

Authentication Works but Application Is Empty

Authentication succeeded, but application authorization is missing.

For Proxmox:

OIDC Troubleshooting Order

When an OIDC application fails:

Do not recreate the provider until the detailed failure is understood.

Monitoring

Recommended Uptime Kuma monitors include:

Monitoring should distinguish between: