IndieAuth

From IndieWeb
Jump to: navigation, search

IndieAuth is a federated login protocol for Web sign-in, enabling users to use their own domain to sign in to other sites and services. IndieAuth can be used to implement OAuth2 login AKA OAuth-based login.

IndieAuth is built on ideas and technology from existing proven technologies like OAuth and OpenID but makes it easier for users as well as developers. It decentralizes much of the process so completely separate implementations and services can be used for each part.

Read More: IndieAuth: OAuth for the Open Web

If you’re familiar with writing an OAuth client, then you're familiar with the problem of having to register your client manually with each OAuth provider. IndieAuth uses DNS as a replacement for client registration, thereby eliminating the need for any manual registration with providers.

Note: IndieAuth is often conflated with the IndieAuth.com service provider. The first is the subject of this page: the way the IndieAuth protocol works. The second is an implementation that most people will be familiar with because it is used on this wiki, and has been renamed to indielogin.com

Why

By choosing your IndieAuth provider, you can tell applications where to send you to sign in. This gives you more control over the privacy and security of your logins.

Most Micropub clients use IndieAuth to log you in, obtaining your authorization by directing you to your chosen IndieAuth server. This allows you to use your own website to log in to the tools you use to post content.

IndieAuth is part of taking back control of your online identity. Instead of logging in to websites as “you on Twitter” or “you on Facebook”, you should be able to log in as just “you”. We should not be relying on silos to provide our authenticated identities, we should be able to use our own personal domains to log in to sites everywhere.

You can use it right now to log in to this wiki and contribute to the community, including doing common things like:

How it works

Basic flow with a user signing in to a (web) app

  1. The user fills in his/her personal URL This is called Web sign-in.
  2. The app fetches the URL, looking for an authorization endpoint. For this, the user can use IndieAuth.com, but it can also be at their own domain. The app redirects the User to their authorization endpoint.
  3. The user authenticates at their own authorization endpoint. IndieAuth.com uses RelMeAuth to authenticate users, but if a user uses an authorization endpoint on his/her own site, it can be a password, e-mail link, or any other authentication mechanism the authorization endpoint provides. They prove their identity to their authorization endpoint while the app waits for them to complete.
  4. The authorization endpoint issues a temporary authorization code, and sends it to the app by redirecting the user's browser back to the app.
  5. The app checks the code with the authorization endpoint, and if the code is valid and if the user’s identifier matches the identifier the authorization endpoint gives, the login is completed, and the user can enter and use the app.

How to

If all you're trying to do is log in to the wiki, then you may not need to set up IndieAuth at all! Instead, you can just link to your existing Twitter or GitHub accounts and the wiki will use those to authenticate you! See indielogin.com/setup for more details.

Set up using IndieAuth.com

IndieAuth.com is a service that allows you to sign in as your site by using your social media profiles. Your homepage and social media profiles need to link to each other for verification. Instead of registering for an account at indieauth.com, it uses your existing social media accounts to verify you own the URL you're signing in as.

  1. Add rel-me links to your homepage for various ways to reach you,
    e.g. <a href="https://twitter.com/indiewebcamp" rel="me">Twitter</a>.
  2. Make sure any social media profiles you linked to have a link back to your homepage.
  3. Finally, include <link rel="authorization_endpoint" href="https://indieauth.com/auth"> on your homepage.

You are done! Try to log in to a site that supports IndieAuth, such as:

These services should redirect you to your chosen IndieAuth endpoint to sign in, which in this case is indieauth.com.

See: full setup instructions

Use IndieAuth.com for your OpenID

See indieauth.com#OpenID

Set up in WordPress

If you use WordPress, you can install the Wordpress IndieAuth Plugin which provides a built-in IndieAuth server.

Set up your own IndieAuth provider

Use an existing implementation or build your own!

IndieWeb Examples

The following people have an authorization endpoint on their own domain.

Aaron Parecki

Aaron Parecki at https://aaronparecki.com/auth as of 2016-04-13. As of 2017-10-04, authentication is done via a push notification to his mobile phone rather than entering a password.

Sebastiaan Andeweg

Sebastiaan Andeweg has an authorization endpoint at https://seblog.nl/auth as of IndieWebWeek 2017 in Düsseldorf and Nürnberg.

Martijn van der Ven

Martijn van der Ven has an authorization endpoint on http://vanderven.se/martijn/ as of 2017-06-30. Powered by selfauth.

Jeena Paradies

Jeena Paradies has an authorization endpoint at https://jeena.net/indieauth as of IndieWebCamp 2017 in Berlin

Implementations

IndieAuth.com

selfauth

Acquiescence

  • Acquiescence is a simple IndieAuth authorization and token endpoint. It is currently limited to GitHub for authorization. Barry Frost uses Acquiescence on his website.

Wordpress IndieAuth Plugin

Known

  • Known provides a built-in IndieAuth server

Comment Parade

  • commentpara.de provides IndieAuth identities to anyone wishing to log in to a website anonymously.

indieauth-openid

IndieCert

Micro.blog

Cellar Door

Services

IndieLogin.com

IndieLogin.com is a service that consumes IndieAuth. It authenticates users using IndieAuth, RelMeAuth, email and PGP, wrapping all the logic in a simple API. It is a very easy way to get started consuming IndieAuth logins.

Read the full documentation

IndieAuth.com

The IndieAuth.com service provides an authorization endpoint to bootstrap your Micropub server development. It lets you authenticate via GitHub, email, and PGP. Eventually this will be replaced with a new service, MyIndieAuth.com, although development of that service has not yet begun.

Historically, IndieAuth.com also provided an API for developers to use to authenticate users, tho this is being phased out in favor of IndieLogin.com.

Read the full documentation

The IndieAuth.com source code is available on GitHub.

Supporting Sites

(This section is a stub and needs expansion!)

There are a growing number of web sites that you can log into using IndieAuth and gain additional functionality:

Use with Micropub

Most Micropub implementations use IndieAuth to obtain the user's authorization (and an access token), including:

IndieAuth Protocol

TODO: consider moving this to its own page, maybe on Category:IndieAuth.

A user should only have to communicate their own homepage URL to the website they are trying to log in to. This is the core idea of Web sign-in. This means a developer should in their turn be able to find everything they need on that one user supplied URL.

Discovery from the User's Homepage

IndieAuth defines two new rel values for this. A user can simply link to the endpoints they want to use from their homepage, add the correct rel value and be done.

An example would be to link to them in the <head> section of their HTML, like so:

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

Developers can discover these endpoints using traditional HTML or Microformats parsing.

The Authorization Endpoint

The authorization endpoint is a page where applications can send users to and asking them to identify themselves. Because the user defines their own endpoint on their homepage, this can be part of their own website or a completely separate service. This is how the user provides proof they really operate the homepage URL they provided.

An application can also ask the user to grant it certain rights by requesting them through the authorization endpoint. A Micropub client might ask to be allowed create rights. The user can then either accept these or not when they have been redirected to their endpoint.

For developers, the authorization endpoint also functions as a verification service. If they get a code from a user they can check its validity with the endpoint to make sure it was truly issued by the user.

Third Party Services

Self-Hostable Implementations

The Token Endpoint

The token endpoint is a service that creates access tokens for applications to store and use in Micropub requests. After authorizing the application, the token endpoint creates a token that the application stores. The application will send it in a header when making a Micropub request, and the Micropub endpoint is expected to be able to validate the token while processing the request.

Third Party Services

Self-Hostable Implementations

Table of Contents

FAQ

The IndieAuth.com FAQ is here:

Feel free to add more questions here that seemed to be asked more than once.

How is IndieAuth different from OpenID Connect

Main article: How is IndieAuth different from OpenID Connect

Do I need a silo account

Q: Do I need an account on some third party silo to use it?

Short answer: no. You can use PGP or selfauth for example.

Longer answer: you do not need a silo account to use IndieAuth, e.g. you may set it up with PGP or selfauth.

However, the vast majority of people already have silo accounts, and most people who have their own websites already have visible hyperlinks to their silo profiles, thus the easiest way to get most people setup with IndieAuth is using RelMeAuth by adding rel=me to their silo hyperlinks, and configuring their silo profiles to link back to their personal website.

And despite using a silo, there is little downside because the use is ephemeral (the site using IndieAuth has no idea which silo used to verify your personal site identity), and there are a number of advantages for most folks:

  • UX familiarity. Most users are already familiar with the authentication flow of signing into a site or app with Twitter or GitHub (or even Facebook has a similar flow.
  • security. Silos have a much larger security staff (and with likely more expertise) than you do, and thus have likely secured their sign-in and authentication/authorization code and user flows much more than solution you would maintain yourself.
  • two-factor authentication (TFA) Most silo accounts can be secured with TFA which adds an additional degree of security, whereas the DIY IndieAuth solutions do not have such a capability, nor does anyone know of anyone who has implemented TFA on their personal site.

One potentially non-trivial downside (depends on the user) of using a silo account for authorization is that the silo account may be tracking your use of IndieAuth.com, and who knows what they will do with that data. The silo accounts do not see what services (like this wiki) that you sign-into however with IndieAuth.

Do I need to enter my URL every time

Q: Do I need to enter my URL every time I log in to an app that uses IndieAuth?

Yes, like traditional username/password forms, you need to enter your URL when you log in to an app. Browsers will remember your URL you enter and will suggest it using their normal autofill mechanisms as well.

indieauth-autofill.jpg

Issues

This section is for issues with the IndieAuth protocol that are not specific to either authorization-endpoint or token-endpoint. Issues with how the protocol is presented, as well as security considerations can go here.

This section is not for issues with IndieAuth.com-the-service. Please open specific bugs and action items for the latter on the IndieAuth.com Github project.

Should the specification make recommendations on HTTPS?

A token can be sent to an IndieAuth endpoint without HTTPS (the docs do not forbid this), such a request should be refused. In the case of an HTTPS redirect being in place for the domain the request should not be redirected to prevent DNS poisoning, MITM, and race-condition attacks.

Need Simple Copy Paste How To

The explanation in http://waterpigs.co.uk/articles/indiewebcamp-signin-ux/ provides a list of three lengthy descriptions of what you need to set up IndieAuth, which was then subsequently criticized as "this is not a straightforward process" in the post: http://aralbalkan.com/notes/on-evolving-indieauth/

Thus we need a a simple copy paste how to that is not three lengthy descriptions.

Any explanation of how to use IndieAuth needs to start with a 1-2 sentence summary. No more.

Compare with:

Explanations for IndieAuth need to be at least as simple to understand as those for Twitter Sign-in and Facebook Connect.

IndieAuth using form-encoded responses instead of JSON

IndieAuth originally used standard form-encoding for requests and responses, since it has been a standard encoding format since the beginning of the web.

Over time, implementations added support for sending JSON responses as well as form-encoded. When IndieAuth was written up as a formal OAuth 2.0 extension, it documented only the JSON responses in order to be compatible with OAuth 2.0. At that point, most implementations already supported JSON responses, or did content negotiation to support both formats.

Historical Discussion IndieAuth uses standard form-encoding for requests and response because it has been a standard encoding format since the beginning of the web. If it were a JSON response, then 7 years down the road you'd be asking "why is the response in JSON instead of ____" where ____ is the next trendy thing that replaces JSON. (Remember when XML was the new hotness?)

Proposal for content negotiation: https://www.tuxed.net/fkooman/blog/proposed_changes_to_indieauth_protocol.html#content_negotiationWwelves.org perpetual-tripper 02:26, 5 March 2015 (PST)

  • To me this would violate Postel's law, requiring every implementation to publish many different formats. I don't care which format IndieAuth produces, but I do think we should settle on one canonical format. Kylewm.com 10:03, 5 March 2015 (PST)
  • Agreed that there should be only one format. The only valid argument for JSON is that the OAuth 2.0 spec defines the response as JSON. Aaron Parecki 10:06, 5 March 2015 (PST)
  • OK I withdraw my objection to content negotiation. Agree it is a relatively small burden on a relatively small number of providers; it's worth supporting multiple formats for convenience to the large number of consumers Kylewm.com 12:06, 5 March 2015 (PST)
  • Just to be anti-inventing-new-formats (too many of them around and demanding attention), I'd go for form-encoded -- Kartik Prabhu 00:21 2015-03-06
  • I just never saw HTTP POST form encoded _responses_ anywhere, only POST url encoded form requests... Any link to other (REST) services that use this? e.g. XMLHttpRequest does not support form encoded responses at all... fkooman

Requesting additional user details

The auth consumers may want to receive additional information about a user, and not just their homepage URL. Andy Baio raised some points in regard to this in a backer-only Kickstarter post, Opening the Source and The Great Auth Debate, 2015-03-16, when deciding what authentication mechanism to use for Upcoming.org.

  • Silos may give the application access to the user’s social graph: who their friends are, who they are following.
    • This would require some IndieWeb format for following.
    • This is great for applications like readers to start a user off.
  • Silos may give the application location information about the user.
    • This is great for applications like Upcoming.org that want to show relevant events.
    • This is possible by parsing the homepage URL of the user for h-card or recent checkins.

naming confusion

There has been ongoing confusion between IndieAuth(-the-protocol), IndieAuth.com and RelMeAuth.

Most people use IndieAuth by using IndieAuth.com as their authorization_endpoint, which then does RelMeAuth to authenticate them, which has people conflate IndieAuth with rel=me-links.

Some might also just have rel=me links set up and only log in to sites which use IndieAuth.com (or other services that support RelMeAuth directly) to handle login for them, which means they are using RelMeAuth, but not IndieAuth(-the-protocol), while thinking they are using IndieAuth.

  • One problem with the indieauth.com site being called just "indieauth.com" is that people then think that IndieAuth is somehow centralized around this service.
  • In in-person conversations about IndieAuth/RelMeAuth/OAuth with people, I've found that most people think of RelMeAuth when they are talking about IndieAuth. Aaron Parecki
    • Another possibility is to rename the IndieAuth protocol (which is an extension of OAuth 2.0) to make it clear that the OAuth 2.0 extension has nothing to do with RelMeAuth
      • Martijn van der Ven: I think renaming the protocol is your call, Aaron Parecki as the author of said protocol, but I feel it would be unnecessary. Especially if indieauth.com is getting renamed. This feels like an education issue, possibly a documentation issue (which we are already solving with wiki-gardening!). We don’t go and rename microformats because people have been writing blog posts where they used the word “microformats” and then described some other system like Microdata. Instead we educate on what the name microformats is.
        • sknebel: +1, I think that'd lead to even more confusion
    • Martijn van der Ven: Note that no implementers have made the mistake. Acquiescence, commentpara.de, Known, selfauth all talk about IndieAuth as the protocol.
      • Aaron Parecki: This is a great point, and convinces me the name of the spec is fine.
    • Martijn van der Ven: And no consumers advertise it wrong as far as I can find. Are there any implementations that use only indieauth.com and claim to be IndieAuth? That means not using something like indieauth/client and using the service as a fallback, but really using only the service?

      This wiki is an example of that, but also does not claim to use IndieAuth in any way! It describes its login as web sign-in and not IndieAuth. It mentions IndieAuth as an alternative for people who do not want to use their social media accounts, that’s a very correct description:

      indieweblogin.png

      • sknebel Indeed, web-sign in seems like a fitting term here (given that the definitions talk about the general concept of using your homepage URL to sign in, and reference both RelMeAuth and IndieAuth as implementations)
    • sknebel I've been explaining IndieAuth at HWC Berlin to people from "has written an endpoint following authorization-endpoint" over "has logged into the wiki" to "IndieAuth, never heard of it". One of the first category wasn't quite clear on the status of non-Indieauth.com implementations of sites to log-in to (since they'd only used it with sites using Indieauth.com, primarily the wiki), second wasn't necessarily aware of a difference between service and protocol. Explaining the difference (and how RelMeAuth fits in) wasn't an issue, but had to be explicitly mentioned. I believe a different name for IndieAuth.com would go a long way there.
  • The wiki pages for IndieAuth don't always make this distinction clear, work has begun during IndieWebWeek (2017-05) to improve this
    • Work continued 2017-07-19 by moving FAQ and Issue items from this page to the pages they were about: RelMeAuth or indieauth.com.
    • New copy for this wiki page was written in a separate sandbox page where the focus was on explaining IndieAuth and its 3 parts. See User:Vanderven.se martijn/IndieAuth.
      • sknebel +1, to me this is just clarifying and extending existing documentation (e.g. the different endpoints, that currently only have their separate pages, and clearly separating .com from the protocol)

how to should include endpoint definition

This would make sure first time users do not have to try and figure this out themselves. Example:

Getting myself validated through IndieAuth was already taken care of by the rel="me" links, but some services needed me to declare IndieAuth as my authorization endpoint; […]

Here “IndieAuth” refers to indieauth.com-the-service. The discussion above is about clearing up the name issue, this is only about including the endpoint declaration in HTML. Daniel ran into services that offered him to login with IndieAuth and required him to declare the authorization endpoint, completely according to how IndieAuth works. (As documented above, most implementers stick to the spec when they talk about IndieAuth.) This is currently completely left out of the how-to and new users are left to figure it out for themselves.

The wiki leaves users hanging who try to login using IndieAuth outside of the wiki. This how-to issue is documented here specifically because Tantek Çelik wondered why an extra step was needed.

  • I say this is a mistake in the How-to that needs to be addressed. — Martijn van der Ven
  • agreed, instructions about IndieAuth should explicitly include the endpoint —sknebel
  • -1 disagreed. Don't make more work for the >99% to satisfy the <1% who want to install their own IndieAuth providers. IndieAuth authentication services should handle rel=me without needing an explicitly specified endpoint. - Tantek Çelik
    • Again this just points to the confusion around the responsibility of who is trusting who. If you are just trying to sign in to the wiki with your domain, you do not need to ever worry about or see the term "IndieAuth". The wiki is doing "web sign-in" via RelMeAuth, IndieAuth, email or PGP authentication by letting the indielogin.com service handle the implementation details. If someone actually wants to implement IndieAuth, it's because they want to specifically tell applications where to send them to sign in, in which case they do that by specifying an authorization_endpoint on their home page. Aaron Parecki

To do

Talks and Demos

Articles


See Also