Bearer Plugin

Overview

The Bearer plugin provides Bearer token authentication by validating JWT access tokens from the configured request header. It extracts tokens in the Bearer <token> format, validates them using the JWT plugin service, and sets UserID in the request context for downstream authorization.

Features

• Authorization Header Validation — Extracts and validates Authorization: Bearer <token> headers or a custom header.
• JWT Integration — Validates token signature, expiration, and blacklist state through the JWT plugin service.
• Required and Optional Modes — Supports bearer.auth for required auth and bearer.auth.optional for optional auth.
• Cooperative Authentication — Skips validation when another auth plugin already populated UserID.
• Configurable Header — Custom header name support with header_name.
• Stateless Validation — No session storage or persistent state is required.

Configuration

Standalone Mode

[plugins.bearer]
enabled = true
header_name = "Authorization"

Library Mode

import (
	bearerplugin "github.com/Authula/authula/plugins/bearer"
)

bearerplugin.New(bearerplugin.BearerPluginConfig{
	Enabled:    true,
	HeaderName: "Authorization",
})

API Reference

This plugin doesn't expose any HTTP endpoints.

Database Schema

This plugin doesn't create any database tables.

Plugin Capabilities

The Bearer plugin provides the following hooks:

• bearer.auth — Required authentication hook. Validates the Bearer token and returns 401 Unauthorized if the token is missing or invalid.
• bearer.auth.optional — Optional authentication hook. Validates the Bearer token if present and silently continues if missing or invalid.

Standalone Mode

[[route_mappings]]
paths = ["GET:/protected"]
plugins = ["bearer.auth"]

[[route_mappings]]
paths = ["GET:/public"]
plugins = ["bearer.auth.optional"]

Library Mode

import (
	authulaconfig "github.com/Authula/authula/config"
	authulamodels "github.com/Authula/authula/models"
	bearerplugin "github.com/Authula/authula/plugins/bearer"
)

config := authulaconfig.NewConfig(
	authulaconfig.WithRouteMappings([]authulamodels.RouteMapping{
		{
			Paths:   []string{"GET:/protected"},
			Plugins: []string{bearerplugin.HookIDBearerAuth.String()},
		},
		{
			Paths:   []string{"GET:/public"},
			Plugins: []string{bearerplugin.HookIDBearerAuthOptional.String()},
		},
	}),
)

Security Recommendations

• Use HTTPS for all requests to protect the Authorization header and bearer token.
• Ensure the JWT plugin is enabled and registered before using the Bearer plugin.
• Use bearer.auth for routes that require authenticated access and bearer.auth.optional for routes that may accept both authenticated and anonymous requests.
• Keep access tokens short-lived and validate them on every request.
• If you use token blacklisting, pair the Bearer plugin with the JWT plugin and Secondary Storage plugin.

Troubleshooting

• 401 Unauthorized on a protected route usually means the token is missing, malformed, expired, or the header name does not match header_name.
• If valid tokens are not recognized, confirm the request header uses the Bearer scheme exactly: Authorization: Bearer <token>.
• If another auth plugin already sets UserID, the Bearer plugin will skip validation, which may affect route behavior if route mappings are misconfigured.

Notes

• The Bearer plugin is stateless and does not persist authentication state.
• It is intended to be used with the JWT plugin because token validation depends on the JWT service.
• Cooperative authentication allows Bearer to operate alongside session-based or other auth plugins without conflicting.