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.
Likes
Bookmarks