luizfonseca/traefik-github-oauth-server repository overview

⁠Traefik GitHub OAuth Plugin

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://<traefik-github-oauth-server-host>/oauth/redirect

2. Run the Traefik GitHub OAuth server

   docker run -d --name traefik-github-oauth-server \
     --network <traefik-proxy-network> \
     -e 'GITHUB_OAUTH_CLIENT_ID=<client-id>' \
     -e 'GITHUB_OAUTH_CLIENT_SECRET=<client-secret>' \
     -e 'API_BASE_URL=http://<traefik-github-oauth-server-host>' \
     -l 'traefik.http.services.traefik-github-oauth-server.loadbalancer.server.port=80' \
     -l 'traefik.http.routers.traefik-github-oauth-server.rule=Host(`<traefik-github-oauth-server-host>`)' \
     luizfonseca/traefik-github-oauth-server
   

   Copy

3. Install the Traefik GitHub OAuth plugin

   Add this snippet in the Traefik Static configuration

   experimental:
     plugins:
       github-oauth:
         moduleName: "github.com/luizfonseca/traefik-github-oauth-plugin"
         version: <version>
   

   Copy

4. Run your App

   docker run -d --whoami test \
     --network <traefik-proxy-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
   

   Copy

⁠Configuration

⁠Server configuration

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

# The base URL of the Traefik GitHub OAuth server
apiBaseUrl: http://<traefik-github-oauth-server-host>
# 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⁠ 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⁠.
  • 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⁠