Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Use raw Markdown files instead of Jekyll for now
Taking inspiration from https://webassembly.github.io, let's do the simplest thing that could possibly work: shoving a bunch of raw Markdown files into the root of the repository and letting GitHub sort out how to render it. This has the advantage of being extremely lightweight and freeing us from any website design concerns, beyond a single index.html file for GitHub Pages. We can return to using Jekyll once we have enough content to justify it. For now, this makes it easier to just sit down and write.
- Loading branch information
Showing
24 changed files
with
212 additions
and
808 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
# Portier's Non-Goals | ||
|
||
Equally important to what Portier will do is what it _will not_ do. Many of these decisions are taken in the interest of simplicity and maintainability: we want Portier to be as well-defined, understandable, and maintainable as possible. Thus, we explicitly reject features that would dramatically expand Portier's scope, increase its complexity, or require significant changes to its user experience. | ||
|
||
Portier is a distinct tool, not an omnibus toolkit. | ||
|
||
Specifically, Portier will not: | ||
|
||
* __Provide profile metadata__: Portier is narrowly focused on authenticating email addresses. Names, photos, and other metadata are out of scope. | ||
|
||
* __Integrate with Facebook__: People do not naturally think of their Facebook accounts as email addresses, while Portier is fundamentally driven by the notion of email address as identity. As such, direct integration with Facebook does not make sense for Portier. Websites may, of course, offer Facebook Connect as an authentication option alongside Portier. | ||
|
||
* __Be a Single Sign-On service__: Though Portier could be useful when build an SSO system, it is not itself an SSO system. | ||
|
||
* __Remember multiple identities__: Portier only verifies email addresses. It doesn't remember those addresses or make claims about associations between multiple addresses. | ||
|
||
* __Promise native browser integration__: Portier must work for everyone on the Web, regardless of browser. The complexity, bureaucracy, and time required for native integration is not currently worth its ill-defined benefits, especially with promising standards from the [FIDO Alliance](https://fidoalliance.org/) on the horizon. In contrast, Portier is relatively simple and designed to solve a specific problem _today_. | ||
|
||
* __Protect users from their own email providers__: A malicious email provider is able to impersonate users within its own domain, and may be able to observe where its users are logging in. However, this is true of _all_ authentication systems with email-based account recovery workflows. Portier is not in a position to properly solve this problem. | ||
|
||
Privacy-conscious users can control which parties they must trust by selecting a different email provider, or self-hosting their own domain. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
# Portier and Other Projects | ||
|
||
Portier considers itself a spiritual successor to [Mozilla Persona](https://login.persona.org). Though elements of Portier's design appear in other projects, the specific combination of starting with an email address, attempting dynamic discovery, and then failing over to traditional email confirmation appears to be unique to Portier and Persona. | ||
|
||
In addition to Persona, Portier takes inspiration from [Poetica](https://poetica.com"), which had an excellent email-first login flow prior to its acquisition by Condé Nast. Specifically, users would enter an email address and then see a menu of compatible authentication options. Google Sign-In wouldn't appear for Yahoo! Mail users, and vice versa. Portier will work similarly, but will automatically select the best available method instead of prompting users. Poetica is also incapable discovering self-hosted providers, forcing users to choose between convenience and data sovereignty. | ||
|
||
There are many contemporary examples of login-via-email workflows. Slack has a "[Magic Link](http://louiiisechg.tumblr.com/post/130650909766/slack-magic-link)," while [Sandstorm](https://oasis.sandstorm.io/) and [Sideway](https://sideway.com/) offer to "Send Login Email." The [Passwordless](https://passwordless.net/) module for Node.js implements the same, as does [Auth0's Passwordless](https://auth0.com/passwordless) service. None of these systems are able to integrate with third party, web-based sign-in APIs. | ||
|
||
Finally, there are many examples of sending information to one device in order to verify interactions on another: Two-Factor Authentication (2FA) systems often ask users to finish logging in by transcribing a short code sent to their phone via SMS. Though Portier uses SMTP, the principle and user experience are comparable. [Digits](https://get.digits.com), by Twitter, offers this style of SMS-based verification as a service. | ||
|
||
## Portier Compared to Persona | ||
|
||
Though imbued with Persona's spirit, Portier is decidedly less ambitious and more narrowly scoped. | ||
|
||
> FIXME: Write this. Cover things like privacy from IdP, email address as id, | ||
> progressive enhancement via bridges, decentralization, native browser support, | ||
> same origin policy workarounds, three-way cold start, complexity, session | ||
> management, fallback accounts / passwords, the entire notion of an account, | ||
> associating multiple email addresses, visibility as an independent product vs | ||
> an infrastructure implementation detail, web native, custom or off-the-shelf | ||
> protocols, hosted verifier, budget, failure modes, third party cookies, | ||
> self-certification. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,127 +1,3 @@ | ||
# Let's Auth! | ||
# Portier | ||
|
||
Let's Auth is an upcoming spiritual successor to Persona. | ||
|
||
We are still in the early planning and prototyping stage. | ||
|
||
## Project Meetings + Chat | ||
|
||
The project meets [every Wednesday at 4 PM UTC](http://arewemeetingyet.com/UTC/2016-03-02/16:00/w/Let's%20Auth%20Weekly%20Meeting) in `#letsauth` on Freenode. | ||
|
||
You can also use [our synchronized Gitter room](https://gitter.im/letsauth/LetsAuth) instead of IRC. | ||
|
||
We have a [mailing list](https://groups.google.com/forum/#!forum/letsauth) for asynchronous discussion. | ||
|
||
## Contributing | ||
|
||
This project welcomes all contributors, and we expect people to treat each other respectfully here. | ||
|
||
Check out the open issues and feel free to jump right in! | ||
|
||
We're currently focused on two main repositories: | ||
|
||
- [letsauth.github.io](https://github.com/letsauth/letsauth.github.io/issues) - | ||
Project documentation and planning | ||
- [oidc-prototype](https://github.com/callahad/authbackend) - Prototype Let's Auth daemon that exposes an API compatible with OpenID Connect | ||
|
||
## Vision + Goals + Non-Goals | ||
|
||
Let's Auth aims to be the simplest way to add email-based authentication (login) to websites, without site-specific passwords. | ||
|
||
It frees users from the burden of creating and remembering strong passwords, and by removing the need to handle or store password-derived secrets, it protects developers from risks associated with database breaches. | ||
|
||
Let's Auth will be: | ||
|
||
- __Email First__ | ||
|
||
Email is the lowest common denominator for identity on the Internet. | ||
|
||
- __Low Friction__ | ||
|
||
Where practical, Let's Auth will integrate with protocols like OpenID Connect to provide seamless, in-browser identity verification. In all other cases, it will use traditional confirmation emails. | ||
|
||
- __Free from Lock-in__ | ||
|
||
Let's Auth transparently provides the user's verified email address to the website. | ||
|
||
(Technically, we provide [RFC 7565](http://tools.ietf.org/html/rfc7565) account identifiers and make no specific claims as to SMTP-routability. In practice, this distinction should be insignificant.) | ||
|
||
- __Self-hostable__ | ||
|
||
Anyone can host their own Let's Auth service; there are no centralized dependencies. | ||
|
||
- __Resilient__ | ||
|
||
In addition to self-hosting, sites can arbitrarily switch between Let's Auth services with just a configuration change. | ||
|
||
- __Simple to Deploy__ | ||
|
||
Let's Auth 1.0 will ship as a single, statically compiled binary. Pre-1.0, we will use a variety of dynamic languages for prototyping. | ||
|
||
- __Maintainable__ | ||
|
||
As a community-driven project, our survival is directly tied to the clarity and simplicity of our code. Every proposed feature will be weighed against its associated maintenance burden. | ||
|
||
- __Language and Framework Agnostic__ | ||
|
||
By implementing Let's Auth as a web service, it will integrate with any environment that speaks HTTP. | ||
|
||
Equally importantly, Let's Auth _will not_: | ||
|
||
- __Handle Profiles__ | ||
|
||
In the interest of simplicity and maintainability, Let's Auth is narrowly focused on authentication, not profile management. | ||
|
||
- __Richly Integrate with Facebook__ | ||
|
||
Facebook identities are not naturally thought of in terms of email addresses, so any sort of rich integration would require a bifurcated email-or-facebook workflow. The added maintenance costs and UI/UX complexity are not worth it for the Let's Auth project. Sites and third party libraries are, of course, welcome to combine Let's Auth and Facebook on their own. | ||
|
||
- __Guarantee Users' Privacy from Their Own Email Provider__ | ||
|
||
Let's Auth will attempt to protect privacy wherever possible, but future development may require revealing the target website to a user's email provider. We consider this acceptable, as providing any absolute protections is impossible: if a website ever contacts a user, that email implicitly reveals the user's association with the site. | ||
|
||
Privacy-conscious users can exercise control over the providers they trust by choosing a different email provider or self-hosting a domain. | ||
|
||
- __Promise Native Browser Integration__ | ||
|
||
We're a small, all-volunteer team. Browser integration would be nice, but it's an enormous amount of work, and universal adoption is so unlikely that sites could never depend on it. Thus, Let's Auth must, first and foremost, work on the Web as it is. | ||
|
||
- __Provide a Single Sign-On Solution__ | ||
|
||
Let's Auth is narrowly focused on authenticating email addresses for websites. It would make a great building block for an SSO system, but it is not an SSO system itself. | ||
|
||
## Architectural and Design Constraints | ||
|
||
We're still early on in the design process, so nearly everything is still up for debate. However, there's decent consensus on the following: | ||
|
||
- Let's Auth will exist as a standalone web service, which exposes an HTTP-based API for authenticating email addresses | ||
- The service will only be accessible over secure (SSL/TLS) connections | ||
- A single Let's Auth instance can service requests from an arbitrary number of relying sites | ||
- By default, sites should not need to pre-register with a Let's Auth instance before using it | ||
- Let's Auth instances will not require durable state, aside from static configuration data | ||
- We'll communicate verification claims as signed [JSON Web Tokens](https://jwt.io) | ||
|
||
Our initial prototype will aim to be compatible with the OpenID Connect specs, in order to minimize duplication of effort and ease integration with existing libraries. | ||
|
||
## Resources | ||
|
||
__Inspiration:__ | ||
|
||
- [Passwordless](https://passwordless.net) has similar goals, but implemented as a Node.js library instead of a standalone web service. We should learn from its design and features. Passwordless does not attempt to integrate with OpenID Connect or other protocols to streamline authentication. | ||
|
||
- [Poetica's sign in page](https://poetica.com/signin) is a beautiful example of email-first authentication. Let's Auth should look similar, but be more opinionated. For example, Poetica offers Gmail users an option of OpenID Connect or a confirmation email. Instead of presenting users with a choice, Let's Auth should automatically choose the best strategy. | ||
|
||
- [Digits](https://get.digits.com/) does a wonderful job of authenticating users by sending short verification codes over SMS. Our confirmation emails should offer a similar option: either click the link, or type in a code. This would make it possible for a user to complete authentication on a computer by glancing at their smartphone for the confirmation code. This has nice UX and privacy properties since the user isn't actually required to directly sign into their email account on the first device. | ||
|
||
__OpenID Connect:__ | ||
|
||
Our initial prototype, [callahad/authbackend](https://github.com/callahad/authbackend), aims to expose an interface that's compatible with OpenID Connect's provider discovery protocol and "implicit" authentication workflow. If successful, this would avoid duplicating effort, and would allow sites to leverage existing OpenID Connect client libraries when integrating Let's Auth. | ||
|
||
- [Core 1.0](http://openid.net/specs/openid-connect-core-1_0.html) | ||
- [Discovery 1.0](http://openid.net/specs/openid-connect-discovery-1_0.html) | ||
- [Implicit Flow Client Implementer's Guide 1.0](http://openid.net/specs/openid-connect-implicit-1_0.html) | ||
|
||
__JSON Web Tokens (JWTs)__ | ||
|
||
- [jwt.io](https://jwt.io) | ||
- [RFC 7519](https://tools.ietf.org/html/rfc7519) | ||
View this site at [portier.github.io](https://portier.github.io). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
# Portier Specifications | ||
|
||
> FIXME: Add more detail, link to specific sections of specs, use more precise language when defining what exactly Portier implements | ||
To avoid reinventing the wheel, Portier is built atop existing, proven standards. | ||
Specifically, the Portier Broker exposes itself to websites as a discoverable OpenID Connect (OIDC) Identity Provider supporting the "implicit" authentication workflow. | ||
|
||
## OpenID Connect | ||
|
||
The relevant OpenID Connect specifications are: | ||
|
||
- [Core 1.0](http://openid.net/specs/openid-connect-core-1_0.html), the main OpenID Connect specification. | ||
- [Discovery 1.0](http://openid.net/specs/openid-connect-discovery-1_0.html), which describes how websites can dynamically discover and interact with OpenID Connect Identity Providers, including the Portier Broker. | ||
|
||
## OAuth 2.0 | ||
|
||
OpenID Connect is built atop the OAuth 2.0 Core specification, with a few extension specifications that are used by Portier. | ||
|
||
- [Core](https://tools.ietf.org/html/rfc6749) (RFC 6749), the protocol atop which OpenID Connect was built. | ||
- [Multiple Respone Type Encoding Practices](http://openid.net/specs/oauth-v2-multiple-response-types-1_0.html), an extension by the OpenID Foundation, defines the `response_mode` request parameter and several new `response_type` values, including `id_token` and `none`. | ||
- [Form Post Response Mode](http://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html), another extension by the OpenID Foundation, defines the new `form_post` response mode, which Portier uses. | ||
|
||
## JSON Web Tokens (JWTs) | ||
|
||
Much of the data that Portier exchanges is in the form of JSON Web Tokens (JWTs), which are cryptographically signed JSON documents. | ||
|
||
- [RFC 7519](https://tools.ietf.org/html/rfc7519) defines JSON Web Tokens. | ||
- [jwt.io](https://jwt.io) offers learning materials and a great interactive tool for parsing and verifying JWTs. |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.