Forward discovery of an actor document given a WebFinger address

Given a username and hostname in the form user@domain:

1. Construct an acct: URI of the form acct:user@domain (as defined in [[RFC7565]])
2. Make an HTTP GET request to that hostname's WebFinger well-known endpoint, using the acct: URI as the value of the resource query parameter (as described in [[RFC7033]])

For example, the WebFinger address alyssa@social.example can be resolved as a resource by making an HTTP GET request for https://social.example/.well-known/webfinger?resource=acct:alyssa@social.example (which is https://social.example/.well-known/webfinger?resource=acct:alyssa%40social.example when percent-encoded). This request MAY result in an HTTP 3xx redirect, in which case the redirect MUST be followed to the Location header's value, which MUST be an https: URI per [[RFC7033]]. (Subsequent redirects SHOULD be followed, up until a maximum redirect limit at the discretion of the requester.) The final request MUST return a JRD (JSON Resource Descriptor, as defined in [[RFC6415]]) with application/jrd+json as the content type (assuming no specified Accept header).

The WebFinger request and response may look like this:

GET /.well-known/webfinger?resource=acct:alyssa%40social.example HTTP/1.1
Host: social.example

HTTP/1.1 307 Temporary Redirect
Location: https://social.example/jrd/alyssa

GET /jrd/alyssa HTTP/1.1
Host: social.example

HTTP/1.1 200 OK
Content-Type: application/jrd+json

{
  "subject": "acct:alyssa@social.example",
  "aliases": [
    "https://social.example/@alyssa",
    "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://social.example/@alyssa"
    },
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://social.example/actors/9c5b94b1-35ad-49bb-b118-8e8fc24abf80"
    }
  ]
}

At this point, you can parse for the href of the element of links that has a rel of self and a type of either application/ld+json; profile="https://www.w3.org/ns/activitystreams" or application/activity+json (depending on the implementation). See for more information about this.

Reverse discovery of a WebFinger address given an actor document

Given an actor with an id and a preferredUsername:

1. Take the hostname of the id to discover the WebFinger domain
2. Combine the preferredUsername and the WebFinger domain in order to form a WebFinger address
3. Verify that this WebFinger address links back to the same actor when performing discovery as described in
4. Optionally: If the JRD from the previous step has a subject and it contains an acct: URI different from the one you constructed, perform a verification discovery against that acct: URI afterward. (In such cases, the subject of the JRD denotes the expected canonical identifier.)

For example, given an actor document at https://activitypub.example.com/actor/1 like so:

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "id": "https://activitypub.example.com/actor/1",
  "preferredUsername": "alice",
  "name": "Alice P. Hacker"
}

The reverse discovery process would extract alice and activitypub.example.com, construct the acct: URI acct:alice@activitypub.example.com, then request https://activitypub.example.com/.well-known/webfinger?resource=acct:alice@activitypub.example.com like so:

GET /.well-known/webfinger?resource=acct:alice@activitypub.example.com HTTP/1.1
Host: activitypub.example.com

HTTP/1.1 200 OK
Content-Type: application/jrd+json

{
  "subject": "acct:alice@example.com",
  "aliases": [
    "https://example.com/@alice",
    "https://activitypub.example.com/actors/1"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@alice"
    },
    {
      "rel": "self",
      "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"",
      "href": "https://activitypub.example.com/actors/1"
    }
  ]
}

At this point, we have validated that alice@activitypub.example.com links back to our actor document, but we can optionally verify that the canonical WebFinger address of alice@example.com also links back to the same actor document:

GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1
Host: example.com

HTTP/1.1 307 Temporary Redirect
Location: https://activitypub.example.com/.well-known/webfinger?resource=acct:alice@example.com

GET /.well-known/webfinger?resource=acct:alice@example.com HTTP/1.1
Host: activitypub.example.com

HTTP/1.1 200 OK
Content-Type: application/jrd+json

{
  "subject": "acct:alice@example.com",
  "aliases": [
    "https://example.com/@alice",
    "https://activitypub.example.com/actors/1"
  ],
  "links": [
    {
      "rel": "http://webfinger.net/rel/profile-page",
      "type": "text/html",
      "href": "https://example.com/@alice"
    },
    {
      "rel": "self",
      "type": "application/ld+json; profile=\"https://www.w3.org/ns/activitystreams\"",
      "href": "https://activitypub.example.com/actors/1"
    }
  ]
}