IndieWebCamp 2015: July 11-12 in Portland, Oregon and Brighton, UK!

IndieAuthProtocol

(Redirected from login-brainstorming)

IndieAuth is a protocol to log users into web applications through an authorization server. The authorization server is linked from the user's home page.


Contents

Authorization process

indieauth-authorization-process.png

  1. User enters his homepage URL in the login form of the web application and clicks "Login"
  2. Web application discovers the authorization endpoint by fetching the user's homepage
  3. Web application redirects the user's browser to the authorization endpoint
  4. Authorization endpoint verifies the user, e.g. by logging in
  5. Authorization endpoint redirects the browser back to the web application, including a token
  6. Web application verifies the token directly with the authorization endpoint
  7. User is logged into the web application


Creating an Authorization Endpoint

An authorization endpoint must be able to both generate authorization codes as well as verify authorization codes.


Identification header

Every endpoint MUST return a

IndieAuth: authorization_endpoint

HTTP header in all responses.

It is used to verify that it's really an endpoint.


1. Login form

The site contains a web sign-in form prompting the user to enter their URL to sign in. Upon submitting the form, the site begins the auth process by discovering the user's auth endpoint.

indieauth-web-sign-in.png

2. Endpoint Discovery

The web application checks the user's website for a link with a rel-value of "authorization_endpoint":

<link rel="authorization_endpoint" href="http://indieauth.example.org/">

Use this URL as endpoint for processing.

If no authorization_endpoint link can be found, the IndieAuth client software may fall back to e.g. indieauth.com by using https://indieauth.com/auth as URL.

TODO: MUST HTTP header links be supported?


3. Redirect to authorization endpoint

Directing the user's browser to the auth endpoint is usually done via a HTTP Location header, but can optionally be an <a> tag with an href set to the authorization URL.

Note: Values are shown without URL encoding for readability.

https://auth.example.org/auth
    ?me=https://aaronparecki.com/
    &client_id=https://webapp.example.org/
    &redirect_uri=https://webapp.example.org/auth/callback
    &state=1234567890
    &response_type=id

Parameters:

me
Full URI of the user's homepage
client_id
Full URI of the application's/website's home page. Used to identify the application. An authorization endpoint may show the application's icon and title to the user during the auth process.
redirect_uri
Full URI to redirect back to when the login process is finished
state
Web application-internal state variable; can contain anything
Optional. Auth endpoints MUST support them, though.
response_type
id (identification only) or code (identification + authorization)
Optional. Defaults to id.
scope
Not used and omitted in identification mode (response_type=id)
For authorization, the scope contains a value (often a verb) that the web application requests permission for, e.g. "post". Multiple values are supported, e.g. post,delete

4. Verify user

The authorization server should present an interface describing the request being made. It must indicate:

The client_id making the request
Optionally the server can include the name and logo if an h-card is found on the client_id URL.
The scope if authorization is requested.

TODO: Example. See h-x-app.


Redirect URI verification

why is redirect_uri separate from state?
the callback URL shouldn't be dynamic per request so that callback URLs can be registered. "state" is allowed to vary per request
why should callback urls be registered?
without registration it's easier to perform a redirect attack. more background here: http://tools.ietf.org/html/rfc6749#section-3.1.2.2
how does the client website register the callback at the server?
haven't written this part up yet, but the idea is for the client to publish its registered redirect URIs on its web page with a <link> tag
since client IDs are always URLs, it's all discoverable that way
for client_id https://example.com/ a server can find its valid redirect URIs by looking for
<link rel="redirect_uri" href="https://example.com/callback">
at example.com

5. Redirect to web application

The authorization server presents the request information to the user, and when he approves, generates an authorization code and redirects the user to the redirect URI specified.

HTTP/1.1 302 Found
Location: https://webapp.example.org/auth/callback
    ?code=xxxxxxxx
    &state=1234567890
    &me=https://aaronparecki.com/

Parameters:

code
Authorization code
state
State variable sent by the web application
me
Full URI of the user's homepage

6. Token verification

The web application finally queries the authorization endpoint to verify the auth code given by making a POST request with the following values:

POST https://auth.example.org/auth
Content-type: application/x-www-form-urlencoded

code=xxxxxxxx
&redirect_uri=https://webapp.example.org/auth/callback
&client_id=https://webapp.example.org/
&state=1234567890

After the authorization server verifies that redirect_uri, client_id and state match the code given, the response will include the "me" and optionally the "scope" value:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

me=https://aaronparecki.com/
&scope=post

Parameters:

me
Full URI of the user's homepage
scope
Not used and omitted in identification mode (request_type=id)
For authorization, the scope contains one or multiple (comma-separated) values the user gave his permission for.


Using an Authorization Service

You can use an existing authorization service such as indieauth.com if you don't want to build your own authorization service.


FAQ

Why are auth codes verified with a POST instead of a GET

If auth codes are sent as a GET request in the query string, they may leak to log files or the HTTP "referer". The decision was made by the OAuth 2.0 working group to use POST requests and the HTTP Authorization header for sending these sensitive tokens and auth codes.

Can the authorization codes be used more than once

No, the authorization code must not be used more than once. If the code is used more than once, the authorization server must deny the request.[1] A maximum lifetime of 10 minutes is recommended for the authorization codes, although many implementations have a lifetime of 30-60 seconds.

Can I add additional parameters for the authorization request

No, but you can use the "state" parameter to encode or reference additional application-specific parameters. The state parameter will be passed around and was designed for this purpose as well as to prevent CSRF attacks.

Does the auth server have to support the state parameter

Yes, the state parameter can be used by the client to maintain state between the request and the callback, so the auth server must support it. It is also used to prevent CSRF attacks.