View source for Identity/Verified Email Protocol/Session API

= Warning =

Portions of this document are out of date. For a short overview of the API (might be more useful than this doc) check out this page: [[Identity/Verified_Email_Protocol/Latest-Session]]

=The Javascript API for Sessions=

;Draft

==Getting the Firefox Addon==
The sessions Firefox plugin can be downloaded from GitHub at [https://github.com/mozilla/browserid_addon/tree/master/addons/sessions/ 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 the button with the intention of being directed to the site's login.  Once the user completes authentication, the "login" button will be changed to show the user's current login name.  The user can click this button to show a doorhanger that displays:

* the user's possible logins (for sites such as Google that support multiple accounts)
* which user they are currently logged in as
* give the ability to log out of the site.  

If the user has multiple accounts on a site and are currently logged in as user A, but then select user B, user A will be logged out and user B will be logged in.  Once user B is selected, the button in the URL bar will be updated to reflect this change.  If the user logs out of all accounts the button in the URL bar will 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 its wish to have the browser display session information, it must add the information to navigator.id.sessions.  A site which does not set navigator.id.sessions will have no visual indication, the same as sites today.

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

====Example - Indicate site support for Sessions API====
    navigator.id.sessions = [];

===Login DOM Event===
If a site has indicated that it supports the Sessions API by setting navigator.id.sessions = [], a "Login" button will be displayed in the URL bar.  When the user clicks this button, the "login" event will be triggered on the current tab's 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 and AJAX calls.

====Example - login event====
    document.addEventListener('login', function(event) {
        document.location.href = /* login page URI here */;
    }, false);

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

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

* email: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 instances when it is not possible to declare the navigator.id.sessions.  An example includes browsing to an image from Wikipedia where Javascript is not available.  As long as the cookie exists, it will be assumed that the session is still active.  If the cookie is removed, the browser will then search for information in navigator.id.sessions.

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's lifetime.  If the user browses from one page where they have session information to another page where they should have session information, the session information must be made available before the DOMContentLoaded to avoid flicker in the visual indicator.

====Example - No binding information====
    // Every page within domain must redeclare navigator.id.sessions
    navigator.id.sessions = [{
        email: 'poohbear@ashdownforest.gov.uk'
    }];

====Example - Binding information====
    // No other page within domain needs to declare navigator.id.sessions
    navigator.id.sessions = [{
        email: 'yogibear@jellystone.nps.gov',
        bound_to: {
            type: 'cookie',
            cookie_name: 'SID'
        }
    }];

===Session Redeclaration===
Once a site declares session information, it must have session information available on every page within the domain to avoid status flicker.  The session information is searched for in the following order:

* navigator.id.sessions
* if navigator.id.sessions is undefined, in the binding information for the domain. 

If neither are available, the browser will assume both that the session information has expired and the page does not support the session API - it will remove the session status indicator.

===Multiple Sessions - NOT YET SUPPORTED ===
Multiple sessions can be declared in navigator.id.sessions, there can be 0 or 1 active sessions.  An example of where this could be used is with Google's multiple session support.  If more than one session is declared "active" only the first will be used.

====Example - Multiple sessions, none active====
    // Our bear is masquerading as two bears.
    navigator.id.sessions = [{
        email: 'poohbear@ashdownforest.gov.uk'
    }, {
        email: 'yogibear@jellystone.nps.gov',
    }];

====Example - Multiple Sessions, one active====
    // Our bear is masquerading as two bears.
    navigator.id.sessions = [{
        email: 'poohbear@ashdownforest.gov.uk',
        status: 'active'
    }, {
        email: 'yogibear@jellystone.nps.gov',
    }];

If 0 sessions are currently active, the browser status button will read "login".  When the user clicks the button, they will be presented a the doorhanger to select a session.  When the user selects a session, the "login" event will be triggered with the selected id given as the "id" field of the event object.

===Changing Sessions - NOT YET SUPPORTED ===

;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.

A better alternative is to directly trigger the login with the new id in the event object.  If a session is already established with the site, it should invalidate the old session and begin the procedure for logging in with the new id.

===Updating/Clearing Session Information===
A site can, at any time, force an update of the session information.  It can do this by setting navigator.id.sessions to indicate the updated state.

====Example - Fall back to searching binding information====
    navigator.id.sessions = undefined;

====Example - Remove all sessions====
    navigator.id.sessions = [];

====Example - Update to a new account====
    navigator.id.sessions = [{ email: 'example@mozilla.com' }];

If removing all sessions by setting navigator.id.sessions = [], all binding information for the domain will be cleared and cookies will be ignored.

===Logout DOM Event===
After the user has session information set, they can click the button with their name in the URL to show a doorhanger with their session information.  The user can logout of the site from here by clicking "logout" next to their active session.

The "logout" DOM event will be triggered on window's document.

====Example - logout event====
    document.addEventListener("logout", function(event) {
        // Go to site's logout page
    }, false);