IndieAuth Sign-In Workflow

23.2

The basic flow for a user signing in to an application is as follows.

  • The user enters their personal URL in the sign-in form of the application.
  • Discovery: The application fetches the URL and finds the user’s authorization endpoint.
  • Authorization Request: The application directs the user’s browser to the authorization endpoint discovered, as a standard OAuth 2.0 Authorization Grant along with the user’s URL entered in the first step.
  • Authentication/Approval: The user authenticates at their authorization endpoint and approves the login request. The authorization server generates an authorization code and redirects back to the application’s redirect URL.
  • Verification: The application checks the code at the authorization endpoint, similar to exchanging the code for an access token, except no access token is returned since this is just a check for authentication. The authorization endpoint responds with the full URL of the user who authenticated.

Authentication Request

When the application builds the URL to authenticate the user, the request looks very similar to the OAuth authorization request, except no pre-registration of the client is necessary, and the request will also include the user’s profile URL. The URL will look like the below.

https://user.example.net/auth?
    me=https://user.example.net/
    &redirect_uri=https://example-app.com/redirect
    &client_id=https://example-app.com/
    &state=1234567890
    &code_challenge=XXXXXXXXX
    &code_challenge_method=S256

The authorization server will then ask the user to log in, as normally happens with OAuth flows, and then ask the user if they would like to continue signing into the app, as shown below.

If the user approves, they will be redirected back to the application with an authorization code (and the app’s state value) in the query string.

The app will then take the authorization code and verify it with the authorization endpoint, in order to confirm the identity of the user that signed in. The app makes a POST request to the authorization endpoint with the code, client_id and redirect_uri, like a typical authorization code exchange.

POST /auth
Host: user.example.net
Content-type: application/x-www-form-urlencoded

code=xxxxxxxx
&client_id=https://example-app.com/
&redirect_uri=https://example-app.com/redirect
&code_verifier=XXXXXXXXX

The response will be a simple JSON object with the user’s full profile URL.

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

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

See https://indieauth.spec.indieweb.org/#redeeming-the-authorization-code for more details about handling the request and response.