Setting Up a WebFinger Server

WebFinger is designed to be a very simple protocol that allows for automated service discovery. Further, it was designed so that any domain owner could run his or her own WebFinger server.

It is possible to run a WebFinger server using software that provides the required JSON Resource Descriptor (JRD) dynamically, such as retrieving link relations from a database. It is also possible in some cases to run a WebFinger without any special software. Below, we will provide a sample configuration so you can run WebFinger on Apache without the need for any additional software.

WebFinger Server Software

If you wish to set up your own WebFinger server, you can download the WebFinger and Host Metadata Server from Packetizer. Complete documentation for the server can be found in the docs/ directory of the compressed archive.

Additional WebFinger server software is listed separately.

WebFinger without WebFinger Server Software

As we mentioned above, it is possible to return WebFinger responses on a site that runs no WebFinger server software. Here, we will document how you can set up your own server using nothing more than Apache configuration files.

Also, Alexander Grüneberg has provided information for a similar configuration using nginx to implement WebFinger.

Handling Requests to /.well-known/webfinger

The first thing to do is create the directory /.well-known/ at the root of your web server's document directory. Clients will query for webfinger information using the URL https://example.com/.well-known/webfinger.

Next, we need to tell Apache how to resolve the webfinger requests. To do that, create this .htaccess file and put it in the .well-known directory. (If not using .htaccess files, then you may not even need the .well-known directory for WebFinger, but you might need it for other services.)

# Re-write rules
RewriteEngine On

RewriteCond %{REQUEST_URI}  /\.well-known/webfinger$
RewriteCond %{QUERY_STRING} resource=([^&]+)
RewriteRule ^(.*)$ /wf/%1.json [L]

RewriteRule ^/.well-known/webfinger$ - [L,R=400]

This .htaccess file does several things. It turns on the rewrite engine to tell Apache to rewrite the requested URLs to return documents from /wf/ if the "resource" parameter is present in the request URL (for example, http://example.com/.well-known/webfinger?resource=acct:bob@example.com). If the resource parameter is present, the rewrite engine serves only to convert queries to serve files from /wf/ where the file names in the /wf/ directory are the names of the resources with a .json file extension. If the resource parameter is missing, the server returns 400.

Serving Files from the /wf/ Directory

Next, create a directory called "wf" (or whatever you prefer) in the the document root of your web server to hold the JRD documents for the resources that will be queried. Here is an example of a file named "acct:bob@example.com.json" stored in /wf/:

{
  "subject" : "acct:bob@example.com",
  "links" :
  [
    {
      "rel" : "http://webfinger.net/rel/avatar",
      "type" : "image/jpeg",
      "href" : "http://www.example.com/~bob/bob.jpg"
    },
    {
      "rel" : "http://packetizer.com/rel/businesscard",
      "type" : "text/vcard",
      "href" : "http://www.example.com/~bob/bob.vcf"
    },
    {
      "rel" : "http://webfinger.net/rel/profile-page",
      "href" : "http://www.example.com/~bob/"
    },
    {
      "rel" : "http://packetizer.com/rel/blog",
      "href" : "http://blogs.example.com/bob/"
    }
  ]
}

Next, we should ensure that the files from the /wf/ directory are served by the web server properly. So, if using .htaccess files, put this one in place:

AddType application/json;qs=0.5 .json
Header set Access-Control-Allow-Origin "*"

Optimizing Apache Configuration

Placing .htacess files in directories is less optimal than having everything in the main httpd.conf configuration file. To use that file to configure Apache for static sites, a virtual host entry might contain configuration lines similar to what is shown below:

<VirtualHost *:80>

    ...

    <Directory /path/to/wf/>
        AddType application/json;qs=0.5 .json
        AllowOverride None
        Order allow,deny
        Allow from all
        Header set Access-Control-Allow-Origin "*"
    </Directory>

    # Re-write rules
    RewriteEngine On

    RewriteCond %{REQUEST_URI}  /\.well-known/webfinger$
    RewriteCond %{QUERY_STRING} resource=([^&]+)
    RewriteRule ^(.*)$ /wf/%1.json [L]

    RewriteRule ^/.well-known/webfinger$ - [L,R=400]

    ...

</VirtualHost>

Acknowledgements

Christian Weiske provided the proposed approach using URL rewriting and multiviews to allow WebFinger to work on static web sites.