Identity/Verified Email Protocol/Session API

The Javascript API for Sessions

Draft

Getting the Firefox Addon

The sessions Firefox plugin can be downloaded from GitHub at Firefox Sessions Addon. When both the addon is installed and the site conforms to the API, a visual indicator will be displayed in the URL bar to the left of the HTTPS information.

Desired UX Flow

When a site supports the Sessions API, a small button to the left of the HTTPS information in the browser URL will appear, the button will be labeled "login." The user will be able to click this button with the intention that the page will redirect to the site's login page. Once the user logs in using the sites login mechanism, the "login" button will be changed to show the user's current login name. The user will be able to click this button which shows a doorhanger that shows the user's possible logins (for sites such as Google that support multiple accounts), which user they are currently logged in as, as well as the ability to log out of the site. If the user has multiple accounts on a site and they select a different account from the currently selected account, the user will be logged out of the first account and into the second. The button in the URL bar will be updated to display the new username. If the user logs out of all accounts, the button in the URL bar will again display "login."

The API

All interaction with the sessions API occurs through navigator.id.sessions and two new DOM events - "login" and "logout", both of which are triggered on window.document.

Indicating Support

For a site to indicate it wishes to have the browser display login information, it must set information in navigator.id.sessions. A site which does not set navigator.id.sessions will act as it does today where no visual indication is given.

To indicate support, but with no users logged in, the site must set navigator.id.sessions to be an empty array([]).

   // Indicate that site supports sessions scheme, no user logged in.
   navigator.id.sessions = [];

Login DOM Event

When no user is currently logged into the site, but the site indicates that it supports the Session API, a button will be displayed in the URL bar displaying "login." When the user clicks this button, the "login" event will be triggered on the current window/tabs window.document. The site should attach an event handler which performs the login, whether this is through a page redirect or within the current page.

Session Declaration

Once the user has authenticated with the site, the site must set information in navigator.id.sessions. navigator.id.sessions is an array that can hold one or more possible sessions. Each Session object contains the following fields:

  [Constructor]
  interface Session {
      attribute string id;
      attribute string status;
      attribute object bound_to;
  }

• id:string, required. Identifier/email address the session is associated with
• status: string, optional. The status may be "active", representing a "logged in" state, or "passive", representing a tracking session without an active log-in. The status field is optional, and defaults to "active".
• bound_to: object, optional. An object holding binding information:

   interface SessionBinding {
       attribute string type;
       attribute string cookie_name;
   }

• type: string, required. only supported value is "cookie"
• cookie_name: string, required if type is "cookie". string of cookie

A site can use the session binding as a cookie based fallback mechanism for when it is not possible to declare the navigator.id.sessions array because the page is content other than HTML. An example includes browsing to an image from Wikipedia.

Once a site declares a binding, the binding is only available *on the same domain*. If the initial binding information is declared at www.example.com and the user then goes to subdomain.example.com, binding information must be redeclared. If neither session information nor binding information are available for subdomain.example.com, the browser will assume that the page does not support the session API and remove the session status indicator.

The site can set navigator.id.sessions at any point in the page lifetime. If changing from one page where the user is authenticated to another, navigator.id.sessions must be set before the DOMContentLoaded or else a flicker may occur in the visual indicator.

Session Redeclaration

Once a site declares session information, on every subsequent page load either the page must redeclare its session information or there must be binding information available for that domain. If neither are available, the browser will assume the page does not support the session API and remove the session status indicator.

Changing Sessions

• • • This needs hammered out, how is this going to work?

We could trigger a logout, then a login, but unless the site knows that the user is trying to change sessions, it may redirect the user to the logout page, breaking the flow.

Could we trigger the login directly but pass the id the user is trying to log in with? This would also cover multiple inactive sessions. Once the site receives the login event when a session is already active, it could take appropriate action.

Updating/Clearing Session Information

A site can, at any time, force an update of the session information.

Logout DOM Event

Once the user is logged in and session information