Identity/Verified Email Protocol/Latest-Session: Difference between revisions

(Created page with "__TOC__ ''WikiMedia editor tip: If you aren't seeing numbered section headings in the body of this document, you can force them to appear by logging in and clicking the "My prefe...")
 
(Add deprecation notice; point people to BrowserID.)
 
(5 intermediate revisions by one other user not shown)
Line 1: Line 1:
__TOC__
{| class="fullwidth-table"
''WikiMedia editor tip: If you aren't seeing numbered section headings in the body of this document, you can force them to appear by logging in and clicking the "My preferences" link, at left, and select "Auto-number headings"''  
|-
| '''Note: The Verified Email Protocol has been deprecated. Please check the [[Identity/BrowserID|BrowserID]] protocol.'''
|}


= Session Description Protocol Specification =
So you want to implement the Session API. Great! We're still working on better docs, but so far we have:


;DRAFT
* A [http://www.shanetomlinson.com/2011/mozilla-session-api-tutorial/ tutorial] on Shane's blog for how to use it.
* An [[Identity/Verified_Email_Protocol/Session_API|API doc]]
* The following block of code which shows off most of the API:


== Terms ==
// All logic needs to be wrapped in the if(navigator.id) block so that we do not break
 
// non-supporting browsers.
;Identity
if(navigator.id) {
:An email address which the user has control over.
  // indicate support - for before the user is logged in.
 
  navigator.id.sessions = [];
;Web Site
:A Web site which has established one or more sessions with the browser, keyed on a specific Identity.
  // user logged in, no cookies - for once the user is logged in.
 
  navigator.id.sessions = [{ email: "user@foo.com" }];
== Objects ==
Note: Object definitions below are written in Web IDL.
  // user logged in, bound to cookie named SID - for once the user is logged in.
 
  navigator.id.sessions = [{
;SessionBinding
    email: "user@foo.com",
 
    bound_to: {
  interface SessionBinding {
      type: "cookie",
     attribute string type;
      cookie_name: "SID"
    attribute cookieName;
    }
  }];
  // login/logout events are triggered on document when the user clicks the appropriate button.
  document.addEventListener("login", function(event) {
    // redirect to login page
    document.location.href = ...;
  }, false);
   
  document.addEventListener("logout", function(event) {
     // redirect to logout page
    document.location.href = ...;
  }, false);
  }
  }
;Session
A Session object describes an individual session the Web Site has with the current User Agent.
* The id attribute is the email address the session is associated with.
* 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".
* The binding attribute is a SessionBinding object.
* The terminate is a URL string. Optional.
[Constructor]
interface Session {
    attribute string id;
    attribute string status;
    attribute object binding;
    attribute string terminateURL;
}
;SessionArray
(array of Sessions?)
== Browser-Level API ==
;navigator.id.sessions
Set by the Web Site to a SessionArray.
;navigator.id.terminateSession
Optionally set by the Web Site to a function;
WebIDL:
module navigator {
    module id {
        attribute object sessions;
        attribute object terminateSession;
    }
};
== Session Description ==
The Web Site [may?should?must?] set the navigator.id.sessions attribute to describe its current sessions to the User Agent.
== Session Termination ==
The Web Site MAY set the terminateURL property of a Session object to a URL, which the User Agent MUST load in the current top-level page of the Web Site, or in a new tab, except as described below. [XXX]
The Web Site MAY set the navigator.id.terminateSession attribute to a function of its choosing. If set, the User Agent MUST call this function upon session termination, and it MUST NOT fetch the terminateURL resource set in the Session object, if any.
== unorganized notes ==
1. Declaring a session is done by adding a session object to the
navigator.id.sessions array property. (note: there can be multiple
session objects)
2. A session object is a JavaScript object with the following properties:
* id:string, required. email address the session is associated with
* status: string, required. can be "active" or "passive"
* bound_to: object, required. contains these properties:
** type: string, required. only supported value is "cookie"
** cookie_name: string, required if type is "cookie". string of cookie
ID to bind lifetime of the session to.
* terminate_url: string, optional. url to load in the current tab if
user invokes logout from browser chrome
3. Session scope and lifetime
Sessions are valid only for the exact origin that declared the
session. No hierarchies or other schemes will be assumed by the user
agent. Multiple origins may declare sessions that are bound to the
same cookie, however. After a session is declared, the user agent may
assume the session is valid on a given page if the cookie it is bound
to was sent to the server.
That's it. In the future, the last rule may be relaxed slightly, and a
session may be assumed valid while loading a page on the same or
similar origin (i.e. under the same hierarchy), up until a certain
event has passed. This would allow larger multi-origin sites to
provide a seamless, flicker-free session UI across their site.
"Multiple origins may declare sessions that are bound to the
same cookie"
By this we mean multiple origins that share a root domain, i.e. finance.yahoo.com and health.yahoo.com, since that's the only way you can have different origins sharing a cookie.
"After a session is declared, the user agent may assume the session is valid on a given page if the cookie it is bound to was sent to the server"
*and* if the cookie value hasn't changed since the time the session was declared.
== References ==
* WebIDL: [http://www.w3.org/TR/WebIDL/ http://www.w3.org/TR/WebIDL/]

Latest revision as of 19:14, 3 April 2012

Note: The Verified Email Protocol has been deprecated. Please check the BrowserID protocol.

So you want to implement the Session API. Great! We're still working on better docs, but so far we have:

  • A tutorial on Shane's blog for how to use it.
  • An API doc
  • The following block of code which shows off most of the API:
// All logic needs to be wrapped in the if(navigator.id) block so that we do not break
// non-supporting browsers.
if(navigator.id) {
  // indicate support - for before the user is logged in.
  navigator.id.sessions = [];

  // user logged in, no cookies - for once the user is logged in.
  navigator.id.sessions = [{ email: "user@foo.com" }];

  // user logged in, bound to cookie named SID - for once the user is logged in.
  navigator.id.sessions = [{
    email: "user@foo.com",
    bound_to: {
      type: "cookie",
      cookie_name: "SID"
    }
  }];

  // login/logout events are triggered on document when the user clicks the appropriate button.
  document.addEventListener("login", function(event) {
    // redirect to login page
    document.location.href = ...;
  }, false);

  document.addEventListener("logout", function(event) {
    // redirect to logout page
    document.location.href = ...;
  }, false);
}