IndieAuth

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.

3.1 Issuer Identifier

The issuer identifier of the authorization server, which is primarily used to prevent authorization server mix-up attacks. The issuer identifier is a URL that uses the "https" scheme and has no query or fragment components as defined in [RFC9207], however, the identifier MUST also be a prefix of the indieauth-metadata URL. For example, for an indieauth-metadata endpoint https://example.com/.well-known/oauth-authorization-server, the issuer URL could be https://example.com/, or for a metadata URL of https://example.com/wp-json/indieauth/1.0/metadata, the issuer URL could be https://example.com/wp-json/indieauth/1.0

3.2 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, host names MUST be domain names and MUST NOT be ipv4 or ipv6 addresses.

Some examples of valid profile URLs are:

• https://example.com/
• https://example.com/username
• https://example.com/users?id=100

Some examples of invalid profile URLs are:

• example.com - missing scheme
• mailto:user@example.com - invalid scheme
• https://example.com/foo/../bar - contains a double-dot path segment
• https://example.com/#me - contains a fragment
• https://user:pass@example.com/ - contains a username and password
• https://example.com:8443/ - contains a port
• https://172.28.92.51/ - host is an IP address

3.3 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, host names 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.4 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 provides https://example.com for Discovery, the client MUST transform it to https://example.com/ when using it and comparing it.

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

For ease of use, clients MAY allow users to enter just the host 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.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 indieauth-metadata endpoint, which provides the location of the IndieAuth server's authorization endpoint and token endpoint, as well as other relevant information for the client. Clients MUST start by making a GET or HEAD request to [Fetch] the user provided URL to discover the necessary values. Clients MUST follow HTTP redirects (up to a self-imposed limit). When using the Authorization flow to obtain an access token for use at another endpoint, such as a [Micropub] endpoint, the client will also discover the micropub endpoint.

Clients MUST check for an HTTP Link header [RFC8288] with a rel value of indieauth-metadata. If the content type of the document is HTML, then the client MUST check for an HTML <link> element with a rel value of indieauth-metadata. 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 URLs 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.

In the event there is no indieauth-metadata URL provided, for compatibility with previous revisions of IndieAuth, the client SHOULD look for an HTTP Link header and HTML <link> element with a rel value of authorization_endpoint (and optionally token_endpoint) following the same order of predence as described above.

Note that the recommendation of looking for the rel=authorization_endpoint and rel=token_endpoint are included for backwards compatibility with previous IndieAuth profiles and may be removed from this specification in the future after wide enough adoption of the newer indieauth-metadata discovery method.

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

{
  "issuer": "https://indieauth.example.com/",
  "authorization_endpoint": "https://indieauth.example.com/auth",
  "token_endpoint": "https://indieauth.example.com/token",
  "code_challenge_methods_supported": ["S256"]
}

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.

Clients SHOULD publish an OAuth Client ID Metadata Document [ClientIDMetadataDocument] at the client identifier URL.

The authorization server SHOULD [Fetch] the URL to find more information about the client.

If the client_id contains the permitted IPv4 and IPv6 addresses 127.0.0.1 or [::1], or if the domain name resolves to these addresses, the authorization endpoint MUST NOT fetch the client_id.

Note that the server may want to perform some additional checks on the client_id before fetching it to avoid SSRF attacks. In particular, the server may want to resolve the domain name first and avoid fetching the document if the IP address is within the loopback range defined by [RFC5735] or any other implementation-specific internal IP address.

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.1 Discovery

After obtaining a URL from the End-User, and optionally applying URL Canonicalization to it, the client fetches the URL and looks for the indieauth-metadata rel values in the HTTP Link headers and HTML <link> tags as described in § 4.1 Discovery by Clients.

Link: <https://indieauth.example.com/.well-known/oauth-authorization-server>; rel="indieauth-metadata"

<link rel="indieauth-metadata" href="https://indieauth.example.com/.well-known/oauth-authorization-server">

The client fetches the metadata document and finds the authorization_endpoint and token_endpoint in the JSON body.

{
  "issuer": "https://indieauth.example.com/",
  "authorization_endpoint": "https://indieauth.example.com/auth",
  "token_endpoint": "https://indieauth.example.com/token",
  "code_challenge_methods_supported": ["S256"]
}

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.

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

• response_type=code - Indicates to the authorization server that an authorization code should be returned as the response
• client_id - The client URL
• redirect_uri - The redirect URL indicating where the user should be redirected to after approving the request
• state - A parameter set by the client which will be included when the user is redirected back to the client. This is used to prevent CSRF attacks. The authorization server MUST return the unmodified state value back to the client.
• code_challenge - The code challenge as previously described.
• code_challenge_method - The hashing method used to calculate the code challenge, e.g. "S256"
• scope - (optional) A space-separated list of scopes the client is requesting, e.g. "profile", or "profile create". If the client omits this value, the authorization server MUST NOT issue an access token for this authorization code. Only the user's profile URL may be returned without any scope requested. See Profile Information for details about which scopes to request to return user profile information.
• me - (optional) The URL that the user entered

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 value after applying URL Canonicalization.

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.

HTTP/1.1 302 Found
Location: https://app.example.com/redirect?code=xxxxxxxx&
                                           state=1234567890&
                                           iss=https%3A%2F%2Findieauth.example.com

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.

POST https://indieauth.example.com/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

POST https://indieauth.example.com/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.

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

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

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

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

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"
  }
}

5.4 Authorization Server Confirmation

Clients will initially prompt the user to enter a URL in order to discover the necessary endpoints to perform authentication or authorization. However, there may be differences between the URL that the user initially enters and the final resulting profile URL as returned by the authorization server. The differences may be anything from a differing scheme (http vs https), to even a URL with a different host.

Upon receiving the me URL in the response from the authorization server (either in the profile URL response or access token response) the client MUST verify the authorization server is authorized to make claims about the profile URL returned by confirming the returned profile URL declares the same authorization server.

The client MUST perform endpoint discovery on the returned me URL and verify that URL declares the same authorization endpoint as was discovered in the initial discovery step, unless the returned me URL is an exact match of the initially entered URL or any of the URLs encountered during the initial endpoint discovery, either from a possible redirect chain or as the final value.

Note that the step of checking for the existence of the returned profile URL in the initial endpoint discovery is an optional optimization step which may save the client from possibly needing to make another HTTP request. This step may be skipped for simplicity, as discovering the authorization server from the returned profile URL is sufficient to confirm the returned profile URL declares the same authorization server.

This verification step ensures 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.

Examples

The following are some non-normative examples of real-world scenarios in which the initial user-entered URL may be different from the final resulting profile URL returned by the authorization server.

Basic Redirect

The basic redirect example covers cases such as:

• entering a domain with a www prefix and resolving it to the main domain
• entering a URL with no scheme or with http and resolving it to an https URL
• entering a short domain and resolving it to a different longer domain

Steps

1. The user enters www.example.com into the client
2. The client applies the steps from URL canonicalization to turn it into a URL: http://www.example.com/
3. The client makes a GET request to http://www.example.com/
4. The server returns a 301 redirect to https://example.com/
5. The client makes a GET request to https://example.com/ and finds the authorization endpoint
6. The client does the IndieAuth flow with that authorization endpoint. This results in the profile URL response with a me value of https://example.com/ as the canonical Profile URL.
7. The client sees that the canonical Profile URL matches the URL that the authorization endpoint was discovered at, and accepts the value https://example.com/

Service Domain to Subdomain

1. The user enters example.com into the client
2. The client applies the steps from URL canonicalization to turn it into a URL: http://example.com/
3. The client makes a GET request to http://example.com/
4. The server returns a 301 redirect to https://example.com/
5. The client makes a GET request to https://example.com/ and finds the authorization endpoint, https://login.example.com
6. The client does the IndieAuth flow with https://login.example.com. This results in the profile URL response with a me value of https://username.example.com/ as the canonical Profile URL.
7. This is the first time the client has seen this URL, so must verify the relationship between this subdomain and the authorization server. It fetches https://username.example.com/ and finds the same authorization endpoint https://login.example.com
8. The client accepts the me value of https://username.example.com/

Service Domain to Path

1. The user enters example.com into the client
2. The client applies the steps from URL canonicalization to turn it into a URL: http://example.com/
3. The client makes a GET request to http://example.com/
4. The server returns a 301 redirect to https://example.com/
5. The client makes a GET request to https://example.com/ and finds the authorization endpoint, https://login.example.com
6. The client does the IndieAuth flow with https://login.example.com. This results in the profile URL response with a me value of https://example.com/username as the canonical Profile URL.
7. This is the first time the client has seen this URL, so must verify the relationship between this subdomain and the authorization server. It fetches https://example.com/username and finds the same authorization endpoint https://login.example.com
8. The client accepts the me value of https://example.com/username

Email-like Identifier

1. The user enters user@example.com into the client
2. The client applies the steps from URL canonicalization to turn it into a URL: http://user@example.com/
3. The client makes a GET request to http://example.com/ providing the HTTP Basic Auth username user
4. The server returns a 301 redirect to https://example.com/
5. The client makes a GET request to https://example.com/ and finds the authorization endpoint, https://login.example.com
   • Note: Alternatively the server can advertise the authorization endpoint in the response to the http://user@example.com/ request directly instead of needing a separate redirect
6. The client does the IndieAuth flow with https://login.example.com, providing the user-entered user@example.com in the request as a hint to the server. This results in the profile URL response with a me value of https://example.com/username as the canonical Profile URL.
7. This is the first time the client has seen this URL, so must verify the relationship between this subdomain and the authorization server. It fetches https://example.com/username and finds the same authorization endpoint https://login.example.com
8. The client accepts the me value of https://example.com/username

5.5 Refresh Tokens

Refresh tokens are issued to the client by the authorization server and MAY be used at any time to obtain a new access token, usually when the current access token becomes invalid or expires, or to obtain a new token with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).

Use of short-lived access tokens and the offering of refresh tokens is RECOMMENDED, however, issuing a refresh token is at the discretion of the authorization server, and may be issued based on properties of the client, properties of the request, policies within the authorization server, a choice by the user authorizing the request or any other criteria. If the authorization server issues a refresh token, it is included in the return when issuing an access token. If the authorization server decides not to issue refresh tokens, or the refresh token expires, the client MAY obtain new access tokens by starting the authorization flow over.

Authorization servers MAY revoke refresh tokens automatically in case of a security event, such as a password change or a logout at the authorization server, or when they are redeemed, in which case a new refresh token MAY be provided. Refresh tokens SHOULD expire if the client has been inactive for some time, i.e., the refresh token has not been used to obtain fresh access tokens for some time. The expiration time is at the discretion of the authorization server.

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

grant_type=refresh_token
&refresh_token=xxxxxxxx&client_id=https://app.example.com

6.1 Access Token Verification Request

If a resource server needs to verify that an access token is valid, it may do so using Token Introspection. IndieAuth extends OAuth 2.0 Token Introspection [RFC7662] by adding that the introspection response MUST include an additional parameter, me.

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.

The resource server SHOULD make a POST request to the token endpoint containing the Bearer token in the token parameter, which will generate a token verification response. The endpoint MUST also require some form of authorization to access this endpoint and MAY identify that in the introspection_endpoint_auth_methods_supported parameter of the metadata response. If the authorization is insufficient for the request, the authorization server MUST respond with an HTTP 401 code.

POST https://indieauth.example.com/introspect
Content-type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Bearer xxxxxxxx

token=xxxxxxxx

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:

• active - (required) Boolean indicator of whether or not the presented token is currently active
• me - (required) The profile URL of the user corresponding to this token
• client_id - The client ID associated with this token
• scope - A space-separated list of scopes associated with this token
• exp - (optional) Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token will expire
• iat - (optional) Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued

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

{
  "active": "true",
  "me": "https://user.example.net/",
  "client_id": https://app.example.com/",
  "scope": "create update delete"
  "exp": "1632443647",
  "iat": "1632443147"
}

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 still MUST return a 200 Response, with the only parameter being active(with its value set to "false"). The response SHOULD NOT include any additional information about an inactive token, including why the token is inactive.

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

{
  "active": "false",
}

7.1 Token Revocation Request

An example revocation request is below.

POST https://indieauth.example.com/revocation HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json

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.