OIDC

Overview

The oidc middleware provides OpenID Connect authentication, extending OAuth 2.0 with standardized identity tokens and user information endpoints. Use it when you need:

Enterprise SSO integration
Standardized identity claims
ID token validation

Installation

import "github.com/go-mizu/mizu/middlewares/oidc"

Quick Start

app := mizu.New()

// Configure OIDC provider
provider, _ := oidc.NewProvider("https://accounts.google.com")

config := oidc.Config{
    Provider:     provider,
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
    RedirectURL:  "http://localhost:3000/callback",
    Scopes:       []string{"openid", "email", "profile"},
}

app.Get("/login", oidc.Login(config))
app.Get("/callback", oidc.Callback(config, handleUser))

Configuration

Config

Field	Type	Description
`Provider`	`*Provider`	OIDC provider
`ClientID`	`string`	Client ID
`ClientSecret`	`string`	Client secret
`RedirectURL`	`string`	Callback URL
`Scopes`	`[]string`	Requested scopes

Examples

Google OIDC

provider, _ := oidc.NewProvider("https://accounts.google.com")

config := oidc.Config{
    Provider:     provider,
    ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
    ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
    RedirectURL:  "http://localhost:3000/auth/callback",
    Scopes:       []string{"openid", "email", "profile"},
}

app.Get("/auth/login", oidc.Login(config))
app.Get("/auth/callback", oidc.Callback(config, func(c *mizu.Ctx, claims *oidc.Claims) error {
    // claims.Subject - User ID
    // claims.Email - User email
    // claims.Name - User name
    return c.Redirect(302, "/dashboard")
}))

Auth0

provider, _ := oidc.NewProvider("https://your-tenant.auth0.com/")

config := oidc.Config{
    Provider:     provider,
    ClientID:     os.Getenv("AUTH0_CLIENT_ID"),
    ClientSecret: os.Getenv("AUTH0_CLIENT_SECRET"),
    RedirectURL:  "http://localhost:3000/callback",
    Scopes:       []string{"openid", "email", "profile"},
}

Keycloak

provider, _ := oidc.NewProvider("https://keycloak.example.com/realms/myrealm")

config := oidc.Config{
    Provider:     provider,
    ClientID:     "my-app",
    ClientSecret: os.Getenv("KEYCLOAK_SECRET"),
    RedirectURL:  "http://localhost:3000/callback",
    Scopes:       []string{"openid", "email", "roles"},
}

Token Validation Middleware

verifier := oidc.NewVerifier(provider, oidc.VerifierConfig{
    ClientID: "your-client-id",
})

// Protect routes with ID token
app.Use(oidc.Verify(verifier))

app.Get("/api/me", func(c *mizu.Ctx) error {
    claims := oidc.GetClaims(c)
    return c.JSON(200, claims)
})

API Reference

Functions

// NewProvider creates OIDC provider from issuer URL
func NewProvider(issuer string) (*Provider, error)

// Login starts OIDC flow
func Login(config Config) mizu.Handler

// Callback handles OIDC callback
func Callback(config Config, handler func(*mizu.Ctx, *Claims) error) mizu.Handler

// Verify creates ID token verification middleware
func Verify(verifier *Verifier) mizu.Middleware

// GetClaims returns claims from context
func GetClaims(c *mizu.Ctx) *Claims

Standard Claims

type Claims struct {
    Subject           string   // sub
    Issuer            string   // iss
    Audience          []string // aud
    Email             string   // email
    EmailVerified     bool     // email_verified
    Name              string   // name
    PreferredUsername string   // preferred_username
    Picture           string   // picture
    ExpiresAt         time.Time
}

Technical Details

Token Verification Process

The OIDC middleware implements a comprehensive JWT token verification process:

Token Extraction: Tokens are extracted from the Authorization header using the Bearer scheme by default. A custom TokenExtractor function can be provided for alternative extraction methods (e.g., from query parameters or cookies).
Token Structure Validation: The token is split into three parts (header, payload, signature) and validated for correct JWT format.
Header Decoding: The JWT header is decoded to extract the algorithm (alg), key ID (kid), and token type (typ).
Claims Decoding: The payload is decoded into standard OIDC claims including issuer, subject, audience, expiration, and custom claims.
Validation Checks:
- Issuer Validation: Verifies the token was issued by the expected OIDC provider
- Audience Validation: Ensures the token is intended for this application (supports both string and array audiences)
- Expiration Check: Validates the token has not expired using the exp claim
- Not Before Check: Validates the token is valid using the nbf claim if present
Context Storage: Validated claims are stored in the request context for downstream handlers to access via GetClaims().

Claims Structure

The middleware supports both standard OIDC claims and custom claims:

Standard Claims: iss, sub, aud, exp, iat, nbf, email, name
Authorization Claims: groups, roles, scope
Raw Claims: All claims are also stored in a Raw map for accessing custom provider-specific claims

Authorization Helpers

Three specialized middleware functions provide fine-grained access control:

RequireGroup: Validates the user belongs to a specific group (checks groups claim)
RequireRole: Validates the user has a specific role (checks roles claim)
RequireScope: Validates the token includes a specific OAuth scope (checks space-delimited scope claim)

Error Handling

The middleware provides customizable error handling through the OnError callback:

Default Behavior: Returns a 401 Unauthorized JSON response with error details
Custom Handler: Can be configured to log errors, return custom responses, or redirect to login

Path Skipping

The SkipPaths option allows certain routes to bypass authentication (e.g., health checks, public endpoints) while keeping the middleware globally applied.

Best Practices

Use OIDC discovery (/.well-known/openid-configuration)
Validate ID tokens for security
Store only necessary claims in sessions
Implement proper logout with end_session_endpoint
Configure appropriate RefreshInterval for JWKS key rotation
Use SkipPaths for public endpoints instead of conditional middleware application
Implement custom OnError handlers for security-sensitive logging
Leverage RequireGroup, RequireRole, and RequireScope for authorization

Testing

The OIDC middleware includes comprehensive test coverage for various scenarios:

Test Case	Description	Expected Behavior
`TestNew`	Basic middleware initialization without token	Returns 401 Unauthorized
`TestWithValidToken`	Valid token with correct issuer, audience, and expiration	Returns 200 OK, claims accessible via GetClaims
`TestExpiredToken`	Token with expiration time in the past	Returns 401 Unauthorized
`TestInvalidIssuer`	Token with incorrect issuer claim	Returns 401 Unauthorized
`TestInvalidAudience`	Token with incorrect audience claim	Returns 401 Unauthorized
`TestSkipPaths`	Configured paths that bypass authentication	Skipped paths return 200 OK without token, protected paths require token
`TestCustomTokenExtractor`	Custom token extraction from query parameters	Successfully authenticates using token from query string
`TestCustomOnError`	Custom error handler configuration	Returns custom error response (403 Forbidden)
`TestClaimsHasAudience`	String and array audience validation	Correctly identifies audience in both string and array formats
`TestClaimsHasGroup`	Group membership validation	Correctly identifies user group membership
`TestClaimsHasRole`	Role membership validation	Correctly identifies user role membership
`TestRequireGroup`	Group-based authorization middleware	Allows access with required group, denies without (403 Forbidden)
`TestRequireScope`	Scope-based authorization middleware	Allows access with required scope, denies without (403 Forbidden)
`TestInvalidToken`	Malformed token format	Returns 401 Unauthorized

oauth2 - OAuth 2.0 authentication
jwt - JWT validation
session - Session management

Overview

Authentication

Security

Rate Limiting & Resilience

Request Processing

Response Processing

Caching

URL Handling

Networking & Proxy

Request Context

Real-time

Static Files

Operations & Monitoring

Advanced

Connection & Protocol

Internationalization

External Integrations

Bot & Client Detection

Overview

Installation

Quick Start

Configuration

Config

Examples

Google OIDC

Auth0

Keycloak

Token Validation Middleware

API Reference

Functions

Standard Claims

Technical Details

Token Verification Process

Claims Structure

Authorization Helpers

Error Handling

Path Skipping

Best Practices

Testing

​Overview

​Installation

​Quick Start

​Configuration

​Config

​Examples

​Google OIDC

​Auth0

​Keycloak

​Token Validation Middleware

​API Reference

​Functions

​Standard Claims

​Technical Details

​Token Verification Process

​Claims Structure

​Authorization Helpers

​Error Handling

​Path Skipping

​Best Practices

​Testing

​Related Middlewares

Overview

Installation

Quick Start

Configuration

Config

Examples

Google OIDC

Auth0

Keycloak

Token Validation Middleware

API Reference

Functions

Standard Claims

Technical Details

Token Verification Process

Claims Structure

Authorization Helpers

Error Handling

Path Skipping

Best Practices

Testing

Related Middlewares