Bearer Plugin

The Bearer Plugin provides Bearer token authentication by validating JWT access tokens from Authorization headers.

Features

• Authorization Header Validation: Extracts and validates Authorization: Bearer <token> headers
• JWT Integration: Uses the JWT plugin service for token validation
• Dual Authentication Modes: Required authentication (returns 401) or optional authentication (silent)
• Cooperative Authentication: Works alongside other auth plugins without conflicts
• Configurable Header: Customize the header name (default: Authorization)

Standalone Mode

[plugins.bearer]
enabled = true
header_name = "Authorization"  # Customizable header name

Library Mode

To use the plugin programmatically, instantiate it as part of the plugins array when creating a new Authula instance:

bearerplugin.New(bearerplugin.BearerPluginConfig{
	Enabled:    true,
	HeaderName: "Authorization", // optional, defaults to "Authorization"
}),

Available Hooks

Authentication Flow

Request with Header
       │
       ▼
┌───────────────┐
│ Authorization	│
│ Bearer <token>│
└──────┬────────┘
       │
       ▼
┌──────────────┐
│ Extract      │
│ Token        │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ JWT Service  │
│ Validation   │
└──────┬───────┘
       │
   ┌───┴───┐
   │       │
   ▼       ▼
┌─────┐ ┌────────┐
│Valid│ │Invalid │
│     │ │        │
└──┬──┘ └──┬─────┘
   │       │
   ▼       ▼
Set ID   401
in ctx   Error

Flow Description

1. Header Extraction: The plugin extracts the Authorization header from the request and parses the Bearer token format.

2. Token Validation: The extracted token is validated using the JWT service, which verifies the signature, expiration, and blacklist status.

3. Success Path: Valid tokens result in the UserID being set in the request context, allowing the request to proceed.

4. Failure Path: Invalid or expired tokens return a 401 Unauthorized response with an appropriate error message.

How to Use

Enable Bearer authentication on routes by adding the appropriate hook ID to route metadata:

Required Authentication (returns 401 if no valid token):

[[route_mappings]]
path = "/api/protected"
method = "GET"
plugins = ["bearer.auth"]

Optional Authentication (works whether authenticated or not):

[[route_mappings]]
path = "/api/public"
method = "GET"
plugins = ["bearer.auth.optional"]

Client Request Format

Clients must send JWT access tokens in the Authorization header using the Bearer scheme:

Authorization: Bearer eyJhbGciOiJFZERTQSJ9...

Cooperative Authentication

The bearer plugin implements cooperative authentication - if a request already has a UserID set by another authentication plugin (e.g., Session), the bearer plugin will skip its validation. This allows multiple auth methods to work together seamlessly.

Dependencies

• JWT Plugin: Required - the bearer plugin validates tokens using the JWT service
• JWT Service: Must be registered in the service registry by the JWT plugin

Security Features

• Strict Format Validation: Enforces proper Bearer <token> format
• JWT Validation: Leverages the JWT plugin's comprehensive token validation (signature, expiration, blacklist)
• Clear Error Messages: Returns descriptive 401 errors for debugging
• No Token Storage: Stateless validation - no server-side session storage required