145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# Auth0
|
|
|
|
A clean, secure, and reusable Auth0 authentication module for Go web applications using **Chi** router.
|
|
|
|
This module provides everything you need to add Auth0-based login/logout to your Chi-based application:
|
|
|
|
- `/login` — Redirects user to Auth0 Universal Login
|
|
- `/callback` — Handles Auth0 redirect, verifies ID token, stores user profile & access token in session
|
|
- `/logout` — Clears session and redirects to Auth0 logout (full single sign-out)
|
|
- Authentication middleware — Protects routes, redirects unauthenticated users to login
|
|
- `CurrentUser(r *http.Request)` helper — Retrieve authenticated user claims in handlers
|
|
|
|
## Features
|
|
|
|
- Secure OAuth2/OIDC flow with state validation and CSRF protection
|
|
- Clean functional options pattern for dependency injection
|
|
- Easy-to-use middleware for protected routes
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get github.com/derekmwright/go-web/auth/auth0
|
|
```
|
|
|
|
(Replace with your actual repo path when published)
|
|
|
|
## Usage
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"log"
|
|
"net/http"
|
|
|
|
"github.com/go-chi/chi/v5"
|
|
"github.com/yourusername/go-auth0-chi"
|
|
// your session manager, e.g. gorilla/sessions, scollett/chi-sessions, etc.
|
|
)
|
|
|
|
func main() {
|
|
r := chi.NewRouter()
|
|
|
|
// Your session manager (must implement auth0.SessionManager interface)
|
|
sessionManager := NewYourSessionManager() // e.g. cookie store
|
|
|
|
// Your logger (zap, zerolog, etc. — must implement auth0.Logger)
|
|
logger := NewYourLogger()
|
|
|
|
// Initialize the Auth0 module
|
|
registerRoutes, requireAuth, err := auth0.New(
|
|
auth0.WithLogger(logger),
|
|
auth0.WithSessions(sessionManager),
|
|
)
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
// Mount the auth routes (usually under root or /auth)
|
|
registerRoutes(r)
|
|
|
|
// Public routes
|
|
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
|
|
w.Write([]byte("Home page — public"))
|
|
})
|
|
|
|
// Protected routes
|
|
r.Group(func(r chi.Router) {
|
|
r.Use(requireAuth) // ← enforces authentication
|
|
|
|
r.Get("/dashboard", func(w http.ResponseWriter, r *http.Request) {
|
|
user := auth0.CurrentUser(r)
|
|
// user is map[string]any with Auth0 claims (sub, name, email, etc.)
|
|
w.Write([]byte("Welcome to the dashboard!"))
|
|
})
|
|
|
|
r.Get("/profile", func(w http.ResponseWriter, r *http.Request) {
|
|
profile := auth0.CurrentUser(r).(map[string]any)
|
|
// Render profile...
|
|
})
|
|
})
|
|
|
|
log.Println("Server starting on :8080")
|
|
http.ListenAndServe(":8080", r)
|
|
}
|
|
```
|
|
|
|
## Routes Added
|
|
|
|
When you call `registerRoutes(r)`, the following routes are registered:
|
|
|
|
| Route | Method | Purpose |
|
|
|-------------|--------|---------|
|
|
| `/login` | GET | Initiates login: generates state, stores in session, redirects to Auth0 |
|
|
| `/callback` | GET | Auth0 redirect URI: validates state, exchanges code, verifies ID token, stores user & access token in session, redirects to `/` |
|
|
| `/logout` | GET | Clears session and redirects to Auth0 `/v2/logout` with proper `returnTo` and `client_id` (full SSO logout) |
|
|
|
|
You can mount these under a subrouter if preferred:
|
|
|
|
```go
|
|
authRouter := chi.NewRouter()
|
|
registerRoutes(authRouter)
|
|
r.Mount("/auth", authRouter) // → /auth/login, /auth/callback, etc.
|
|
```
|
|
|
|
## Required Environment Variables
|
|
|
|
The module reads Auth0 configuration from environment variables:
|
|
|
|
```env
|
|
AUTH0_DOMAIN=your-tenant.auth0.com
|
|
AUTH0_CLIENT_ID=your-client-id
|
|
AUTH0_CLIENT_SECRET=your-client-secret
|
|
AUTH0_REDIRECT_URI=http://localhost:8080/callback
|
|
```
|
|
|
|
Make sure `AUTH0_REDIRECT_URI` is listed in your Auth0 Application → **Allowed Callback URLs**.
|
|
|
|
Also add your post-logout URL (e.g. `http://localhost:8080/`) to **Allowed Logout URLs** in the Auth0 dashboard.
|
|
|
|
## Dependencies Injected
|
|
|
|
You must provide:
|
|
|
|
- `Logger` — with `Debug`, `Info`, `Error` methods (easy to adapt zap, zerolog, log/slog, etc.)
|
|
- `SessionManager` — with `Get(ctx, key)` and `Put(ctx, key, value)` (compatible with gorilla/sessions, etc.)
|
|
|
|
## Session Storage
|
|
|
|
The module stores:
|
|
|
|
- `"user"` → `map[string]any` with decoded ID token claims (sub, name, email, picture, etc.)
|
|
- `"access_token"` → raw access token string (useful for calling APIs)
|
|
|
|
You can extend this as needed in your own handlers.
|
|
|
|
## Testing
|
|
|
|
The module is designed for easy testing — all dependencies are interfaces. See the `_test.go` files for examples using mocks.
|
|
|
|
## License
|
|
|
|
MIT
|
|
|