Traefik-Forward-Auth (sentry authorization)

---
title: Traefik Forward Auth middleware handles authentication
---
sequenceDiagram
participant User
participant Traefik
participant TFA as TFA middleware
participant Forgejo as Oauth2 provider - Forgejo
participant HeaderAuth as Sentry authorization middleware
participant App

User ->> Traefik: HTTP request
Traefik ->> TFA: Sends the request to TFA middleware
TFA ->> Forgejo: OAuth2 authentication
Forgejo -->> TFA: OAuth2 response (returns OK / KO)
TFA -->> Traefik: Returns OK / KO
alt KO
    Traefik ->> User: KO, access denied
else OK
    Traefik -->> User: OK, logged in
    User -->> Traefik: Send new requests with auth cookie.
end
Traefik ->> HeaderAuth: Send cookie token in trusted header for verification
HeaderAuth ->> Traefik: Returns OK / KO
alt KO
    Traefik ->> User: KO, Returns error
else OK
    Traefik -->> App: OK, Forwards trusted connection to backend app container
    App -->> Traefik: OK, App returns response
    Traefik -->> User: OK, app returns response
end

Sentry authorization

Some apps may already have their own authentication mechanisms, while others may not. Sentry authorization creates a common authentication and authorization framework in front of your applications via Traefik middleware. Sentry authorization happens before any existing auth mechanisms in the app itself, and so it acts as a front door gatekeeper for your apps. It can’t control what users are allowed to do once they get in, but it does control who is allowed in through the front door.

  • Users are authenticated via the Forgejo instance and traefik-forward-auth.
  • Users are authorized by a group membership filter applied on a per-app basis.

Configure traefik-forward-auth

Run this on the Raspberry Pi
pi make traefik-forward-auth config
(stdout)
TRAEFIK_FORWARD_AUTH_HOST: Enter the traefik-foward-auth host domain name (eg. auth.example.com)

: auth.pi.example.com

TRAEFIK_FORWARD_AUTH_COOKIE_DOMAIN: Enter the cookie domain name (ie ROOT domain) (eg. example.com)

: pi.example.com

? Select the OAuth provider to use
> gitea
  github
  google
  discord

TRAEFIK_FORWARD_AUTH_GITEA_DOMAIN: Enter your gitea domain name (eg. git.example.com)

: git.pi.example.com

At this point it will open w3m to the gitea instance asking you to sign in. Because this isn’t very user friendly, so just press q and then y to quit w3m.

  • Open your preffered web browser and open up the gitea URL: https://git.pi.example.com
  • Make sure you are logged in as the root user.
  • Open the root user settings page, click Applications.
  • Fill in the section titled Manage OAuth2 applications:
    • Enter an application name as a public identifier.
    • Enter the redirect URI https:://auth.pi.example.com/_oauth.
  • Click Create Application.
  • This will show you the OAuth2 client ID and secret:

Back in your terminal session, it should be asking you to fill these same details in:

(stdout)
TRAEFIK_FORWARD_AUTH_PROVIDERS_GENERIC_OAUTH_CLIENT_ID: Copy and Paste the OAuth2 client ID here

: 38d6c7f7-c712-43a9-967c-27888819e85f

TRAEFIK_FORWARD_AUTH_PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET: Copy and Paste the OAuth2 client secret here

: gto_4g54tazy7oyslypqhr7z7khundcmtwezlkdeyghe7ctj7k4gltvq

TRAEFIK_FORWARD_AUTH_LOGOUT_REDIRECT: Enter the logout redirect URL

: https://git.pi.example.com/logout

Install Traefik-Forward-Auth

Run this on the Raspberry Pi
pi make traefik-forward-auth install

Add a new route on the sentry

Run this on your Raspberry Pi
sentry route set pi auth.pi.example.com
Tip

You may also create the route interactively through the Traefik config menu.

Add user groups for sentry authorization

With OAuth2 sentry authorization enabled, users are authorized to access apps only if they are a member of an authorized group for that app. You need to create the group membership lists in the Traefik config:

Run this on the Raspberry Pi
pi make traefik config
(stdout)
? Traefik:
> Config
  Install (make install)
  Admin
  Exit (ESC)

? Traefik Configuration:
  Traefik user
  Entrypoints (including dashboard)
  TLS certificates and authorities
> Middleware (including sentry auth)
  Advanced Routing (Layer 7 / Layer 4 / Wireguard)
  Error page template
v Logging level

? Traefik middleware config:
  MaxMind geoIP locator
> OAuth2 sentry authorization (make sentry)

? Sentry Authorization Manager (main menu):
> Group Manager
  User Manager
  List all members
  List authorized callback URLs
  Quit

> Sentry Authorization Manager (main menu): Group Manager
? Choose a group to manage
> Create a new group

? Enter the name of the group to create: admin

> Do you want to add users to this group now? Yes

Enter the new user id(s) to add, one per line:
? Enter a user ID (Press Esc or enter a blank value to finish)  me@example.com
Tip

Replace me@example.com with the same email address that you used to sign up for your personal account in Forgejo. You can add more users to the group if you wish, when done enter a blank line.

Re-configure whoami with sentry authorization (OAuth2)

Run this on the Raspberry Pi
pi make whoami config
(stdout)
WHOAMI_TRAEFIK_HOST: Enter the whoami domain name (eg. whoami.example.com)

: whoami.pi.example.com

? Do you want to enable sentry authorization in front of this app (effectively making the entire site private)?
  No
  Yes, with HTTP Basic Authentication
> Yes, with Oauth2
  Yes, with Mutual TLS (mTLS)

? Which authorization group do you want to permit access to this app?
> admin
Tip

This will allow only the admin authorization group to access this instance.

Remember, you can create extra authorization groups in the Traefik config, that way you can have separate user access per instance.

Re-install whoami:

Run this on the Raspberry Pi
pi make whoami install

Test login for whoami

Open the whoami app in your web browser: https://whoami.pi.example.com.

You should be automatically redirected to the Foregjo app to login.

The first time a Forgejo user authenticates to a sentry authorization protected app, they should see this prompt:

Confirm by clicking the button Authorize Application.

If the user is authorized, they should be automatically redirected back to the whoami app.

The output of whoami now reflects the authorized user:

(stdout)
Name: default
Hostname: c863ccd86cec
IP: 127.0.0.1
IP: ::1
IP: 172.19.0.2
RemoteAddr: 172.19.0.1:38606
GET / HTTP/1.1
Host: whoami.pi.example.com
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:127.0) Gecko/20100101 Firefox/127.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.5
Cookie: _forward_auth=xxxxxxxxxxxxxxxxxxxxxxxxxxx=|123456789|me@example.com
Dnt: 1
Priority: u=1
Sec-Fetch-Dest: document
Sec-Fetch-Mode: navigate
Sec-Fetch-Site: same-site
Sec-Fetch-User: ?1
Te: trailers
Upgrade-Insecure-Requests: 1
X-Forwarded-For: 192.168.1.1
X-Forwarded-Host: whoami.pi.example.com
X-Forwarded-Port: 443
X-Forwarded-Proto: https
X-Forwarded-Server: pi
X-Forwarded-User: me@example.com
X-Real-Ip: 192.168.1.1

The request shows the new details:

  • Cookie the cookie value is set by the traefik-forward-auth middleware once the user is successfully authenticated.
  • The X-Forwarded-User is passed to the application to identify the validated user id (email address).

Reconfigure other apps to use OAuth2

All other apps may be protected with sentry authorization in the same manner as whoami.