Repository navigation
forward auth authelia
Authelia can sit in front of Muximux as either a forward-auth provider or an OIDC provider. This guide covers both. Forward auth is the original Authelia integration model. It is also the most common. OIDC (OpenID Connect, a standard sign-in protocol) is the more recent approach, and it is more portable.
If you're not sure which to pick:
- Pick forward auth if Authelia already protects other apps in your stack through your reverse proxy (a server that forwards requests to another server, such as Traefik, Nginx, Caddy). It's the lighter setup.
- Pick OIDC if you want Muximux to sign users in with Authelia the same way it would with Keycloak or Entra ID. This works independently of your reverse proxy.
In this mode, your reverse proxy calls Authelia on every request. Authelia decides whether to allow the request and adds headers like Remote-User and Remote-Groups. Muximux trusts those headers.
If Authelia already protects other apps, you only need to add a rule for Muximux's host. Add it in configuration.yml:
access_control:
default_policy: deny
rules:
- domain: muximux.example.com
policy: two_factor # or one_factor; pick what suits your risk modelThe headers themselves need no special Authelia config. Authelia sends Remote-User, Remote-Email, Remote-Name, and Remote-Groups by default.
The exact syntax depends on your proxy. The pattern is the same for all proxies. Forward Muximux's traffic to Authelia's /api/verify endpoint. Then copy the auth headers into the request that goes on to Muximux.
Traefik (file provider):
http:
routers:
muximux:
rule: "Host(`muximux.example.com`)"
service: muximux
middlewares: [authelia]
tls:
certResolver: default
services:
muximux:
loadBalancer:
servers:
- url: "http://muximux:8080"
middlewares:
authelia:
forwardAuth:
address: "http://authelia:9091/api/verify?rd=https://auth.example.com"
trustForwardHeader: true
authResponseHeaders:
- Remote-User
- Remote-Groups
- Remote-Email
- Remote-NameNginx: see Authelia's official Nginx integration page for the exact snippet. Then point the protected location at Muximux.
Caddy: Authelia's Caddy integration page covers forward_auth directives.
auth:
method: forward_auth
trusted_proxies:
- 172.16.0.0/12 # whatever subnet your reverse proxy lives in
headers:
user: Remote-User
email: Remote-Email
groups: Remote-Groups
name: Remote-Name
logout_url: https://auth.example.com/logouttrusted_proxies is required. Muximux only accepts auth headers that arrive from a trusted hop (an address in this list). Setting it to 0.0.0.0/0 removes the protection. Restrict it to your reverse proxy's actual address or subnet.
You can promote users to admin through groups. By default, Authelia puts your group memberships into Remote-Groups as a comma-separated list. Muximux looks for any of admin, admins, or administrators (case-insensitive). If your admin group has a different name, set forward_auth_admin_groups on the auth block to that name:
auth:
method: forward_auth
forward_auth_admin_groups:
- dashboard-admins- Open
https://muximux.example.com/. You should see Authelia's login page. - Sign in. Complete 2FA if Authelia asks for it. You should land on the Muximux dashboard.
- Sign in as a user whose
groupsfield in Authelia includesadmin(oradmins/administrators). The Settings gear should appear.
Authelia can also act as an OIDC provider. In that mode you don't need any forward-auth setup. Muximux talks to Authelia directly.
Add a client to Authelia's configuration.yml:
identity_providers:
oidc:
hmac_secret: <a long random string>
issuer_private_key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
clients:
- id: muximux
description: Muximux dashboard
secret: '<bcrypt-hashed secret, see Authelia docs>'
public: false
authorization_policy: two_factor
redirect_uris:
- https://muximux.example.com/api/auth/oidc/callback
scopes:
- openid
- profile
- email
- groups
userinfo_signing_algorithm: noneAuthelia stores client secrets as hashes. Use authelia hash-password '<secret>' to generate one.
auth:
method: oidc
oidc:
enabled: true
issuer_url: https://auth.example.com
client_id: muximux
client_secret: ${AUTHELIA_CLIENT_SECRET} # the plaintext, not the hash
redirect_url: https://muximux.example.com/api/auth/oidc/callback
scopes:
- openid
- profile
- email
- groups
username_claim: preferred_username
email_claim: email
groups_claim: groups
display_name_claim: name
admin_groups:
- Muximux-Adminsissuer_url is the public base URL of your Authelia instance, with no trailing path. Authelia exposes the OIDC discovery document at https://auth.example.com/.well-known/openid-configuration.
Validate the same way as for any other OIDC provider:
- Visit
/login. - Click Login with SSO.
- Sign in to Authelia. Authelia sends you back to Muximux.
- Sign in as a member of the group listed in
admin_groups. Members of that group see the Settings gear.
| Symptom | Cause | Fix |
|---|---|---|
Forward auth: Remote-User empty |
The reverse proxy isn't forwarding the header, or the rule that protects Muximux didn't match. | Check the reverse-proxy logs for the response headers from /api/verify. They should include Remote-User. |
| Forward auth: requests bypass Authelia | A request reached Muximux from outside the trusted-proxy range. | Lock down access at the reverse proxy so direct connections to Muximux's port aren't possible from outside the proxy network. |
| Forward auth: admin gear missing for known admin user | Authelia is sending Remote-Groups: foo and Muximux's check is for admin/admins/administrators. |
Either rename the admin group in Authelia, or set forward_auth_admin_groups in Muximux to your group's name. |
OIDC: unauthorized_client from Authelia |
The client secret in config.yaml doesn't match Authelia's stored hash. |
Regenerate the hash with authelia hash-password and verify the plaintext you put in Muximux's environment matches. |
OIDC: no groups claim in token |
groups not in the client's scopes list in Authelia. |
Add groups to both Authelia's client config (Step 1) and Muximux's scopes:. |
-
Authentication overview for the rest of
auth.oidcandauth.method: forward_auth. - Other identity providers: Microsoft Entra ID, Keycloak, Authentik, Pocket ID, Zitadel, Google, Cloudflare Access.
Getting Started
Features
- Apps
- HTTP Actions
- Reverse Proxy
- Docker Discovery
- Docker Labels
- Docker Swarm & Compose
- Navigation
- Split View
- Themes
- Keyboard Shortcuts
- Keyboard & Accessibility
- Health Monitoring
- Icons
- Translations
Security
Identity provider guides
Operations