google_oidc_auth_middleware

package module

v0.2.0 Latest Latest Go to latest Published: Jul 10, 2025 License: Apache-2.0 Imports: 17 Imported by: 0

README ¶

Traefik Google OIDC Auth Middleware

This is a Traefik middleware plugin that authenticates users with Google OpenID Connect, and then checks that their email address or Google Workspace domain is authorized.

Requirements

Setup a new project in the Google API console to obtain a client ID and client secret. See the Google developer docs.
Install the plugin to Traefik using static config.
Configure the middleware in dynamic config.
Associate a service to the middleware.

Configuration

Option	Default	Required	Description
oidc.clientID		X	OAuth client ID
oidc.clientSecret		X	OAuth client secret
oidc.callbackPath	/oidc/callback		The path where the OIDC provider will redirect the user after authenticating.
oidc.prompt			A space-delimited, case-sensitive list of prompts to present the user. Possible values are: `none`, `consent`, `select_account`. See Google's docs for more info.
cookie.name	oidc_auth		Name of the cookie. It can be customized to avoid collisions when running multiple instances of the middleware.
cookie.path	/		You can use this to limit the scope of the cookie to a specific path. Defaults to '/'.
cookie.secret		X	Secret is the HMAC key for cookie signing, and helps provide integrity protection for cookies.
cookie.duration	24h		Validity period for new cookies. Users are granted access for this length of time regardless of changes to user's account in the OIDC provider. Uses the Go time.Duration format.
cookie.insecure	false		Set to true to omit the `Secure` attribute from cookies.
authorized.emails		X	List of allowed email addresses.
authorized.domains		X	List of allowed domains.
debug	false		Enable debug logging to stdout.

Headers

X-Forwarded-User

When the middleware proxies a request it adds an X-Fowarded-User header containing the user's email address. This can be used by the downstream service to identify the authenticated user.

If you want your JSON access logs to include the user's email address then configure the access log to retain the X-Forwarded-User header. Here is a CLI example:

# Adding X-Forwarded-User to JSON access logs.
--accesslog
--accesslog.format=json
--accesslog.fields.headers.names.X-Forwarded-User=keep

The resulting access log will contain a request_X-Forwarded-User field.

    "request_X-Forwarded-User": "name@gmail.com"

See Limiting the Fields/Including Headers for more details.

Example config

Static config

# traefik.yml

experimental:
  plugins:
    google-oidc-auth-middleware:
      moduleName: "github.com/andrewkroh/google-oidc-auth-middleware"
      # Populate this with the latest release tag.
      version: vX.Y.Z

Dynamic config

# dynamic.yml

http:
  middlewares:
    oidc-auth:
      plugin:
        google-oidc-auth-middleware:
          oidc:
            clientID: example.apps.googleusercontent.com
            clientSecret: fake-secret
          cookie:
            secret: mySecretKey
          authorized:
            emails:
              - name@gmail.com
            domains:
              - example.com
  routers:
    my-router:
      rule: host(`localhost`)
      service: service-foo
      entryPoints:
        - web
      middlewares:
        - oidc-auth

Documentation ¶

Index ¶

func New(_ context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
type AuthCookie
- func (c *AuthCookie) Base64() string
- func (c *AuthCookie) Expired() bool
type AuthorizedConfig
type CSRFCookie
- func (c *CSRFCookie) Base64() string
- func (c *CSRFCookie) Expired() bool
type Config
- func CreateConfig() *Config
type CookieConfig
type OIDCConfig

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func New ¶

func New(_ context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New created a new Google OIDC auth middleware plugin.

Types ¶

type AuthCookie ¶

type AuthCookie struct {
	ExpiresUnixSec int64  `json:"exp"`
	Email          string `json:"email"`
	Domain         string `json:"domain,omitempty"`
}

AuthCookie represents the data stored in the requestor's cookie jar to authenticate future requests.

func (*AuthCookie) Base64 ¶

func (c *AuthCookie) Base64() string

func (*AuthCookie) Expired ¶

func (c *AuthCookie) Expired() bool

type AuthorizedConfig ¶

type AuthorizedConfig struct {
	Emails  []string // List of allowed email addresses.
	Domains []string // List of allowed domains.
}

type CSRFCookie ¶

type CSRFCookie struct {
	ExpiresUnixSec int64  `json:"exp"`
	Nonce          string `json:"nonce"`
	RedirectURL    string `json:"url"` // URI to redirect the user after authenticating.
}

func (*CSRFCookie) Base64 ¶

func (c *CSRFCookie) Base64() string

func (*CSRFCookie) Expired ¶

func (c *CSRFCookie) Expired() bool

type Config ¶

type Config struct {
	OIDC       OIDCConfig
	Cookie     CookieConfig
	Authorized AuthorizedConfig
	Debug      bool // Enable debug logging to stdout.
}

Config the plugin configuration.

func CreateConfig ¶

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type CookieConfig ¶

type CookieConfig struct {
	Name     string // Name of the cookie. It can be customized to avoid collisions when running multiple instances of the middleware.
	Path     string // You can use this to limit the scope of the cookie to a specific path. Defaults to '/'.
	Secret   string // Secret is the HMAC key and helps provide integrity protection for cookies.
	Duration string // Validity period for new cookies. Users are granted access for this length of time regardless of changes to user's account in the OIDC provider.
	Insecure bool   // Only set this if you are using HTTP.
	// contains filtered or unexported fields
}

type OIDCConfig ¶

type OIDCConfig struct {
	// The OAuth Client ID from the provider for OIDC roles.
	ClientID string

	// The OAuth Client Secret from the provider for OIDC roles.
	ClientSecret string

	// The path where the OIDC provider will redirect user after authenticating.
	CallbackPath string

	// Prompt is an optional, space-delimited, case-sensitive list of prompts to
	// present the user. If you don't specify this parameter, the user will be
	// prompted only the first time your project requests access.
	// Possible values are: 'none', 'consent', 'select_account'.
	Prompt string
}

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL