traefik_webfinger

README

Traefik WebFinger Plugin

A Traefik middleware plugin that implements the WebFinger Protocol (RFC 7033) for service discovery.

Features

• Full WebFinger protocol support according to RFC 7033
• Static resource configuration
• Domain-based resource filtering
• Optional passthrough to backend services
• Support for multiple resource types (acct:, https://, mailto:)
• Configurable aliases and links
• JRD+JSON response format

Installation

To configure the WebFinger plugin in your Traefik instance:

1. Enable the plugin in your static configuration:

# Static configuration
experimental:
  plugins:
    webfinger:
      moduleName: github.com/NX211/traefik-webfinger
      version: v0.1.0

1. Configure the middleware in your dynamic configuration:

# Dynamic configuration
http:
  middlewares:
    my-webfinger:
      plugin:
        webfinger:
          domain: "example.com"
          resources:
            "acct:user@example.com":
              subject: "acct:user@example.com"
              aliases:
                - "https://example.com/user"
              links:
                - rel: "http://webfinger.net/rel/profile-page"
                  type: "text/html"
                  href: "https://example.com/user"
                - rel: "self"
                  type: "application/activity+json"
                  href: "https://example.com/users/user"
          passthrough: false

1. Use the middleware in your router:

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      middlewares:
        - my-webfinger

Configuration

Plugin Configuration Options

Option	Type	Required	Default	Description
domain	string	Yes	""	The domain this WebFinger service handles
resources	map	No	{}	Map of WebFinger resources and their responses
passthrough	bool	No	false	Whether to pass through to backend when resource not found

Resource Configuration

Each resource in the resources map can have the following properties:

Property	Type	Required	Description
subject	string	Yes	The resource identifier
aliases	[]string	No	Alternative identifiers for the resource
links	[]Link	No	Related links for the resource

Link Configuration

Each link in the links array can have:

Property	Type	Required	Description
rel	string	Yes	The link relation type
type	string	No	The content type of the linked resource
href	string	No	The URL of the linked resource
titles	map[string]string	No	Titles in different languages
properties	map[string]string	No	Additional properties

Example Usage

Basic Configuration

http:
  middlewares:
    webfinger:
      plugin:
        webfinger:
          domain: "example.com"
          resources:
            "acct:alice@example.com":
              subject: "acct:alice@example.com"
              aliases:
                - "https://example.com/alice"
              links:
                - rel: "http://webfinger.net/rel/profile-page"
                  type: "text/html"
                  href: "https://example.com/alice"

Making Requests

To query a WebFinger resource:

curl "https://example.com/.well-known/webfinger?resource=acct:alice@example.com"

Example response:

{
  "subject": "acct:alice@example.com",
  "aliases": [
    "https://example.com/alice"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/alice"
    }
  ]
}

Development

To build and test the plugin:

# Run tests
go test ./...

# Build the plugin
go build ./...

Local Development

For local development, you can use Traefik's plugin development mode:

# Static configuration
experimental:
  localPlugins:
    webfinger:
      moduleName: github.com/NX211/traefik-webfinger

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Documentation

Overview

Package traefik_webfinger implements a Traefik middleware for handling WebFinger requests.

Index

• Variables
• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Config
  • func CreateConfig() *Config
• type WebFinger
  • func (w *WebFinger) ServeHTTP(responseWriter http.ResponseWriter, req *http.Request)
• type WebFingerLink
• type WebFingerResponse

Variables

var (
	ErrDomainRequired      = errors.New("domain must be specified")
	ErrResourceDomainMatch = errors.New("resource does not match configured domain")
	ErrSubjectRequired     = errors.New("subject is required for resource")
	ErrRelRequired         = errors.New("rel is required for links in resource")
)

Define static errors.

Functions

func New

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

New creates a new WebFinger middleware plugin.

Types

type Config

type Config struct {
	// The domain this WebFinger service is responsible for
	Domain string `json:"domain,omitempty" yaml:"domain"`
	// Default resources and their links
	Resources map[string]WebFingerResponse `json:"resources,omitempty" yaml:"resources"`
	// Whether to pass through to the backend service if resource not found
	Passthrough bool `json:"passthrough,omitempty" yaml:"passthrough"`
}

Config defines the plugin configuration structure.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates a new default plugin configuration.

type WebFinger

type WebFinger struct {
	// contains filtered or unexported fields
}

WebFinger is the middleware plugin implementation.

func (*WebFinger) ServeHTTP

func (w *WebFinger) ServeHTTP(responseWriter http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.

type WebFingerLink

type WebFingerLink struct {
	Rel        string            `json:"rel"`
	Type       string            `json:"type,omitempty"`
	Href       string            `json:"href,omitempty"`
	Titles     map[string]string `json:"titles,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
}

WebFingerLink represents a link in the WebFinger response.

type WebFingerResponse

type WebFingerResponse struct {
	Subject string          `json:"subject"`
	Aliases []string        `json:"aliases,omitempty"`
	Links   []WebFingerLink `json:"links,omitempty"`
}

WebFingerResponse represents the WebFinger JSON response according to RFC 7033.