API tweak proposal - A complimentary and optional session management API

[Austin King]

Occasionally, we're suggesting developers use the get API, instead of
the watch API.

Proposal:
Persona authentication should come in two compatible layers which match
a web developers mental model:

1) get me a verified email
2) additionally, do session management

Everyone must use the 1st API call, because that is "using Persona".

Websites can opt into Persona session semantics by also using the 2nd
API call, which has many benefits as well as some constraints.

[Dan Callahan]

+1, <3.

Do you have an idea of what those calls would look like in practice?

If not... off the top of my head:

Right now, .watch() requires onlogin *and* onlogout, so it can do
session management.

What if we just made onlogout optional, and only required onlogin?

.watch({onlogin:}) == no session management
.watch({onlogin:,onlogout:)} == session management

-Callahad

[Sean McArthur]

[+ some folks in webdev that use Persona]

This sounds like the right goal. Some people will enjoy not having to
manage state, but existing websites really have trouble with the current
watch().

I had some similar conversations with mkelly, and I experimented in this
gist based on his feedback: https://gist.github.com/seanmonstar/5561248

On Jun 4, 2013 9:28 AM, "Austin King" <oz...@mozilla.com> wrote:

> Occasionally, we're suggesting developers use the get API, instead of the
> watch API.
>
> Proposal:
> Persona authentication should come in two compatible layers which match a
> web developers mental model:
>
> 1) get me a verified email
> 2) additionally, do session management
>
> Everyone must use the 1st API call, because that is "using Persona".
>
> Websites can opt into Persona session semantics by also using the 2nd API
> call, which has many benefits as well as some constraints.

> ______________________________**_________________
> dev-identity mailing list
> dev-id...@lists.mozilla.org
> https://lists.mozilla.org/**listinfo/dev-identity<https://lists.mozilla.org/listinfo/dev-identity>
>

[Zachary Carter]

----- Original Message -----
> From: "Sean McArthur" <sean.m...@gmail.com>
> To: "Austin King" <oz...@mozilla.com>, "Michael Kelly" <mke...@mozilla.com>, mba...@mozilla.com
> Cc: dev-id...@lists.mozilla.org
> Sent: Tuesday, June 4, 2013 9:58:26 AM
> Subject: Re: API tweak proposal - A complimentary and optional session management API
>
> [+ some folks in webdev that use Persona]
>
> This sounds like the right goal. Some people will enjoy not having to
> manage state, but existing websites really have trouble with the
> current
> watch().
>
> I had some similar conversations with mkelly, and I experimented in
> this
> gist based on his feedback:
> https://gist.github.com/seanmonstar/5561248

Very nice. I also spoke with mkelly at JSConf and this captures what he told me as well.

+1

> On Jun 4, 2013 9:28 AM, "Austin King" <oz...@mozilla.com> wrote:
>
> > Occasionally, we're suggesting developers use the get API, instead
> > of the
> > watch API.
> >
> > Proposal:
> > Persona authentication should come in two compatible layers which
> > match a
> > web developers mental model:
> >
> > 1) get me a verified email
> > 2) additionally, do session management
> >
> > Everyone must use the 1st API call, because that is "using
> > Persona".
> >
> > Websites can opt into Persona session semantics by also using the
> > 2nd API
> > call, which has many benefits as well as some constraints.
> > ______________________________**_________________
> > dev-identity mailing list
> > dev-id...@lists.mozilla.org
> > https://lists.mozilla.org/**listinfo/dev-identity<https://lists.mozilla.org/listinfo/dev-identity>
> >

> _______________________________________________
> dev-identity mailing list
> dev-id...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-identity
>

[Matt Basta]

I think a larger goal should be to, rather than add a client-side session API, create a series of plugins for Django, Flask, etc. that replaces their built-in session functionality with a Persona-based session system. As it stands, it's virtually impossible to properly integrate Persona with server-based sessions without doing hard page reloads after signing the user in or out. Having a way to make the server magically play along with the Persona auth dance would be extremely useful.

----- Original Message -----
From: "Sean McArthur" <sean.m...@gmail.com>
To: "Austin King" <oz...@mozilla.com>, "Michael Kelly" <mke...@mozilla.com>, mba...@mozilla.com
Cc: dev-id...@lists.mozilla.org
Sent: Tuesday, June 4, 2013 9:58:26 AM
Subject: Re: API tweak proposal - A complimentary and optional session management API



[+ some folks in webdev that use Persona]

This sounds like the right goal. Some people will enjoy not having to manage state, but existing websites really have trouble with the current watch().

I had some similar conversations with mkelly, and I experimented in this gist based on his feedback: https://gist.github.com/seanmonstar/5561248

On Jun 4, 2013 9:28 AM, "Austin King" < oz...@mozilla.com > wrote:


Occasionally, we're suggesting developers use the get API, instead of the watch API.

Proposal:
Persona authentication should come in two compatible layers which match a web developers mental model:

1) get me a verified email
2) additionally, do session management

Everyone must use the 1st API call, because that is "using Persona".

Websites can opt into Persona session semantics by also using the 2nd API call, which has many benefits as well as some constraints.

______________________________ _________________
dev-identity mailing list
dev-id...@lists.mozilla.org
https://lists.mozilla.org/ listinfo/dev-identity

[Jared Hirsch]

Hey Austin,

I think this is a really interesting idea, and I'd love to see an
alternative API in prototype form. I'd also be down to hack on this some
Friday.

Cheers,

Jared

On Tue, Jun 4, 2013 at 9:27 AM, Austin King <oz...@mozilla.com> wrote:

> Occasionally, we're suggesting developers use the get API, instead of the
> watch API.
>
> Proposal:
> Persona authentication should come in two compatible layers which match a
> web developers mental model:
>
> 1) get me a verified email
> 2) additionally, do session management
>
> Everyone must use the 1st API call, because that is "using Persona".
>
> Websites can opt into Persona session semantics by also using the 2nd API
> call, which has many benefits as well as some constraints.

> ______________________________**_________________
> dev-identity mailing list
> dev-id...@lists.mozilla.org
> https://lists.mozilla.org/**listinfo/dev-identity<https://lists.mozilla.org/listinfo/dev-identity>
>

[Lloyd Hilaiel]

Yeah. This is intriguing. The promises aspect is a bit fancy for my taste - and I don't know that we'll find much precedent in existing dom apis. Also, automatic should probably read "only will be invoked if the user was logged in while the page was not loaded". Subtly different, but I don't see how any other semantic makes sense.

But generally, the claim here is we can significantly simplify our api by getting out of the business of ending sessions via JavaScript. This sacrifices some features - resetting your persona password would no longer sign you out everywhere.

Overall though, given the volume of feedback, I'd like to explore this more... Others?

Lloyd

Zachary Carter <zca...@mozilla.com> wrote:



----- Original Message -----
> From: "Sean McArthur" <sean.m...@gmail.com>
> To: "Austin King" <oz...@mozilla.com>, "Michael Kelly" <mke...@mozilla.com>, mba...@mozilla.com
> Cc: dev-id...@lists.mozilla.org
> Sent: Tuesday, June 4, 2013 9:58:26 AM
> Subject: Re: API tweak proposal - A complimentary and optional session management API
>
> [+ some folks in webdev that use Persona]
>
> This sounds like the right goal. Some people will enjoy not having to
> manage state, but existing websites really have trouble with the
> current
> watch().
>
> I had some similar conversations with mkelly, and I experimented in
> this
> gist based on his feedback:
> https://gist.github.com/seanmonstar/5561248

Very nice. I also spoke with mkelly at JSConf and this captures what he told me as well.

+1

> On Jun 4, 2013 9:28 AM, "Austin King" <oz...@mozilla.com> wrote:
>
> > Occasionally, we're suggesting developers use the get API, instead
> > of the
> > watch API.
> >
> > Proposal:
> > Persona authentication should come in two compatible layers which
> > match a
> > web developers mental model:
> >
> > 1) get me a verified email
> > 2) additionally, do session management
> >
> > Everyone must use the 1st API call, because that is "using
> > Persona".
> >
> > Websites can opt into Persona session semantics by also using the
> > 2nd API
> > call, which has many benefits as well as some constraints.
> > ______________________________**_________________
> > dev-identity mailing list
> > dev-id...@lists.mozilla.org
> > https://lists.mozilla.org/**listinfo/dev-identity<https://lists.mozilla.org/listinfo/dev-identity>
> >

> _______________________________________________
> dev-identity mailing list
> dev-id...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-identity
>
_______________________________________________
dev-identity mailing list
dev-id...@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-identity

[Sean McArthur]

Yea, I included promises because he asked for them, and I had fun writing
them. I said that would be the hardest part to sell. Though, there is
currently DOMFutures in the proposal stage at W3C...

[Francois Marier]

On 05/06/13 09:32, Lloyd Hilaiel wrote:
> But generally, the claim here is we can significantly simplify our api by getting out of the business of ending sessions via JavaScript.

That does look like Dan's claim, but is that really what's preventing
people from using the watch API?

It seems to me that onlogout is typically an easy callback to write and
that the things that are more complicated in .watch() v. .get() are:

- passing loggedInUser from the backend to the front-end
- dealing with the unpredictability of when (and if) callbacks will fire

Francois

[Shane Tomlinson]

On 04/06/2013 17:58, Sean McArthur wrote:
> [+ some folks in webdev that use Persona]
>
> This sounds like the right goal. Some people will enjoy not having to
> manage state, but existing websites really have trouble with the current
> watch().
>
> I had some similar conversations with mkelly, and I experimented in this
> gist based on his feedback: https://gist.github.com/seanmonstar/5561248

TLDR; I am laying out the use cases, as well as the problems I am
running in to, while using the .watch API with the Wordpress Persona
plugin. If you don't care about the gory details, skip this email.

=========================================

Sean, this is the first I have seen these ideas, I like where they are
going.Can the same functionality (minus the promises) be retrofitted
into the current .watch/.request API via additional parameters?

I am going to lay out in detail the use cases I have recently run up
against in the Wordpress plugin. The Wordpress plugin is probably a
unique in that sometimes Persona is used to sign a user up/in to the
site as a member, at other times it is used as a quick way to verify an
email addresses when a visitor want to leave a comment. We want both of
these sets of functionality to exist together, at the same time.
Sometimes we want full on session handling. At other times we want a one
time assertion.

Use case - user sign in

1) Users: Existing Persona users *or* new users signing in with an IdP
backed address.

Desired Behavior: User never leaves dialog, completes sign in in
same tab they start in. No problem here.
Existing Behavior: Same as existing behavior.

2) Users: User who must verify their email address with Persona.

Desired Behavior: User verifies their email address with Persona, is
redirected back to Wordpress,
is signed in, and are redirected to their profile page.
Existing Behavior: The same as existing behavior.

Use case - user signup

Because of my own lack of understanding of how Wordpress fits together,
I am trying to use already existing facilities and retrofit Persona on
top of it. This means I ask for a username first, verify the user using
Persona, and then submit the new user form. If I knew how to stage the
info on the back end until verification, this would be *much* easier,
but, I do not. We do not have the ability to hotpatch Core Wordpress
files to add needed functionality, and we do not want to change too much
existing behavior and risk collisions with other plugins or long term
diversion from core Wordpress functionality.

1) Users: Existing Persona users *or* new users signing in with an IdP
backed address.

Desired Behavior: User fills out new username, clicks "sign in with
Persona."
The user verifies with Persona, the registration form is
submitted, and a new account is created.
Existing Behavior: Same as desired behavior.

2) Users: User who must verify their email address with Persona.

a) Verification Method: User verifies in same tab by replacing
currently existing window.

Desired Behavior: redirect user to sign up page, re-load
previously saved new user state, submit form.
Existing Behavior: same as desired, using localStorage to
re-load previously filled out state.

b) Verification Method: User verifies in a different tab while
keeping original tab open.
User's original page is Tab A. User verifies in Tab B.

Desired Behavior: User opens new tab to verify with Persona, is
then redirected to the
signup page where the new user form is submitted, IFF there
is an error (like the
user name is already taken), show the error. Otherwise, the
user is redirected to
their profile page where they can fill out additional
profile information. Tab A
does nothing. It finds out that Tab B was opened and stands
down. If it takes any
action, it should redirect to the profile page when Tab B
completes registration.

Existing Behavior: This is a nightmare. We don't know which tab
will receive its assertion
first. Sometimes it is Tab A, sometimes it is Tab B. We
always want Tab B to show any
registration errors because the user is at Tab B. To try to
do this, before the user
opens the Persona dialog, we save all sign up state to
localStorage. Since we have no
way of definitively knowing by time Tab A receives its
assertion whether Tab B has
been opened (like case 2A), the first tab to receive the
assertion adds the assertion
to the signup form and submits. The second tab to receive
its assertion busy waits
for a "I'm done" or "Houston, there was a problem!" signal
from the tab that
submitted the form. If there was a problem, for example, if
the username is already
registered, both tabs show the error.

For both Sign Up and Sign In, we want Persona to have a hand in managing
sessions after the user signs in.

For commenting though, this is not the case. We only want an assertion
so the user can submit a comment. We cannot mix .get and .watch on the
same page. We have to jump through additional hoops.

Use case - visitors who leave a comment

Unlike new user sign up, it does not make sense to consider having the
user verify their email address first and then ask them to leave a comment.

1) Users: Existing Persona users *or* new users signing in with an IdP
backed address.

Desired Behavior: User fills out comment, clicks "sign in with
Persona."
The user verifies with Persona, the comment form is submitted,
no session is created.
The user is not marked as "signed in to this site" with Persona.
Existing Behavior: Same as desired behavior, but doing this with
.watch is a pain. Remember .watch
is registered on every page to handle normal member sign ins. If
the user leaves a comment and
is not signed in to the site as a member, when .onlogin is
called, we have to immediately
call navigator.id.logout() to prevent the .onlogin callback from
being fired on every subsequent
page the user visits.

2) Users: User who must verify their email address with Persona.

a) Verification Method: User verifies in same tab by replacing
currently existing window.

Desired Behavior: User fills out comment, clicks "sign in
with Persona."
The user verifies with Persona, the previous state of
the comment form is re-loaded,
submitted, no session is created. The user is not marked
as "signed in to this site"
with Persona.
Existing Behavior: Matches desired behavior by saving form
state to localStorage.

b) Verification Method: User verifies in a different tab while
keeping original tab open.

Desired Outcome: User opens new tab to verify with Persona,
is then redirected to the
comment page where the comment form is submitted, IFF there
is an error (like the
comment already exists), show the error. Otherwise, the
user is redirected to
their new comment. Tab A does nothing. It finds out that
Tab B was opened and
stands down. If Tab A takes any action, it should redirect
to the new comment once
Tab B completes submission.

Existing Behavior: All of the same nightmares as "User Sign
Up:2b" with the additional
caveat that user is not marked as "signed in to this
site" with Persona.


===================================================


Remedies to what is ailing me.

I want to be able to use .watch and .get like functionality at the same
time. .watch for session management of members. .get for visitors who
leave comments.

Potential Solutions:
* add a "no_session" flag to .request.
* Allow .get and .watch to co-exist.

I also want a way for users who verify in Tab B to notify Tab A that
their onlogin should be ignored. Maybe this
is of the form of a new parameter when calling .watch or .request, or
perhaps an additional field when returning the assertion that says "user
verified in another window and is going to be redirected". I want this
to work whether Tab A or Tab B receives its assertion first.

We keep saying that BigTent is going to remedy loads of these problems
for the majority of users, and it will. But, for the 30% of the users
not covered under BigTent who do not yet have a Persona account, I still
want the plugin's UX to be awesome. I don't want them to have to create
a Persona account and then re-submit their comment. I don't want them to
have to create a Persona account and then have to re-submit the
authentication form. And I don't want to rewrite large portions of the
Wordpress core logic to stage data and then fully submit it once the
user verifies.

Goodness.

Shane

[Francois Marier]

On 05/06/13 23:38, Shane Tomlinson wrote:
> I want to be able to use .watch and .get like functionality at the same
> time. .watch for session management of members. .get for visitors who
> leave comments.

Me too. Working about the watch() API is far too painful:


http://feeding.cloud.geek.nz/posts/migrating-libravatar-to-persona/#Working_around_the_internal_login_state

> Potential Solutions:
> * add a "no_session" flag to .request.
> * Allow .get and .watch to co-exist.

I like the second approach because it sounds like it should be easy to
do in the code and we don't have to do anything documentation-wise
because it's just a matter of using the other supported API.

In any case, I think we need to re-open one of these two bugs:

https://github.com/mozilla/browserid/issues/2152
https://github.com/mozilla/browserid/issues/853

Because there is demand for this feature.

Francois

[Austin King]

Here is a concrete proposal that I worked out with callahad:

navigator.id.request takes an optional first parameter which is a function.
If you call request(function(assertion) {
// validate assertion
}, options);

then the SHIM or native implementation won't do any session management.

This is called "using the *basic request* API".

Optionally... a website can opt into session management (and other
benefits) by using today's watch API

navigaor.id.watch({
onlogin: function(assertion) {
// validate assertion
},
onlogout: function() {

},
...
});

navigator.id.request(options);

(It is a programming error to use watch and pass a function as the first
argument to request.)

This is called "using the *full watch* API".

[Lloyd Hilaiel]

Counter proposal:

// invoked when user logs in via the dialog or when user has logged in while the site
// was not loaded.
navigator.id.onlogin(function(assertion) {
// post the assertion and create a session
});

// invoke in a window handler to cause the dialog to open
navigator.id.request();

// assertions gain a new property that is returned from the verifier
suggestedSessionDuration: // session duration in seconds

Reasons I like this better:
1. it is a single API instead of two
2. it still lets us handle assertion delivery for cases where the site was not loaded (which is important, because we cannot support embedded WebViews, chrome iOS, possibly the "" and other environments without it)
3. The suggestedSessionDuration gives a hint to sites to help keep session durations short when the user is on a shared computer
4. we can regain the log-me-out-everywhere functionality when we get native support.
5. it's no longer required for the site to supply "logged in user"
6. assertion delivery for the case where the site was not loaded can be fast. We can actually have a zero API request path if the authentication happened "recently"
7. minimal resource loading is required when the user is not logged in.
8. we can add this without breaking current watch in experimental status

Many of these benefits apply to the other proposals.

holes?

lloyd

[Lloyd Hilaiel]

Sorry guys, typing too fast.

On Jun 8, 2013, at 2:37 PM, Lloyd Hilaiel <ll...@mozilla.com> wrote:
> // invoke in a window handler to cause the dialog to open

not a window handler, but a CLICK handler

> 2. it still lets us handle assertion delivery for cases where the site was not loaded (which is important, because we cannot support embedded WebViews, chrome iOS, possibly the "" and other environments without it)

"" is the "silent login for services case", that is where yoursite.com uses openbadges.com or firebase.com, and you want to be logged into the dependent site without giving them too much control (passing firebase an assertion with full authority to authenticate you to yoursite.com), and you want that site to be authorized to share only data that was stored in the service while you were logged into yoursite.com. Francois and I and others were discussing this feature on list as a cowpath that's emerging that we'd like to pave.

My point is, I think there are more and more cases where automatic login is really valuable to users and sites. Automatic logout is important from a privacy perspective, but it's really "kid sister" security without native support, and it seems less important to users and sites.

This whole line of thinking is basically asking whether we're willing to sacrifice features around login to make the API simpler and improve adoption.

lloyd

[Francois Marier]

These are really two orthogonal proposals:

1. removing onlogout and loggedInUser from the watch API
2. adding a session duration hint to assertions

I like both proposals. I think the session management stuff is easy to
explain, but when it comes time to actually implement it, there are lots
of pitfalls.

One thing I'd like to understand better first though is why mkelly had
to work-around automatic logins in django-browserid. Proposal #1 doesn't
address that. I don't understand the use case that forced this decision
in django-browserid and I feel that if we're going to revise the watch
API, it should fix django-browserid's problem.

Francois

[Shane Tomlinson]

On 08/06/2013 21:37, Lloyd Hilaiel wrote:
> Counter proposal:
>
> // invoked when user logs in via the dialog or when user has logged in while the site
> // was not loaded.
> navigator.id.onlogin(function(assertion) {
> // post the assertion and create a session
> });
>
> // invoke in a window handler to cause the dialog to open
> navigator.id.request();
>
> // assertions gain a new property that is returned from the verifier
> suggestedSessionDuration: // session duration in seconds

Lloyd,
I am having trouble figuring out whether this is any better than the
existing API for the specific problems/use cases I see in the Wordpress
plugin.

Does this proposal:
1) still do any sort of session management?

2) If yes, does it allow both session management and one time assertions
to be requested during a single page load (member session management is
enabled on all pages vs a visitor posting a comment and wants a 1 time
assertion)?

3) help with the post-verification blues? As an RP, I want commenting to
be great for 95+ % of new users, not just 70. If users open a new tab to
verify their email address, I want the original tab to basically do
nothing. To make that a reality, assertion generation timing involving 2
tabs must be predictable or there must be some cross-tab notification
mechanism.

Shane

[Jared Hirsch]

Wow, I'm bummed that I never saw any of Francois' or Callahad's replies
until now. But excited to see them, even if a month late :-)