Traefik OpenID Connect Middleware

A traefik Plugin for securing the upstream service with OpenID Connect acting as a relying party.

Note

This document always represents the latest version, which may not have been released yet. Therefore, some features may not be available currently but will be available soon. You can use the GIT-Tags to check individual versions.

Warning

This middleware is under active development and breaking changes may occur. It is only tested against traefik v3+.

Tested Providers

Provider	Status	Notes
ZITADEL	✅
Kanidm	✅	See GH-12
Keycloak	✅
Microsoft EntraID	✅
HashiCorp Vault	❌	See GH-13
Authentik	✅
Pocket ID	✅
GitHub	❌	GitHub doesn't seem to support OIDC, only plain OAuth.

📚 Documentation

Please see the full documentation HERE.

Note

The documentation is being built from the production branch, representing the latest released version. If you want to check the documentation of the main branch to see whats comming in the next version, see here.

🧪 Local Development and Testing

This project uses a Taskfile for easy access to commonly used tasks. You need to install the Taskfile CLI by following the official documentation. You also need Docker installed on your machine.

You can then run the following command to list all available tasks:

task --list

The easiest way to get started is to run the plugin with Keycloak because this repo comes with a pre-configured instance. Just do:

1. Run task run:keycloak and wait a moment for everything to be settled
2. Open a web browser and navigate to http://localhost:9080
3. You will be redirected to Keycloak's login page. Log in with user admin and password admin.

If you want to start the plugin with your own identity provider, create the following .env file in workspaces/external-idp:

PROVIDER_URL=...
CLIENT_ID=...
CLIENT_SECRET=...
VALIDATE_AUDIENCE=true

And then do:

1. Run task run:external
2. Open a web browser and navigate to http://localhost:9080
3. You will be redirected to your own identity provider

If you want to play around with the plugin config, modify the file workspaces/configs/http.yml. Changes will be reloaded automatically and you should see some debug output in the container logs.