NAME

Mojolicious::Plugin::MozPersona::Controller - Default implementation for server side functions for "Persona" authentication.

VERSION

version 0.04

DESCRIPTION

When registering the "MozPersona" plugin you may specify a configuration param namespace which must contain the name of a module that inherits from Mojolicious::Controller.

This module must provide (directly or via inheritance) implementations of three methods: signin, signout and js.

NAME

Mojolicious::Plugin::MozPersona::Controller - Default implementation for server side functions for "Persona" authentication.

BEWARE: THIS IS AN ALPHA RELEASE! - It is quite possible that there will be incompatible changes before the API and the functionality of this plugin are declared stable. Use at your own risk. On the other hand that also means that now is the right time to tell me what should be changed to make this module more usable and useful!

METHODS

signin

This method gets called via an XMLHttpRequest after a user signed in with the identity provider - i.e. after the IdP created and stored an association between the user and the given audience (the Mojolicious app).

It receives a controller object which has access to the authentication assertion of the IdP as request param assertion. It also has access to the configuration values "audience" (as _persona_audience) and "service" (as _persona_service) via the stash.

It is responsible for sending a request containing the assertion and the audience to the service, thereby verifying the assertion token and retrieves a JSON response which tells if the assertion was verified, until when it is valid and what email address was associated with the user.

It should update the Mojolicious session accordingly. The default implementation in this module does so by saving the IdP response in the _persona key in the session).

Please note that the session is updated with the IdP response no matter if the authentication and verification actually succeeded! Simply checking for the existence of session-{_persona}> is NOT sufficient - you need to check the value of the status element in the response of the Persona IdP. Setting the "_persona" data anyway allows the app to provide a failure message for subsequent requests by the user.

This method should return a status info to the browser: The default implementation in this module returns "success":false if there was an error while processing the request and "success":true otherwise.

"success":true, however, does NOT indicate that the user was successfully authenticated! Again, you have to refer to the message returned by the IdP which is also included in the response and contains either "status":"okay" or "status":"failure".

E.g. if the user successfully signed in and the verification succeeded the JSON message returned is:

  {
    "success": true,
    "result": {
      "status"  : "okay",
      "email"   : "somebody@example.org",
      "audience": "http:\/\/127.0.0.1:3000\/",
      "issuer"  : "login.persona.org",
      "expires" : 1358864866835
    }
  }

Otherwise if the message exchange was successful but IdP could not verify the authentication of the user the JSON message looks like this:

  {
    "success": true,
    "result": {
      "status": "failure",
      "reason": "...server hiccup..."
    }
  }

And if the whole process failed the JSON message simply is

  {
    "success": false
  }

For further info please refer to https://developer.mozilla.org/en-US/docs/Persona, https://developer.mozilla.org/en-US/docs/Persona/Quick_Setup and https://developer.mozilla.org/en-US/docs/Persona/Remote_Verification_API.

signout

This method gets called via an XMLHttpRequest after a user successfully signed out with the identity provider.

It receives a controller object which has access to the Mojolicious session.

It should remove the authentication information from the sessions. The default implementation in this module does so by simply deleting the key "_persona" from the session hash.

It should return a status info to the browser. Since all that this default implementation of the method does is delete the Persona info from the session it always returns {"signout":true}.

js

This method gets called from the browser to provide a JavaScript document that registers click handlers for the login and logout button. The JavaScript code also registers the appropriate callback functions with the watch method of the browsers navigator.id API. See also https://developer.mozilla.org/en-US/docs/DOM/navigator.id.

The method retrieves the complete config of the Mojolicious::Plugin::MozPersona module as a hash in the stash slot _persona_conf.

Using this info it renders the template specified as localJsTpl in the configuration.

SEE ALSO

Mojolicious::Plugin::MozPersona, https://developer.mozilla.org/en-US/docs/Persona, Mojolicious.

AUTHORS

• Heiko Jansen <hjansen@cpan.org>

• Moritz Lenz <moritz@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Heiko Jansen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Mojolicious::Plugin::MozPersona

perl -MCPAN -e shell
install Mojolicious::Plugin::MozPersona