Howto Authelia OIDC

How to set up Authelia as an OIDC provider

This guide configures Authelia's native OIDC provider (v4.34+) so Bindery users sign in via Authelia's login page and receive a standard OIDC session — no forward-auth middleware required.

This is different from Phase 1 proxy auth. Proxy forward-auth (covered in Howto-Authelia-proxy-auth) is a header-passing approach where Bindery trusts a header set by the proxy. OIDC is a token-based flow where Bindery validates a signed ID token directly with Authelia. OIDC is more portable and works without a trusted-proxy network path.

Prerequisites:

• Authelia v4.34+ with OIDC enabled in its configuration
• Bindery v0.24.0+
• BINDERY_OIDC_REDIRECT_BASE_URL set to your public Bindery URL

---

Steps

1. Enable OIDC in Authelia and register the Bindery client

Add to your Authelia configuration.yml:

identity_providers:
  oidc:
    hmac_secret: <random-32-char-secret>      # openssl rand -hex 32
    issuer_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ... your RSA private key ...
      -----END RSA PRIVATE KEY-----

    clients:
      - id: bindery
        description: Bindery
        secret: '$plaintext$<your-bindery-client-secret>'  # openssl rand -hex 32
        public: false
        authorization_policy: one_factor     # or two_factor
        redirect_uris:
          - https://bindery.example.com/api/v1/auth/oidc/authelia/callback
        scopes:
          - openid
          - email
          - profile
          - groups
        userinfo_signing_algorithm: none

Generate the private key if you don't have one:

openssl genrsa -out authelia-oidc.key 4096
# Paste contents into issuer_private_key above

Restart Authelia. Confirm OIDC discovery is available:

curl -s https://auth.example.com/.well-known/openid-configuration | jq .issuer
# Expected: "https://auth.example.com"

2. Set the redirect base URL in Bindery

environment:
  BINDERY_OIDC_REDIRECT_BASE_URL: "https://bindery.example.com"

Restart Bindery if adding for the first time.

3. Add the Authelia provider in Bindery

Settings → Security → OIDC Providers → Add provider, or:

curl -X POST http://bindery:8787/api/v1/settings/auth/oidc/providers \
  -H "X-Api-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "authelia",
    "name": "Authelia",
    "issuer": "https://auth.example.com",
    "client_id": "bindery",
    "client_secret": "<your-bindery-client-secret>",
    "scopes": "openid email profile groups",
    "allowed_groups": "bindery-users"
  }'

Leave allowed_groups empty to allow all Authelia users. Set it to an Authelia group name to restrict access.

Expected result: provider saved, Sign in with Authelia button appears on the Bindery login page.

4. Test the login flow

1. Open a private window → https://bindery.example.com/login → click Sign in with Authelia.
2. Browser redirects to https://auth.example.com — complete the Authelia login (including 2FA if configured).
3. Authelia redirects back to https://bindery.example.com/api/v1/auth/oidc/authelia/callback.
4. Bindery validates the ID token, maps the user by (https://auth.example.com, <authelia-sub>), provisions the account, and logs you in.
5. Confirm in Settings → Users.

5. (Optional) Map Authelia groups to Bindery admin role

In your Bindery provider config, set allowed_admin_groups to the Authelia group whose members should be promoted to admin:

# Update the provider (replace the whole object)
curl -X PUT http://bindery:8787/api/v1/settings/auth/oidc/providers/authelia \
  -H "X-Api-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "authelia",
    "name": "Authelia",
    "issuer": "https://auth.example.com",
    "client_id": "bindery",
    "client_secret": "<secret>",
    "scopes": "openid email profile groups",
    "allowed_groups": "bindery-users",
    "allowed_admin_groups": "bindery-admins"
  }'

---

Choosing between OIDC and forward-auth for Authelia

	Forward-auth (Phase 1)	OIDC (this guide)
How identity is passed	HTTP header (Remote-User)	Signed ID token
Requires trusted-proxy network path	Yes	No
Works without Traefik/Caddy middleware	No	Yes
Supports 2FA	Yes (Authelia handles it)	Yes (Authelia handles it)
Token includes group claims	No (header only)	Yes (groups scope)
Suitable for	Homelab, simple setups	Multi-app, more portable

---

When this goes wrong

Symptom	Cause	Fix
Authelia discovery URL 404	OIDC not enabled in Authelia config	Add identity_providers.oidc block and restart Authelia
invalid_client on callback	Client ID/secret mismatch	Compare client_id / client_secret in Bindery with the id / secret in Authelia's clients list
redirect_uri_mismatch	Callback URL not in Authelia's redirect_uris	Add https://bindery.example.com/api/v1/auth/oidc/authelia/callback to Authelia's client config
state mismatch on callback	Proxy stripping Set-Cookie headers	Ensure your reverse proxy passes Set-Cookie response headers from Bindery unchanged
allowed_groups blocks all users	Group claim not included in token	Add groups to scopes in both Authelia client config and Bindery provider config
Login works but user always gets user role, never admin	allowed_admin_groups not set	Add allowed_admin_groups to the Bindery provider config (step 5)

See also: Troubleshooting — OIDC | docs/auth-oidc.md | Authelia forward-auth (Phase 1)