IndieAuth

IndieWeb Living Standard 26 September 2020

This version:
https://indieauth.spec.indieweb.org/
Test suite:
https://indieauth.rocks/
Previous version:
https://indieauth.spec.indieweb.org/20200809/
Editor:
Aaron Parecki
Repository:
Github
Issues
Commits

Please check the errata for any errors or issues reported since publication.


Abstract

IndieAuth is an identity layer on top of OAuth 2.0 [RFC6749], primarily used to obtain an OAuth 2.0 Bearer Token [RFC6750] for use by [Micropub] clients. End-Users and Clients are all represented by URLs. IndieAuth enables Clients to verify the identity of an End-User, as well as to obtain an access token that can be used to access resources under the control of the End-User.

Author's Note

This section is non-normative.

This specification was contributed to the W3C from the IndieWeb community. More history and evolution of IndieAuth can be found on the IndieWeb wiki.

Status of This Document

This document was published by the IndieWeb community as a Living Standard.

Per CC0, to the extent possible under law, the editor(s) and contributors have waived all copyright and related or neighboring rights to this work. In addition, the editor(s) and contributors have made this specification available under the Open Web Foundation Agreement Version 1.0.

1. Introduction

1.1 Background

This section is non-normative.

The IndieAuth spec began as a way to obtain an OAuth 2.0 access token for use by Micropub clients. It can be used to both obtain an access token, as well as authenticate users signing to any application. It is built on top of the OAuth 2.0 framework, and while this document should provide enough guidance for implementers, referring to the core OAuth 2.0 spec can help answer any remaining questions. More information can be found on the IndieWeb wiki.

1.2 OAuth 2.0 Extension

IndieAuth builds upon the OAuth 2.0 [RFC6749] Framework as follows

Additionally, the parameters defined by OAuth 2.0 (in particular state, code, and scope) follow the same syntax requirements as defined by Appendix A of OAuth 2.0 [RFC6749].

2. Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

2.1 Conformance Classes

An IndieAuth implementation can implement one or more of the roles of an IndieAuth server or client. This section describes the conformance criteria for each role.

Listed below are known types of IndieAuth implementations.

2.1.1 Authorization Endpoint

An IndieAuth Authorization Endpoint is responsible for obtaining authentication or authorization consent from the end user and generating and verifying authorization codes.

2.1.2 Token Endpoint

An IndieAuth Token Endpoint is responsible for generating and verifying OAuth 2.0 Bearer Tokens.

2.1.3 Micropub Client

A Micropub client will attempt to obtain an OAuth 2.0 Bearer Token given an IndieAuth profile URL, and will use the token when making Micropub requests.

2.1.4 IndieAuth Client

An IndieAuth client is a client that is attempting to authenticate a user given their profile URL, but does not need an OAuth 2.0 Bearer Token.

3. Identifiers

3.1 User Profile URL

Users are identified by a [URL]. Profile URLs MUST have either an https or http scheme, MUST contain a path component (/ is a valid path), MUST NOT contain single-dot or double-dot path segments, MAY contain a query string component, MUST NOT contain a fragment component, MUST NOT contain a username or password component, and MUST NOT contain a port. Additionally, hostnames MUST be domain names and MUST NOT be ipv4 or ipv6 addresses.

Some examples of valid profile URLs are:

Some examples of invalid profile URLs are:

3.2 Client Identifier

Clients are identified by a [URL]. Client identifier URLs MUST have either an https or http scheme, MUST contain a path component, MUST NOT contain single-dot or double-dot path segments, MAY contain a query string component, MUST NOT contain a fragment component, MUST NOT contain a username or password component, and MAY contain a port. Additionally, hostnames MUST be domain names or a loopback interface and MUST NOT be IPv4 or IPv6 addresses except for IPv4 127.0.0.1 or IPv6 [::1].

3.3 URL Canonicalization

Since IndieAuth uses https/http URLs which fall under what [URL] calls "Special URLs", a string with no path component is not a valid [URL]. As such, if a URL with no path component is ever encountered, it MUST be treated as if it had the path /. For example, if a user enters https://example.com as their profile URL, the client MUST transform it to https://example.com/ when using it and comparing it.

Since domain names are case insensitive, the hostname component of the URL MUST be compared case insensitively. Implementations SHOULD convert the hostname to lowercase when storing and using URLs.

For ease of use, clients MAY allow users to enter just a hostname part of the URL, in which case the client MUST turn that into a valid URL before beginning the IndieAuth flow, by prepending either an http or https scheme and appending the path /. For example, if the user enters example.com, the client transforms it into http://example.com/ before beginning discovery.

4. Discovery

This specification uses the link rel registry as defined by [HTML] for both HTML and HTTP link relations.

4.1 Discovery by Clients

Clients need to discover a few pieces of information when a user signs in. The client needs to discover the user's authorization_endpoint, and optionally token_endpoint if the client needs an access token. When using the Authorization flow to obtain an access token for use at a [Micropub] endpoint, the client will also discover the micropub endpoint.

Clients MUST start by making a GET or HEAD request to [Fetch] the user's profile URL to discover the necessary values. Clients MUST follow HTTP redirects (up to a self-imposed limit). If one or more successive HTTP permanent redirects (HTTP 301 or 308) are encountered starting with the very first request, the client MUST use the final permanent redirection's target URL as the canonical profile URL. If any other redirection (such as HTTP 302, 303, or 307) is encountered, it must still be resolved for endpoint discovery, but this redirection does not modify the canonical profile URL, nor do subsequent permanent redirects.

Clients MUST check for an HTTP Link header [RFC8288] with the appropriate rel value. If the content type of the document is HTML, then the client MUST check for an HTML <link> element with the appropriate rel value. If more than one of these is present, the first HTTP Link header takes precedence, followed by the first <link> element in document order.

The endpoints discovered MAY be relative URLs, in which case the client MUST resolve them relative to the current document URL according to [URL].

Clients MAY initially make an HTTP HEAD request [RFC7231] to follow redirects and check for the Link header before making a GET request.

4.1.1 Redirect Examples

4.1.1.1 http to https

In this example, the user enters example.com in the sign-in form, so the client initially transforms that to http://example.com/ to perform discovery. The URL http://example.com/ returns an HTTP 301 permanent redirect to https://example.com/, so the client updates the initial profile URL to https://example.com/, and looks at the contents of that page to find the authorization endpoint.

4.1.1.2 www to no-www

In this example, the user enters www.example.com in the sign-in form, so the client initially transforms that to http://www.example.com/ to perform discovery. The URL http://www.example.com/ returns an HTTP 301 permanent redirect to https://example.com/, so the client updates the initial profile URL to https://example.com/, and looks at the contents of that page to find the authorization endpoint.

4.1.1.3 Temporary Redirect

In this example, the user enters example.com in the sign-in form, so the client initially transforms that to http://example.com/ to perform discovery. The URL http://example.com/ returns an HTTP 301 permanent redirect to https://example.com/, and https://example.com/ returns an HTTP 302 temporary redirect to https://example.com/username. The client stores the last 301 permanent redirect as the profile URL, https://example.com/, and uses the contents of https://example.com/username to find the authorization endpoint.

4.1.1.4 Permanent Redirect to a Different Domain

In this example, the user enters username.example in the sign-in form, so the client initially transforms that to http://username.example/ to perform discovery. However, the user does not host any content there, and instead that page is a redirect to their profile elsewhere. The URL http://username.example/ returns an HTTP 301 permanent redirect to https://example.com/username, so the client updates the initial profile URL to https://example.com/username when setting the me parameter in the initial request. At the end of the flow, the authorization endpoint will return a me value of https://example.com/username, which is not on the same domain as what the user entered, but the client can accept it because of the HTTP 301 redirect encountered during discovery.

4.1.1.5 Temporary Redirect to a Different Domain

In this example, the user enters username.example in the sign-in form, so the client initially transforms that to http://username.example/ to perform discovery. However, the user does not host any content there, and instead that page is a temporary redirect to their profile elsewhere. The URL http://username.example/ returns an HTTP 302 temporary redirect to https://example.com/username, so the client discovers the authorization endpoint at that URL. Since the redirect is temporary, the client still uses the user-entered http://username.example/ when setting the me parameter in the initial request. At the end of the flow, the authorization endpoint will return a me value of https://username.example/, which is not on the same domain as the authorization endpoint, but is the same domain as the user entered. This allows users to still use a profile URL under their control while delegating the authentication or authorization flow to an external account.

4.2 Client Information Discovery

When an authorization server presents its authorization interface, it will often want to display some additional information about the client beyond just the client_id URL, in order to better inform the user about the request being made. Additionally, the authorization server needs to know the list of redirect URLs that the client is allowed to redirect to.

Since client identifiers are URLs, the authorization server SHOULD [Fetch] the URL to find more information about the client.

4.2.1 Application Information

Clients SHOULD have a web page at their client_id URL with basic information about the application, at least the application's name and icon. This page serves as a good landing page for human visitors, but can also serve as the place to include machine-readable information about the application. The HTML on the client_id URL SHOULD be marked up with [h-app] Microformat to indicate the name and icon of the application. Authorization servers SHOULD support parsing the [h-app] Microformat from the client_id, and if there is an [h-app] with a url property matching the client_id URL, then it should use the name and icon and display them on the authorization prompt.

<div class="h-app">
  <img src="/logo.png" class="u-logo">
  <a href="/" class="u-url p-name">Example App</a>
</div>

This can be parsed with a Microformats2 parser, which will result in the following JSON structure.

{
  "type": [
    "h-app"
  ],
  "properties": {
    "name": ["Example App"],
    "logo": ["https://app.example.com/logo.png"],
    "url": ["https://app.example.com/"]
  }
}

4.2.2 Redirect URL

If a client wishes to use a redirect URL that is on a different domain than their client_id, or if the redirect URL uses a custom scheme (such as when the client is a native application), then the client will need to whitelist those redirect URLs so that authorization endpoints can be sure it is safe to redirect users there. The client SHOULD publish one or more <link> tags or Link HTTP headers with a rel attribute of redirect_uri at the client_id URL.

Authorization endpoints verifying that a redirect_uri is allowed for use by a client MUST look for an exact match of the given redirect_uri in the request against the list of redirect_uris discovered after resolving any relative URLs.

GET / HTTP/1.1
Host: app.example.com

HTTP/1.1 200 Ok
Content-type: text/html; charset=utf-8
Link: <https://app.example.com/redirect>; rel="redirect_uri"

<!doctype html>
<html>
  <head>
    <link rel="redirect_uri" href="/redirect">
  </head>
  ...
</html>

5. Authorization

This section describes how to authenticate users and optionally obtain an access token using the OAuth 2.0 Authorization Code Flow with IndieAuth.

IndieAuth Authorization Flow DiagramBrowserClientUser URLAuthorization EndpointToken EndpointUser enters their profile URLClient fetches URL to discoverrel=authorization_endpointand rel=token_endpointClient builds authorization request andredirects to authorization_endpointUser visits their authorization endpoint and sees the authorization requestAuthorization endpoint fetches client information (name, icon)User authenticates, and approves the request.Authorization endpoint issues code, builds redirect back to client.User's browser is redirected toclient with an authorization codeClient exchanges authorization code for an access token by making a POST requestto the token_endpointToken endpoint verifies code and returnscanonical user profile URL with an access tokenClient initiates login sessionand the user is logged in

Note: If the client is only trying to learn who the user is and does not need an access token, the client exchanges the authorization code for the user profile information at the Authorization Endpoint instead.

5.1 Discovery

After obtaining the End-User's profile URL, the client fetches the URL and looks for the authorization_endpoint and token_endpoint rel values in the HTTP Link headers and HTML <link> tags as described in § 4.1 Discovery by Clients.

Link: <https://example.org/auth>; rel="authorization_endpoint"
Link: <https://example.org/token>; rel="token_endpoint"

<link rel="authorization_endpoint" href="https://example.org/auth">
<link rel="token_endpoint" href="https://example.org/token">

5.2 Authorization Request

The client builds the authorization request URL by starting with the discovered authorization_endpoint URL and adding parameters to the query component.

All IndieAuth clients MUST use PKCE ([RFC7636]) to protect against authorization code injection and CSRF attacks. A non-canonical description of the PKCE mechanism is described below, but implementers should refer to [RFC7636] for details.

Clients use a unique secret per authorization request to protect against authorization code injection and CSRF attacks. The client first generates this secret, which it can later use along with the authorization code to prove that the application using the authorization code is the same application that requested it.

The client first creates a code verifier for each authorization request by generating a random string using the characters [A-Z] / [a-z] / [0-9] / - / . / _ / ~ with a minimum length of 43 characters and maximum length of 128 characters. This value is stored on the client and will be used in the authorization code exchange step later.

The client then creates the code challenge derived from the code verifier by calculating the SHA256 hash of the code verifier and Base64-URL-encoding the result.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

For backwards compatibility, authorization endpoints MAY accept authorization requests without a code challenge if the authorization server wishes to support older clients.

https://example.org/auth?response_type=code&
                          client_id=https://app.example.com/&
                          redirect_uri=https://app.example.com/redirect&
                          state=1234567890&
                          code_challenge=OfYAxt8zU2dAPDWQxTAUIteRzMsoj9QBdMIVEDOErUo&
                          code_challenge_method=S256&
                          scope=profile+create+update+delete&
                          me=https://user.example.net/

The client SHOULD provide the me query string parameter to the authorization endpoint, either the exact value the user entered, or the canonical profile URL resulting from the discovery step.

The authorization endpoint SHOULD fetch the client_id URL to retrieve application information and the client's registered redirect URLs, see Client Information Discovery for more information.

If the URL scheme, host or port of the redirect_uri in the request do not match that of the client_id, then the authorization endpoint SHOULD verify that the requested redirect_uri matches one of the redirect URLs published by the client, and SHOULD block the request from proceeding if not.

It is up to the authorization endpoint how to authenticate the user. This step is out of scope of OAuth 2.0, and is highly dependent on the particular implementation. Some authorization servers use typical username/password authentication, and others use alternative forms of authentication such as [RelMeAuth], or delegate to other identity providers.

The authorization endpoint MAY use the provided me query component as a hint of which user is attempting to sign in, and to indicate which profile URL the client is expecting in the resulting profile URL response or access token response. This is specifically helpful for authorization endpoints where users have multiple supported profile URLs, so the authorization endpoint can make an informed decision as to which profile URL the user meant to identify as. Note that from the authorization endpoint's view, this value as provided by the client is unverified external data and MUST NOT be assumed to be valid data at this stage. If the logged-in user doesn't match the provided me parameter by the client, the authorization endpoint MAY either ignore the me parameter completely or display an error, at the authorization endpoint's discretion.

Once the user is authenticated, the authorization endpoint presents the authorization request to the user. The prompt MUST indicate which application the user is signing in to, and SHOULD provide as much detail as possible about the request, such as information about the requested scopes.

5.2.1 Authorization Response

If the user approves the request, the authorization endpoint generates an authorization code and builds the redirect back to the client.

The redirect is built by starting with the redirect_uri in the request, and adding the following parameters to the query component of the redirect URL:

  • code - The authorization code generated by the authorization endpoint. The code MUST expire shortly after it is issued to mitigate the risk of leaks, and MUST be valid for only one use. A maximum lifetime of 10 minutes is recommended. See OAuth 2.0 Section 4.1.2 for additional requirements on the authorization code.
  • state - The state parameter MUST be set to the exact value that the client set in the request.
HTTP/1.1 302 Found
  Location: https://app.example.com/redirect?code=xxxxxxxx
                                             state=1234567890

Upon the redirect back to the client, the client MUST verify that the state parameter in the request is valid and matches the state parameter that it initially created, in order to prevent CSRF attacks. The state value can also store session information to enable development of clients that cannot store data themselves.

See OAuth 2.0 [RFC6749] Section 4.1.2.1 for how to indicate errors and other failures to the user and client.

5.3 Redeeming the Authorization Code

Once the client has obtained an authorization code, it can redeem it for an access token or the user's final profile URL.

5.3.1 Request

If the client needs an access token in order to make requests to a resource server such as a [Micropub] endpoint, it can exchange the authorization code for an access token and the user's profile URL at the token endpoint.

If the client only needs to know the user who logged in and does not need to make requests to resource servers with an access token, the client exchanges the authorization code for the user's profile URL at the authorization endpoint.

After the client validates the state parameter, the client makes a POST request to the token endpoint or authorization endpoint to exchange the authorization code for the final user profile URL and/or access token. The POST request contains the following parameters:

  • grant_type=authorization_code
  • code - The authorization code received from the authorization endpoint in the redirect.
  • client_id - The client's URL, which MUST match the client_id used in the authentication request.
  • redirect_uri - The client's redirect URL, which MUST match the initial authentication request.
  • code_verifier - The original plaintext random string generated before starting the authorization request.
Example request to authorization endpoint
POST https://example.org/auth
  Content-type: application/x-www-form-urlencoded
  Accept: application/json

  grant_type=authorization_code
  &code=xxxxxxxx
  &client_id=https://app.example.com/
  &redirect_uri=https://app.example.com/redirect
  &code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5
Example request to token endpoint
POST https://example.org/token
Content-type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code
&code=xxxxxxxx
&client_id=https://app.example.com/
&redirect_uri=https://app.example.com/redirect
&code_verifier=a6128783714cfda1d388e2e98b6ae8221ac31aca31959e59512c59f5

Note that for backwards compatibility, the authorization endpoint MAY allow requests without the code_verifier. If an authorization code was issued with no code_challenge present, then the authorization code exchange MUST NOT include a code_verifier, and similarly, if an authorization code was issued with a code_challenge present, then the authorization code exchange MUST include a code_verifier.

5.3.2 Profile URL Response

When the client receives an authorization code that was requested with either no scope or only profile scopes (defined below), the client will exchange the authorization code at the authorization endpoint, and only the canonical user profile URL and possibly profile information is returned.

The authorization endpoint verifies that the authorization code is valid, has not yet been used, and that it was issued for the matching client_id and redirect_uri, and checks that the provided code_verifier hashes to the same value as given in the code_challenge in the original authorization request. If the request is valid, then the endpoint responds with a JSON [RFC7159] object containing the property me, with the canonical user profile URL for the user who signed in, and optionally the property profile with the user's profile information as defined in Profile Information.

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

  {
    "me": "https://user.example.net/"
  }

The resulting profile URL MAY be different from the canonical profile URL as resolved by the client, but MUST be on the same domain. This gives the authorization endpoint an opportunity to canonicalize the user's URL, such as correcting http to https, or adding a path if required. See Redirect Examples for an example of how a service can allow a user to enter a URL on a domain different from their resulting me profile URL, and see Differing User Profile URLs for security considerations client developers should be aware of.

See OAuth 2.0 [RFC6749] Section 5.2 for how to respond in the case of errors or other failures.

5.3.3 Access Token Response

When the client receives an authorization code that was requested with one or more scopes that will result in an access token being returned, the client will exchange the authorization code at the token endpoint.

The token endpoint needs to verify that the authorization code is valid, and that it was issued for the matching client_id and redirect_uri, contains at least one scope, and checks that the provided code_verifier hashes to the same value as given in the code_challenge in the original authorization request. If the authorization code was issued with no scope, the token endpoint MUST NOT issue an access token, as empty scopes are invalid per Section 3.3 of OAuth 2.0 [RFC6749].

The specifics of how the token endpoint verifies the authorization code are out of scope of this document, as typically the authorization endpoint and token endpoint are part of the same system and can share storage or another private communication mechanism.

If the request is valid, then the token endpoint can generate an access token and return the appropriate response. The token response is a JSON [RFC7159] object containing the OAuth 2.0 Bearer Token [RFC6750], as well as a property me, containing the canonical user profile URL for the user this access token corresponds to, and optionally the property profile with the user's profile information as defined in Profile Information. For example:

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

{
  "access_token": "XXXXXX",
  "token_type": "Bearer",
  "scope": "create update delete",
  "me": "https://user.example.net/"
}

The resulting profile URL MAY be different from the canonical profile URL as resolved by the client, but MUST be on the same domain. This provides the opportunity to canonicalize the user's URL, such as correcting http to https, or adding a path if required. See Redirect Examples for an example of how a service can allow a user to enter a URL on a domain different from their resulting me profile URL.

See OAuth 2.0 [RFC6749] Section 5.2 for how to respond in the case of errors or other failures.

5.3.4 Profile Information

Requesting Profile Information

If the client would like to request the user's profile information in addition to confirming their profile URL, the client can include one or more scopes in the initial authorization request. The following scope values are defined by this specification to request profile information about the user:

  • profile (required) - This scope requests access to the user's default profile information which include the following properties: name, photo, url.
  • email - This scope requests access to the user's email address in the following property: email.

Note that because the profile scope is required when requesting profile information, the email scope cannot be requested on its own and must be requested along with the profile scope if desired.

When an authorization code is issued with any of the scopes defined above, then the response when exchanging the authorization code MAY include a new property, profile, alongside the me property in the response from the authorization endpoint or the token endpoint. The profile property is defined as a JSON [RFC7159] object with the properties defined by each scope above.

For example, a complete response to a request with the scopes profile email create, including an access token and profile information, may look like the following:

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

{
  "access_token": "XXXXXX",
  "token_type": "Bearer",
  "scope": "profile email create",
  "me": "https://user.example.net/",
  "profile": {
    "name": "Example User",
    "url": "https://user.example.net/",
    "photo": "https://user.example.net/photo.jpg",
    "email": "user@example.net"
  }
}

As is always the case with OAuth 2.0, there is no guarantee that the scopes the client requests will be granted by the authorization server or the user. The client should not rely on the presence of profile information even when requesting the profile scope. As such, implementing support for returning profile information from the authorization server is entirely optional.

The information returned in the profile object is informational, and there is no guarantee that this information is "real" or "verified". The information provided is only what the user has chosen to share with the client, and may even vary depending on which client is requesting this data.

The client MUST NOT treat the information in the profile object as canonical or authoritative, and MUST NOT make any authentication or identification decisions based on this information.

For example, attempting to use the email returned in the profile object as a user identifier will lead to security holes, as any user can create an authorization endpoint that returns any email address in the profile response. A client using the email address returned here should treat it the same as if it had been hand-entered in the client application and go through its own verification process before using it.

Similarly, the url returned in the profile object is not guaranteed to match the me URL, and may even be on a different domain. For example, a multi-author website may use the website's URL as the me URL, but return each specific author's own personal website in the profile data.

6. Access Token Verification

In OAuth 2.0, access tokens are opaque to clients, so clients do not need to know anything about the contents or structure of the token itself. Additionally, endpoints that clients make requests to, such as [Micropub] endpoints, may not even understand how to interpret tokens if they were issued by a standalone token endpoint. If the token endpoint is not tightly integrated with the resource server the client is interacting with, then the resource server needs a way to verify access tokens that it receives from clients. If the token endpoint and Micropub endpoint are tightly coupled, then they can of course use an internal mechanism to verify access tokens.

Token endpoints that intend to interoperate with other endpoints MUST use the mechanism described below to allow resource servers such as Micropub endpoints to verify access tokens.

6.1 Access Token Verification Request

If a resource server needs to verify that an access token is valid, it MUST make a GET request to the token endpoint containing an HTTP Authorization header with the Bearer Token according to [RFC6750]. Note that the request to the endpoint will not contain any user-identifying information, so the resource server (e.g. Micropub endpoint) will need to know via out-of-band methods which token endpoint is in use.

GET https://example.org/token
  Authorization: Bearer xxxxxxxx
  Accept: application/json

6.2 Access Token Verification Response

The token endpoint verifies the access token (how this verification is done is up to the implementation), and returns information about the token:

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

  {
  "me": "https://user.example.net/",
  "client_id": https://app.example.com/",
  "scope": "create update delete"
  }

Specific implementations MAY include additional parameters as top-level JSON properties. Clients SHOULD ignore parameters they don't recognize.

If the token is not valid, the endpoint MUST return an appropriate HTTP 400, 401 or 403 response. The response body is not significant.

7. Token Revocation

A client may wish to explicitly disable an access token that it has obtained, such as when the user signs out of the client. IndieAuth extends OAuth 2.0 Token Revocation [RFC7009] by defining the following:

7.1 Token Revocation Request

An example revocation request is below.

POST https://example.org/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  Accept: application/json

  action=revoke
  &token=xxxxxxxx

As described in [RFC7009], the revocation endpoint responds with HTTP 200 for both the case where the token was successfully revoked, or if the submitted token was invalid.

8. Security Considerations

In addition to the security considerations in OAuth 2.0 Core [RFC6749] and OAuth 2.0 Threat Model and Security Considerations [RFC6819], the additional considerations apply.

8.1 Differing User Profile URLs

Clients will initially prompt the user for their profile URL in order to discover the necessary endpoints to perform authentication or authorization. However, there may be slight differences between the URL that the user initially enters vs what the system considers the user's canonical profile URL.

For example, a user might enter user.example.net in a login interface, and the client may assume a default scheme of http, providing an initial profile URL of http://user.example.net. Once the authentication or authorization flow is complete, the response in the me parameter might be the canonical https://user.example.net/. In some cases, user profile URLs have a full path component such as https://example.net/username, but users may enter just example.net in the login interface.

Upon validation, clients MUST check the me value from the profile URL response or access token response, and take the following validation steps:

  1. It MUST follow any permanent redirections from this URL to discover the canonical profile URL, in the same manner as initial profile URL discovery.
  2. It MUST verify that the canonical profile URL is on the same domain as the initially-entered profile URL.
  3. It MUST verify that the canonical profile URL declares the same authorization_endpoint as the initially-entered profile URL.

These steps ensure that an authorization endpoint is not able to issue valid responses for arbitrary profile URLs, and that users on a shared domain cannot forge authorization on behalf of other users of that domain.

8.2 Preventing Phishing and Redirect Attacks

Authorization servers SHOULD fetch the client_id provided in the authentication or authorization request in order to provide users with additional information about the request, such as the application name and logo. If the server does not fetch the client information, then it SHOULD take additional measures to ensure the user is provided with as much information as possible about the request.

The authorization server SHOULD display the full client_id on the authorization interface, in addition to displaying the fetched application information if any. Displaying the client_id helps users know that they are authorizing the expected application.

Since all IndieAuth clients are public clients, and no client authentication is used, the only measure available to protect against some attacks described in [RFC6819] is strong verification of the client's redirect_uri. If the redirect_uri scheme, host or port differ from that of the client_id, then the authorization server MUST either verify the redirect URL as described in Redirect URL, or display the redirect URL to the user so they can inspect it manually.

9. IANA Considerations

The link relation types below are documented to be registered by IANA per Section 6.2.1 of [RFC8288]:

Relation Name:
authorization_endpoint
Description:
Used for discovery of the OAuth 2.0 authorization endpoint given an IndieAuth profile URL.
Reference:
IndieAuth Specification (https://indieauth.spec.indieweb.org/)
Relation Name:
token_endpoint
Description:
Used for discovery of the OAuth 2.0 token endpoint given an IndieAuth profile URL.
Reference:
IndieAuth Specification (https://indieauth.spec.indieweb.org/)
Relation Name:
redirect_uri
Description:
Used for discovery of the OAuth 2.0 redirect URI given an IndieAuth client ID.
Reference:
IndieAuth Specification (https://indieauth.spec.indieweb.org/)

A. Resources

This section is non-normative.

A.1 Articles

This section is non-normative.

You can find a list of articles about IndieAuth on the IndieWeb wiki.

A.2 Implementations

This section is non-normative.

You can find a list of IndieAuth implementations on indieauth.net

B. Acknowledgements

The editor wishes to thank the IndieWeb community and other implementers for their support, encouragement and enthusiasm, including but not limited to: Amy Guy, Barnaby Walters, Benjamin Roberts, Bret Comnes, Christian Weiske, Dmitri Shuralyov, François Kooman, Jeena Paradies, Martijn van der Ven, Sebastiaan Andeweg, Sven Knebel, and Tantek Çelik.

C. Change Log

This section is non-normative.

C.1 Changes from 09 August 2020 to this version

C.2 Changes from 25 January 2020 to 09 August 2020

C.3 Changes from 03 March 2019 to 25 January 2020

C.4 Changes from 07 July 2018 to 03 March 2019

C.5 Changes from 23 January 2018 to 07 July 2018

C.6 Changes from 07 July 2018 to 03 March 2019

D. References

D.1 Normative references

[Fetch]
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
[h-app]
h-app. Aaron Parecki. microformats.org. Living Specification. URL: https://microformats.org/wiki/h-app
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6749
[RFC6750]
The OAuth 2.0 Authorization Framework: Bearer Token Usage. M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://tools.ietf.org/html/rfc6750
[RFC7009]
OAuth 2.0 Token Revocation. T. Lodderstedt, Ed.; S. Dronia; M. Scurtescu. IETF. August 2013. Proposed Standard. URL: https://tools.ietf.org/html/rfc7009
[RFC7159]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. March 2014. Proposed Standard. URL: https://tools.ietf.org/html/rfc7159
[RFC7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC7636]
Proof Key for Code Exchange by OAuth Public Clients. N. Sakimura, Ed.; J. Bradley; N. Agarwal. IETF. September 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7636
[RFC8288]
Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/

D.2 Informative references

[Micropub]
Micropub. Aaron Parecki. W3C. 23 May 2017. W3C Recommendation. URL: https://www.w3.org/TR/micropub/
[RelMeAuth]
RelMeAuth. Tantek Çelik. microformats.org. Living Specification. URL: https://microformats.org/wiki/RelMeAuth
[RFC6819]
OAuth 2.0 Threat Model and Security Considerations. T. Lodderstedt, Ed.; M. McGloin; P. Hunt. IETF. January 2013. Informational. URL: https://tools.ietf.org/html/rfc6819