Authelia SSO Setup

Authelia is a lightweight self-hosted auth server popular with home-labbers — often paired with a reverse proxy like Traefik or Caddy.

Authelia config

Authelia is configured via YAML files. Edit your Authelia configuration.yml:

identity_providers:
  oidc:
    jwks:
      - key_id: 'dockmesh'
        # Generate with: authelia crypto pair rsa generate
        key: |
          -----BEGIN PRIVATE KEY-----
          ...your private key...
          -----END PRIVATE KEY-----

    clients:
      - client_id: 'dockmesh'
        client_name: 'dockmesh'
        client_secret: '$pbkdf2-sha512$...'  # hash your secret with authelia crypto hash generate
        public: false
        authorization_policy: 'two_factor'
        redirect_uris:
          - 'https://dockmesh.example.com/auth/oidc/callback'
        scopes:
          - 'openid'
          - 'profile'
          - 'email'
          - 'groups'
        userinfo_signed_response_alg: 'none'

Generate the secret

# On the Authelia container
docker exec -it authelia authelia crypto hash generate pbkdf2 --password 'my-long-random-secret'

Save both the plaintext secret (for dockmesh config) and the hash (for Authelia config).

Users and groups

Authelia uses a users database file (users_database.yml) or an LDAP backend. Example users file:

users:
  alice:
    displayname: 'Alice Example'
    password: '$pbkdf2-sha512$...'
    email: alice@example.com
    groups:
      - dockmesh-admins

  bob:
    displayname: 'Bob Example'
    password: '$pbkdf2-sha512$...'
    email: bob@example.com
    groups:
      - dockmesh-viewers

Restart Authelia to pick up config changes.

In dockmesh

Settings → Authentication → OIDC → Add provider:

Field	Value
Display name	`Authelia`
Issuer URL	`https://auth.example.com` (Authelia’s external URL)
Client ID	`dockmesh`
Client secret	the plaintext secret from earlier
Scopes	`openid profile email groups`
Groups claim	`groups`

Click Test, then Save.

Group mapping

Settings → Authentication → Group mappings:

dockmesh-admins → Admin role, all hosts
dockmesh-viewers → Viewer role, all hosts
Add more as needed

Two-factor auth

Because our Authelia config sets authorization_policy: two_factor, users must complete 2FA (TOTP or WebAuthn, depending on Authelia setup) before Authelia issues tokens to dockmesh. This means 2FA is enforced at the IdP level — dockmesh’s own 2FA is redundant for SSO users and can be disabled.

Troubleshooting

“access_denied” after login:

User’s group doesn’t match any mapping → no role assigned
Check Authelia logs: which groups were in the user’s session?

“invalid_client”:

Client ID mismatch, or client secret mismatch
If you changed the secret, regenerate the pbkdf2 hash in Authelia config

Discovery URL 404:

Authelia’s OIDC endpoints are under /api/oidc/... — the discovery is at https://auth.example.com/.well-known/openid-configuration
Check this URL works in a browser before configuring dockmesh