https://github.com/luizfonseca/traefik-github-oauth-plugin
Lightweight Traefik middleware plugin that enable users to authenticate on specific domains using GitHub OAuth
https://github.com/luizfonseca/traefik-github-oauth-plugin
docker-swarm golang traefik traefik-plugin
Last synced: 3 months ago
JSON representation
Lightweight Traefik middleware plugin that enable users to authenticate on specific domains using GitHub OAuth
- Host: GitHub
- URL: https://github.com/luizfonseca/traefik-github-oauth-plugin
- Owner: luizfonseca
- License: mit
- Created: 2023-11-27T10:19:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-07T09:29:56.000Z (3 months ago)
- Last Synced: 2025-04-07T10:29:57.686Z (3 months ago)
- Topics: docker-swarm, golang, traefik, traefik-plugin
- Language: Go
- Homepage: https://plugins.traefik.io/plugins/65646fb989090d725bcb75b7/git-hub-o-auth-plugin
- Size: 16.3 MB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Traefik GitHub OAuth Plugin
> This is a fork of [MuXiu1997](https://github.com/MuXiu1997/traefik-github-oauth-plugin) repository. This fork is mostly fixing some of the security concerns I wanted to address. This will be kept synced with the main repo.
This is a Traefik middleware plugin that allows users to authenticate using GitHub OAuth.
The plugin is intended to be used as a replacement for the BasicAuth middleware,
providing a more secure way for users to access protected routes.
## Quick Start (Docker)
1. Create a GitHub OAuth App
- See: https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app
- Set the Authorization callback URL to `http:///oauth/redirect`
2. Run the Traefik GitHub OAuth server
```sh
docker run -d --name traefik-github-oauth-server \
--network \
-e 'GITHUB_OAUTH_CLIENT_ID=' \
-e 'GITHUB_OAUTH_CLIENT_SECRET=' \
-e 'API_BASE_URL=http://' \
-l 'traefik.http.services.traefik-github-oauth-server.loadbalancer.server.port=80' \
-l 'traefik.http.routers.traefik-github-oauth-server.rule=Host(``)' \
luizfonseca/traefik-github-oauth-server
```
3. Install the Traefik GitHub OAuth plugin
Add this snippet in the Traefik Static configuration
```yaml
experimental:
plugins:
github-oauth:
moduleName: "github.com/luizfonseca/traefik-github-oauth-plugin"
version:
```
4. Run your App
```sh
docker run -d --whoami test \
--network \
--label 'traefik.http.middlewares.whoami-github-oauth.plugin.github-oauth.apiBaseUrl=http://traefik-github-oauth-server' \
--label 'traefik.http.middlewares.whoami-github-oauth.plugin.github-oauth.whitelist.logins[0]=luizfonseca' \
--label 'traefik.http.middlewares.whoami-github-oauth.plugin.github-oauth.whitelist.teams[0]=827726' \
--label 'traefik.http.routers.whoami.rule=Host(`whoami.example.com`)' \
--label 'traefik.http.routers.whoami.middlewares=whoami-github-oauth' \
traefik/whoami
```
## Configuration
### Server configuration
| Environment Variable | Description | Default | Required |
|------------------------------|-------------------------------------------------------------------------------|---------|----------|
| `GITHUB_OAUTH_CLIENT_ID` | The GitHub OAuth App client id | | Yes |
| `GITHUB_OAUTH_CLIENT_SECRET` | The GitHub OAuth App client secret | | Yes |
| `GITHUB_OAUTH_SCOPES` | Additional scopes to be added to the Oauth workflow. | | No |
| `API_BASE_URL` | The base URL of the Traefik GitHub OAuth server | | Yes |
| `API_SECRET_KEY` | The api secret key. You can ignore this if you are using the internal network | | No |
| `SERVER_ADDRESS` | The server address | `:80` | No |
| `DEBUG_MODE` | Enable debug mode and set log level to debug | `false` | No |
| `LOG_LEVEL` | The log level, Available values: debug, info, warn, error | `info` | No |
You can append `_FILE` to any of the environment variable names to load the value from a file.
E.g. `GITHUB_OAUTH_CLIENT_SECRET_FILE=/run/secrets/github_oauth_client_SECRET` where the content of the file `/run/secrets/github_oauth_client_SECRET` will be used as the environment variable.
### Middleware Configuration
```yaml
# The base URL of the Traefik GitHub OAuth server
apiBaseUrl: http://
# The api secret key. You can ignore this if you are using the internal network
apiSecretKey: optional_secret_key_if_not_on_the_internal_network
# The path to redirect to after the user has authenticated, defaults to /_auth
# Note: This path is not GitHub OAuth App's Authorization callback URL
authPath: /_auth
# optional jwt secret key, if not set, the plugin will generate a random key
jwtSecretKey: optional_secret_key
# optional jwt expiration in hours, defaults to 24 hours
jwtExpirationInHours: 24
# The log level, defaults to info
# Available values: debug, info, warn, error
logLevel: info
# whitelist
whitelist:
# The list of GitHub user ids that are whitelisted to access the resources
ids:
- 996
# The list of GitHub user logins that are whitelisted to access the resources
logins:
- luizfonseca
# The list of Github Teams that are whitelisted to access the resources
teams:
- 988772
```
### OAuth Configuration
For the OAuth configuration, you need to create a GitHub OAuth App.
You can follow the steps in the [GitHub documentation](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to create it and obtain the `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET` values.
#### OAuth Scopes
- For `ids` and `logins` you don't need extra scopes.
- For `teams` you might need to request the `read:org` scope from the user. See the [documentation](https://docs.github.com/en/rest/teams/teams?apiVersion=2022-11-28#list-teams-for-the-authenticated-user).
- You can do so by updating the `GITHUB_OAUTH_SCOPES` environment variable with the desired additional scopes, e.g. `GITHUB_OAUTH_SCOPES="read:org"` via the **Server Configuration**.
## License
[MIT](./LICENSE)