Packetizer

WebFinger


WebFinger Logo

WebFinger (RFC 7033) is a REST-based web service used to discover information about people and other addressable entities on the Internet.

WebFinger servers return a JSON document as a response to a valid query. The JSON document is referred to as a JSON Resource Descriptor (JRD) document. The structure of the document is simple, providing the querying client with a list of link relations, properties, and other information about the subject being queried.

End users publish information about themselves through an account, such as a social network account or a corporate directory. The service provider or enterprise maintaining the account would then publish the information about the user marked for publication via WebFinger. It is then possible for other users to retrieve that information from within the applications they use. As an example, a user might publish his name, address, phone number, and picture via WebFinger. This information could then appear automatically in an email client used by another user.

WebFinger may be used for discovering other kinds of information about a host or domain. It is certainly not limited to discovering information about human users. For example, it could be used to discover the information required to properly configure an email client or to determine the physical location of a printer or other device on the network.

The WebFinger Resource

WebFinger servers allow clients to query for information using a single well-known resource location, namely:

/.well-known/webfinger

Security Considerations

As with many services on the Internet, especially those that might convey important user-specific information, it is strongly desirable to utilize TLS. WebFinger clients and servers are therefore required to utilize TLS exclusively for communication.

Protocol Example

A typical exchange with a WebFinger server looks like the following. First, a client queries the domain related to the users account (say, acct:bob@example.com):

GET /.well-known/webfinger?resource=acct%3Abob%40example.com HTTP/1.1
Host: example.com

In response, the server might reply with a JRD like this:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jaon; charset=UTF-8

{
  "subject" : "acct:bob@example.com",
  "links" :
  [
    {
      "rel" : "http://webfinger.net/rel/avatar",
      "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/"
    }
  ]
}

With this reply, the requesting client can see the location of Bob’s avatar and could display that for the user. There is also a link to Bob’s vCard, which might contain contact information (e.g., address, phone number) that could be processed and provided to the user.

More Complex Example

In the previous section, we looked at a very simple document that contained only link relations. It is also possible to return documents that contain aliases and properties related to the document, as well as types, titles and properties related to individial link relations.

Here is a more complete example that uses every feature in the JRD document. Even this is rather simple and easy to understand:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jaon; charset=UTF-8

{
  "subject" : "acct:bob@example.com",
  "aliases" :
  [
    "http://www.example.com/~bob/"
  ],
  "properties" :
  {
    "http://packetizer.com/ns/name" : "Bob Q. Smith"
  },
  "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",
      "type" : "text/html",
      "href" : "http://blogs.example.com/bob/",
      "titles" :
      {
        "en-us" : "The Magical World of Bob",
        "fr" : "Le Monde Magique de Bob"
      }
    },
    {
      "rel" : "http://packetizer.com/rel/smtp-server",
      "properties" :
      {
        "http://packetizer.com/ns/host" : "smtp.example.com",
        "http://packetizer.com/ns/port" : "587",
        "http://packetizer.com/ns/login-required" : "yes",
        "http://packetizer.com/ns/transport" : "starttls"
      }
    },
    {
      "rel" : "http://packetizer.com/rel/imap-server",
      "properties" :
      {
        "http://packetizer.com/ns/host" : "imap.example.com",
        "http://packetizer.com/ns/port" : "993",
        "http://packetizer.com/ns/transport" : "ssl"
      }
    }
  ]
}

In this example, you can see much of the same information as the previous example. However, we also introduced titles for the blog and indicated the expected media types related to the link relations. There are also link relations that do not have an "href", namely "smtp-server" and "imap-server". Those link relations only have "properties" that would tell Bob's email client what hostnames, ports, and transports to use when connecting to his company's mail server.

JSON Resource Descriptor Format

You can read the complete JRD syntax specification here.

Common Link Relations and Properties

There are an infinite number of link relations and properties that might be defined for use with webFinger. We have created a table of link relations and a table of properties, documenting those that appear to have gained some popularity.

Setting up your own WebFinger Server or Using a WebFinger Service Provider

If you want to set up your own WebFinger server, we provide instructions, source code, etc.

For those who want to use a service provider to host their WebFinger service We also document how you can configure the Apache web server to direct WebFinger queries to a third-party WebFinger service provider.

There are a number of WebFinger client and server software packages available that you may wish to utilize.

Have Comments or Questions?

Feel free to post comments or questions in the Packetizer Forums area established for WebFinger.