Year: 2022

I really enjoyed Aaron Parecki’s post explaining the changes during the 2020 season, and thought I’d write my own this time using the same format. I’ve been heavily involved in the update, but Aaron is heavily embedded in the OAuth world to a degree I’m not, and may have more insights I hope he gets a chance to blog about.

Many of the changes bring IndieAuth closer to OAuth 2.0, ensuring that an OAuth client could support IndieAuth with a minimum of changes.

• New Metadata Discovery Method
• Server Issuer Identifier
• Refresh Tokens
• New Revocation Endpoint
• New Token Introspection Endpoint
• New User Info Endpoint
• Clarifications Around Profile

Metadata Discovery

The first thing an IndieAuth client does is discover the user’s endpoints and redirect the user to their server to authorize the client.

Previously, the client would look for HTTP Link headers for the authorization and token endpoint. As we continue to expand into new use cases, we need a new way to provide information to clients.

The new metadata object servers publish and clients retrieve not only identifies the location of the various endpoints(some of which are optional), but what the capabilities are of the endpoints.

Changes for Clients: Clients must check for a HTTP Link header or an HTML link element with a rel-value of indieauth-metadata. For the foreseeable future, clients should, for backward compatibility, still look for the authorization_endpoint and token_endpoint rel values.

Changes for Servers: The server has to publish the link values for the client to find, and at that URL return a JSON object with properties containing information about the various endpoints. You may wish to place it in the .well-known path, for compatibility with other OAuth 2.0 implementions, but this is not a requirement.

Issuer Identifier

In order to positively identify differing IndieAuth server, each one will now have a server identifier, indicated by the issuer parameter.  It is a prefix of the URL where the Server Metadata endpoint is.

This can now be checked to protect against attacks, as IndieAuth clients interact with multiple servers.

Changes for Clients: Clients must now check that the issuer identifer returned from the authorization endpoint is valid and matches the one provided in Server Metadata.

Changes for Servers: When the authorization endpoint builds the redirect back to the client it will include the issuer identifier. The issuer identifier will be provided through the new metadata endpoint.

Refresh Tokens

Refresh tokens are something were always permitted in IndieAuth, but people didn’t know it was an option because it wasn’t described.

Changes for Clients: Clients should note whether tokens have an expiry and be prepared to request new tokens using the refresh token process. The new metadata endpoint, if implemented, would advise if a server supported the refresh token grant type. The only negative to not implementing support is that when the token expires, it would be a poor experience for the user to have to reauthenticate.

Changes for Servers: Servers are not required to implement short-lived tokens and refresh tokens. But if they choose to, they would have to support the refresh_token grant type in order to allow clients to get new tokens when one expired.

Revocation Endpoint

The previous version of the spec overloaded the token endpoint to provide revocation with the action=revoke parameter.

Changes for Clients: Clients should support discovering the new endpoint through the server metadata endpoint and utilizing it.

Changes for Servers: Servers may wish to support the old revocation method for backward compatibility for the foreseeable future, but should implement the new endpoint.

Token Introspection Endpoint

This new version introduces the token introspection endpoint, discoverable through the new metadata endpoint. This replaces the previous token verification process with one based on the OAuth 2 Token Introspection process. This means also a change to the response.

The major difference between this method and the prior one is that the previous method was a GET request, this is a POST, and requires some form of authentication.

Changes for Clients: None….the token verification is meant to be done by resource servers, such as a micropub endpoint if not coupled with the IndieAuth endpoints. Some clients may have been using the verification process, and must remove this.

Changes for Servers: The introspection endpoint is also optional. The old GET option may be retained for a time, but it is best to discontinue as soon as possible as the previous verification endpoint was not meant to be used by clients.

New User Info Endpoint

A previous update to the spec added a profile scope and a profile return to the authorization response. This addresses the scenario where a client wishes to refresh that profile information by allowing for an optional user information endpoint, discoverable via the metadata endpoint.

Changes for Clients: Clients supported/using profile information should, if a user information endpoint is available may choose to query it periodically for updated information. This would allow for refreshing avatars and display names automatically.

Changes for Servers: Implementing a userinfo endpoint is, of course optional. In most cases, if you were returning the profile information in the authorization response, it should be relatively easy to add the endpoint.

Clarification of Profile and Its Scope

There were questions regarding the definition of the return values for the profile information, which were clarified in the update, and more significantly, the application of the profile scope…specifically, could you issue a token with only the profile scope and what that would mean.

The language of the previous update made some individuals believe that a token would not be issued if the request contained only the profile scope. This was clarified.

If you need a token, you would redeem your authorization code at the token endpoint…which would allow you to have a token with just a profile scope…which could work well for the new userinfo endpoint. If you don’t need a token, just to know the user logged in, you can do the same redemption at the authorization endpoint.

Change for Clients: This should be addressed as per use case above. Namely, if you need a token vs not needing one.

Changes for Servers: If you implemented this during the prior update, and set it so you could not get a token with a profile only spec, due a misread of the intentions of the specification, you should change this. It shouldn’t affect any client.

One of the stumbling blocks was discovery on this, being distributed, how you can essentially follow people who are participating.

One proposal involved creating a site you log into using IndieAuth and then that would be how you’d join.

I started contemplating simple webmentions. The same way you RSVP to an event…you should be able to create a page for a challenge and have it receive webmentions, which would generate the feed.

So, that is what I’ve been contemplating all afternoon since. The page would work like an old-style planet. A planet is a site that aggregates feeds from a variety of sources with a particular theme or community.

Using webmentions as a publishing avenue is what Brid.gy does. So, there are a few ways I thought this could work.

1. Like the way Brid.gy does it, the post would be marked up with a u-syndication property, which would trigger a webmention to the page, but instead of it being seen as a comment, it would add it as an h-entry in a feed people could follow. To prevent abuse, there could be the same types of vouches/moderation you’d otherwise use. If you wanted to ‘take down’ a post, you’d use the webmention delete method.
2. This would be the same, except using the u-category properties instead of u-syndication. So, why is this a thought? Because you are tagging it, but just linking it to a tag on another site. The argument for this vs u-syndication is that the syndication in this case is entirely at the discretion of the receiver…also it the URL is scoped to the feed, not to the individual post.

In both of these, it seems like a relatively easy thing to have your webmention receiver interpret this markup by generating an h-feed, either of reposts of the post, or a simple feed with just URLs to the individual posts.

This is something that could be easily built into any site that has webmention capabilities with a minimum of additional code.

So, have at it, what am I missing here?

Recently, I came across Geoff Graham’s response on CSS Tricks commenting on another post by Miriam Suzanne on implementing Indieweb technology. I asked to speak to Geoff, who I did not previously know, and did so this past Friday.

Earlier that week, someone I had helped configure their WordPress site at a Homebrew Website Club meeting had decided things were a bit too complicated for them. Whenever that happens, I feel like it is a good time to ask…how can we make this better?

I had some suspicions that Geoff might be confused about a few things, and it would give me a chance to not only explain, but use that to plan how to prevent same in future. This article is also an outgrowth of that.

The CSS Tricks post was in response to Miriam Suzanne…who is using a static site, not WordPress. I’m going to focus purely on WordPress.

The IndieWeb plugin you can get for WordPress was originally conceived as sort of a JetPack for WordPress, but because each piece of the Indieweb infrastructure is independent, it does most of this by being a plugin installer/recommender. And it clearly can do better at explaining its recommendations.

The plugin by itself handles establishing your identity as the IndieWeb sees it. It offers an h-card template and widget. H-Card is the markup for marking up information about a person or place. So, this is an element many people opt to put on their site anyway.

Alternatively, it offers rel-me linking. Rel me is just a way to tell visitors that a link to another site is a link to another version of me.  But, a bunch of links to other profiles is also a common website design measure. Your Twitter URL would be marked up with rel=me, establishing your website and your twitter profile are both the same person. To prove that, your Twitter bio should also point back to your site, otherwise anyone could impersonate you. That’s again, about proving your identity against something verifiable.

Other than a few other behaviors, such as telling the code whether this is a single author or multi-author site, to address differing behaviors, the plugin is as simple as possible, but is a good gateway to more.

If you want to continue to build your identity, it suggests IndieAuth. IndieAuth is a protocol. There’s some confusion about this idea, because indieauth.com is a hosted instance of that protocol that uses rel-me links. but WordPress users don’t need any of that. The WordPress implementation is an entire self-hosted implementation built into your site.

So, what is IndieAuth? IndieAuth is a protocol, based on top of OAuth2. If you haven’t heard of OAuth2, it is what those, Login with Google or Login with Facebook buttons are based on. IndieAuth allows you to log into any site with your URL as your identifier. If you use the WordPress version, you put your URL into an application that supports IndieAuth, and it will redirect to your WordPress instance to authenticate by logging into that, then redirect back to the application. So, for WordPress users, it is really Login with your WordPress site.

A Micropub client is a great example of something you can use IndieAuth to log into. The Micropub plugin adds a Micropub server, or endpoint to your WordPress site. This allows you to use any Micropub client to post to your site. That gives you an infinite number of publishing apps, if, for example, you aren’t thrilled with the built-in WordPress editors.

The Webmentions plugin for WordPress handles the receiving and sending of webmentions. Like the IndieAuth plugin, people often think it requires webmention.io, which is a hosted webmention provider. The WordPress version is entirely self-contained.

Back when it was built, the plugin handled only the business of receiving and sending webmentions, not handling display to any degree. Semantic Linkbacks, a separate plugin handled that for not only webmentions, but the older pingback and trackback protocols.

For the duration of the pandemic, the primary developer and I have been working on a complete reimplementation of the Semantic Linkbacks display code inside the webmentions plugin, and hope to have that done soon, which will eliminate the split(although deprecate support for enhancing pingbacks which wasn’t really happening anyway).

Semantic Linkbacks takes a webmention, which is a notification that another site has linked to something on your site, fetches the other site, and tries to render a display of the information. How that is done can vary from just a profile photo(if it can find one), to interpreting it as a full comment.

It does this using Microformats…a way of marking up HTML to allow elements to be identified. It is one of several ways of doing this, but is a very simple and readable one, which is why it is popular in the IndieWeb community.

Being as many themes are not properly marked up, we did try creating a plugin to do this with WordPress hooks and filters…the Microformats plugin…but its ability to do so is limited. Which is why you are likely better off with a properly marked up theme.

Since many people are not inclined, or not comfortable modifying a theme, the new version of Webmentions will include several different alternative ways to try to find an image or summary to display…from OpenGraph(which Facebook and Twitter use to display URLs provided to it) to detecting the WordPress REST API version of a page and using that to get the author name and profile image. None of them will provided as much context as Microformats, but the experience will still be something worth installing.

The other plugins provide other useful functionality for a site interested in taking the place of your participation in social media silos.

A popular goal of members of the IndieWeb community is to syndicate their content to those sites and pull back the interactions to their own websites. However, most people do not want to write integration to the APIs for these sites.

A community member offers Brid.gy as a service for feeding back interactions to syndicated posts from various other sites, by implementing their APIs, and then sending webmentions to your site when someone comments on the syndicated version of your post. The same could be done by implementing the API directly.

Syndication Links helps with syndication by offering a marked up display of links to the syndicated copies of posts. These look similar to the ‘Share with Twitter/Facebook’ buttons many sites have, except they link you directly to the syndicated copy of the post on those sites, instead of implementing tracking or other code in your site.

Brid.gy also offers a service to publish to sites it supports, and Syndication Links optionally leverages a way of triggering that capability, as well as allowing Micropub to trigger it. It supports several other services as well, and may be expanded to more in the future. But if you don’t want this feature, it is actually disabled by default.

Simple Location is one of my geekier projects. It obsessively adds location context to posts on your site. So, add a location to a post, show a map…the weather, etc at that location. It also adds archives and other data. If you are trying to reproduce the experience of Swarm, or other check-in type functionality on your site…add maps to photo posts, etc, that’s what it is for.

But if that isn’t what you want, it’s fine not to install that piece. Because not everyone’s needs are the same.

If you don’t want to learn how to markup individual types of posts(as opposed to your theme) with Microformats, the Post Kinds plugins tries to add the ability to post a reply, like, check-in, etc from your site. It is integrated with the Classic WordPress editor, however, so some may opt out of it.

The IndieWeb implementation on WordPress is a serious of building blocks that you can or cannot choose to use, which is what makes it wonderful, but sometimes confusing. WordPress has a philosophy of decisions, not options. But the IndieWeb is all about options…about building the features that are right for you.

As WordPress users within the IndieWeb community, we can always do a better job of explaining what these things are for, and are happy to do so. We have a live chat, weekly events, and are generally happy to help. But the IndieWeb is not a monolith…we’re a community of people with a common philosophy of using our own websites rather than someone else’s.  That means different things to different people.

I immediately started getting something I haven’t gotten in ages. Pingbacks and Trackbacks.  Now, I spent a time as the Pingbacks and Trackbacks component maintainer for WordPress. I’d very much hoped we could iterate to make these features more than just another ignored piece of WordPress.

Of course, I was more interested in their successor, webmentions, which adopts many of the same principles, but…offers some important changes, most significantly of which, people are still working on it.

In response to the CSS Tricks post, I got 28 pingbacks and trackbacks. I don’t turn them off on my site, because disabling the ability to receive them would also, with the current webmention configuration, disable that too.

But I think I will be adjusting it to immediately remove Trackbacks. Trackbacks have no validation, and I have not ever gotten a legitimate one. WordPress doesn’t allow you to selectively remove one protocol or the other.

Pingbacks, as they do have validation, mean a site actually does have to link to you, not just say it does. But I looked at the quality of those. CSS Tricks seems to have a lot of people republishing its content without attribution.

Some of these, actual WordPress sites, probably running a scraping plugin, don’t even give authorship and the author is set as the admin account. So, not exactly impressive…although one version did seem to be translated into Spanish.

So, does that mean the only sites still sending pingbacks are sites that wholesale copy other content and put it out there? That has a bunch of different problems with it. It makes me ask if I should turn off pingbacks as well as disused by anyone interested in quality content.

There is nothing inherently wrong with reposting content…although I am a big believer in proper attribution. When I post about an article, I usually only share a summary and a link.

So, I hadn’t gotten a pingback in over a year, and when I did, it was notifications of this.

Maybe I will just stick with webmentions and abandon all similar protocols. Eventually, it could in theory have the same problem as pingbacks…namely, less utility. There have been discussions about that from the beginning. But the way that is solved is by iterating. And no one is doing that on pingbacks right now.

I did consider some other choices. I did attend a discussion a few years on different levels of display based on trust. So, an untrusted source, till trusted, unless you prefer moderation, might appear as an additional number displayed in a counter on your post. As it grew in trust, it might add displaying avatars or other information. That might allow me to keep offering the service.

But, unless someone can show me an example of a quality pingback, probably better to shut it down.