Traefik + Authentik + Shelfmark Proxy Authentication

[Jammrock]

How I setup Shelfmark Proxy Authentication with Traefik and Authentik. I suggest performing the steps in this order.

My setup:

• Authentik 2025.12.1
• Traefik 3.6
• Shelfmark 1.0.3
• [optional] Portainer2.33.6 (any Docker compose manager or setup will work)

Authentik

Groups [Optional]

I reused my CWA admin group for Shelfmark. Groups are technically optional, but I use a group so they are part of the guide.

1. Logon to Authentik with a Super User account and go to the Admin Interface.
2. Directory > Groups
3. "New Group" button
4. Enter a "Group Name:" like Shelfmark-Admins
5. All other values are optional
6. Create
7. Click on the newly created group
8. Users tab
9. "Add existing users"
10. Add all user accounts you want to grant Settings/Admin rights in Shelfmark
11. Assign

Application + Provider + Outpost

Proxy authentication needs a Provider tied to an application that is added to the default Outpost for Authentik proxy forward authentication to work.

1. Logon to Authentik with a Super User account and go to the Admin Interface.
2. Applications > Applications
3. Select the "Create with Provider" button.
4. Configure the Application
   a. Application Name: Shelfmark
   b. [auto-populated value is fine] Slug: shelfmark
   c. Policy Engine Mode: ANY
   d. Next
5. Select "Proxy Provider"
6. Next
7. "Configure Proxy Provider"
   a. [Optional] Remove "Provider for " so the provider name matches the Application name. This is my personal preference.
   b. Authorization flow:
   i. Select "Explicit" to require Authentik to prompt the user about sending auth data to Shelfmark
   ii. Select "Implicit" to let Authentik send auth data to Shelfmark without user consent (which is fine for a homelab)
   c. Select "Forward auth (single application)"
   d. External host: https://shelfmark.company.domain
   i. The host is the URL used to access the site from OUTSIDE of Traefik
   ii. shelfmark.company.domain is a placeholder for your Shelfmark URL.
   e. No other settings need to be changed, but "Authentication Settings > Intercept header authentication" must be toggled on (default)
   f. Next
8. [Optional, only needed by those using an admin group] "Bind existing policy/group/user"
   a. Group
   b. Click into the Group text box to get a list of groups
   c. Select your admin group (i.e. Shelfmark-Admins)
   d. Order: 1
   e. Save binding
   f. Next
9. Submit

There will now be an Application named Shelfmark and a Provider named "[Provider for ]Shelfmark".

Application:

Provider:

20. Applications > Outposts
21. Select the Edit icon to the right of the "authentik Embedded Outpost" outpost
22. Select Shelfmark under the left "Available Applications" column
23. Click the single right arrow

24. Shelfmark will appear in the right column when the operation is performed successfully

25. Update

The Authentik setup is now complete!

Traefik

I used a YAML file in a rules dir that Traefik watches rather then adding labels in the Docker compose file. The YAML file can be converted to compose labels or a TOML file.

There can be only one [in a Highlander voice] Shelfmark definition in Traefik. Comment, remove, or adjust any existing labels/definitions before using this configuration.

When using the YAML method, make sure traefik.yaml has a watcher:

  file:
    directory: /etc/traefik/
    watch: true

File [Traefik container path]: /etc/traefik/rules/shelfmark.yaml

Replace:

auth.company.domain with the external URL to your Authentik site.
shelfmark.company.domain with the external URL to your Shelfmark site.
<ip>:<port> with the internal IP address (127.0.0.1 or 192.168.xxx.yyy) and port used by Shelfmark. I recommend testing the URL locally first, and use a known working http-based URL in the loadBalancer config.

http:
    middlewares:
        shelfmark-authentik-mw:
            forwardAuth:
                address: http://auth.company.domain:9000/outpost.goauthentik.io/auth/traefik
                trustForwardHeader: true
                authResponseHeaders:
                    - X-authentik-username
                    - X-authentik-groups
                    - X-authentik-email
                    - X-authentik-name
                    - X-authentik-uid
                    - X-authentik-jwt
                    - X-authentik-meta-jwks
                    - X-authentik-meta-outpost
                    - X-authentik-meta-provider
                    - X-authentik-meta-app
                    - X-authentik-meta-version

    routers:
        default-router-shelfmark:
            rule: "Host(`shelfmark.company.domain`)"
            tls:
              certResolver: azuredns
            entryPoints:
              - websecure
            middlewares:
                - shelfmark-authentik-mw
            priority: 10
            service: shelfmark-lb
        default-router-auth-shelfmark:
            rule: "Host(`shelfmark.company.domain`) && PathPrefix(`/outpost.goauthentik.io/`)"
            priority: 15
            service: shelfmark-auth-svc
    services:
        shelfmark-lb:
            loadBalancer:
                servers:
                    - url: http://<ip>:<port>/
        shelfmark-auth-svc:
            loadBalancer:
                servers:
                    - url: http://auth.company.domain:9000/outpost.goauthentik.io

Testing

Open an Incognito/InPrivate instance of your browser of choice and go to your external Shelfmark site (i.e. https://shelfmark.company.domain).

The backend is configured correctly when you are prompted to authenticate via Authentik before being redirected to Shelfmark.

You will still have access to settings because Shelfmark is not setup yet.

Shelfmark

It's time to setup Proxy Authentication in Shelfmark. These steps include the optional step of enabling an admin group.

1. Open Settings

2. Security
3. Authentication Method: Proxy Authentication
4. Proxy Auth User Header: X-authentik-username
5. Leave Proxy Auth Logout URL blank.

Optional Admin Group Configuration

This step is for those who are granting access to users who you don't trust with Settings access.

1. Settings > Security
2. Toggle on: Restrict Settings to Admins authenticated via Proxy
3. Proxy Auth Admin Group Header: X-authentik-groups
4. Proxy Auth Admin Group Name: <your admins group created in Authentik (i.e. Shelfmark-Admins)>

Testing

When everything is setup correctly, users in the Shelfmark/CWA admins group will have access to Settings once logged on via Authentik. All other users can search and download, but will not have Settings access.

Please test an admin and a normal user before releasing Shelfmark to non-admin users.

[gitnew12]

Asking because I am an idiot; any reason to pick Proxy Authentication over OIDC (OpenID Connect)? For context I am also using Traefik + Authentik stack.

[gitnew12]

Ah was this written before OIDC was implemented in February?