Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

A Webfinger extension for Sinatra.

An easy Sinatra extension for adding Webfinger support to your domain.

What is Webfinger?

It's a way to attach information to your email address.

Take an email address, and ask its domain about it using HTTPS. For example, information about is available in JSON at:

See, Paul E. Jones' description, or Webfinger's official standard at RFC 7033 for more information.

Using sinatra-webfinger

sinatra-webfinger is a small Sinatra extension optimized for single users, where you own your domain name, and you want to attach information to your email address.

Install it:

gem install sinatra-webfinger

Require it in your app:

require 'sinatra/webfinger'

If you're using the modular style of Sinatra app, by subclassing Sinatra::Base, make sure to register the extension inside your class:

class MyApp < Sinatra::Base
  register Sinatra::Webfinger

  # of your app ...


Configure sinatra-webfinger by passing the webfinger method a hash where each key is an email address you want to attach details for. The value for each email address is another hash containing name/value pairs of data.

For each field, if its value is a URI beginning with http or https, it will be added to the Webfinger links array, where the field will be the rel and the value will be the href.

Otherwise, the field will be added to the Webfinger properties object, by that key and value.

For example:

webfinger "" => {
  name: "Eric Mill",
  website: ""

This will add a GET endpoint at /.well-known/webfinger? that produces:

  "subject": "",
  "properties": {
    "": "Eric Mill"
  "links": [
      "rel": "",
      "href": ""

In Webfinger, fields are URIs, but you can use common short strings and sinatra-webfinger will convert those to the current best practice URIs for you.

These URIs are defined in urns.yml. Please contribute to it!

Configuration in YAML

It may be easiest to serialize your Webfinger configuration in YAML, then load it into Ruby and pass it to the webfinger method.

An example YAML file for the above example would be:
  name: Eric Mill

If you saved that to webfinger.yml, you might configure your application using:

webfinger YAML.load_file('webfinger.yml')

Behavior of /.well-known/webfinger

The Content-Type of the response will be application/jrd+json, and CORS will be enabled (Access-Control-Allow-Origin will be *).

A 400 will be returned if:

  • There is no resource parameter provided in the query string.
  • There's any sort of Exception while parsing the resource URI.

A 404 will be returned if:

  • A URI scheme other than acct is submitted.
  • A resource is submitted for an acct that isn't listed in the configuration.

A 500 will be returned if:

  • Sinatra::Webfinger.config has not been set to anything.
  • There is any unplanned Exception.

MIT License

This project is published under the MIT License.


Webfinger plugin for Sinatra.







No packages published