Skip to content

Latest commit

 

History

History
86 lines (56 loc) · 3.24 KB

Specs.md

File metadata and controls

86 lines (56 loc) · 3.24 KB
Raw

Portier Specifications

The Portier protocol is composed of several smaller documents listed on this page.

Terminology

Some common terminology is used everywhere we try define the Portier protocol:

  • User: The person that wants to authenticate with a Relying Party.

  • User Agent (UA): A web browser, or similar application, being directly controlled by the User.

  • Relying Party (RP): A website that wants to authenticate Users by their email address, using Portier.

  • Identity: A handle that identifies the online presence of a User. In Portier, this is an email address.

  • Identity Provider (IdP): A website appointed by the User to control their Identity.

  • Identity Provider Discovery: The method with which the Identity Provider is discovered, based on the User email address.

  • Broker: A website trusted by the Relying Party that implements User authentication, optionally using Identity Provider Discovery and delegating to an Identity Provider.

Documents

  • Email Normalization, relevant to Broker implementors, and possibly Relying Party implementors that need to compare email addresses.

  • Portier Authentication Protocol, relevant to Relying Party, Broker and Identity Provider implementors.

  • Identity Provider Discovery Protocol (TODO)

  • Identity Provider Authentication Protocol (TODO)

Referenced External Standards

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.

FIXME: Add more detail, link to specific sections of specs, use more precise language when defining what exactly Portier implements

OpenID Connect

The relevant OpenID Connect specifications are:

  • Core 1.0, the main OpenID Connect specification.
  • Discovery 1.0, 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 (RFC 6749), the protocol atop which OpenID Connect was built.

  • Multiple Respone Type Encoding Practices, 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, 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 defines JSON Web Tokens.

  • jwt.io offers learning materials and a great interactive tool for parsing and verifying JWTs.