NAME

Mojolicious::Plugin::MozPersona - Minimalistic integration of Mozillas "Persona" authentication system in Mojolicious apps

VERSION

version 0.05

SYNOPSIS

# Mojolicious::Lite
plugin 'MozPersona' => {
    audience => 'http://127.0.0.1:3000/',
    siteName => 'My spectacular new site!',
    autoHook => { css => 1 },
};

# Mojolicious
# $self->plugin( moz_persona => { 
#     audience => 'https://example.org:8443/',
#     siteName => 'My shiny new site!'
# });

get '/' => sub {
    my $self = shift;
    $self->render('index');
};

app->start;

__DATA__

@@ index.html.ep
<!DOCTYPE html>
<html>
  <head><title>Mozilla Persona Test</title></head>
  <body>
% if ( defined(session '_persona') && (session '_persona')->{'status'} eq 'okay' ) {
%     my $email = (session '_persona')->{'email'};
    <a href="#" class="persona-button" id="personaSignout"><span><%= $email %> abmelden</span></a>
% } else {
    <a href="#" class="persona-button" id="personaSignin"><span>Anmelden mit Ihrer Email</span></a>
% }
    <p>Some dummy content.</p>
  </body>
</html>:confirm b6

DESCRIPTION

Mojolicious::Plugin::MozPersona is a Mojolicious plugin. It provides a minimalistic integration of Mozillas "Persona" authentication system in Mojolicious apps.

This modules adds a few routes (at signinPath, signoutPath and localJsPath, see below) to your app which refer to the code that is responsible for handling the local, application-specific server side part of the Persona authentication model.

It also by default registers a after_dispatch hook that automatically inserts some script and link elements to pull in the JavaScript code Persona needs and some CSS that provides common styling rules for the signin/signout elements (cf. autoHook below).

Please note that you´re advised to read the Persona documentation before using this plugin.

NAME

Mojolicious::Plugin::MozPersona - Minimalistic integration of Mozillas "Persona" authentication system in Mojolicious apps.

BEWARE: THIS IS AN EARLY 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!

CONFIGURATION

You may pass a hash ref on plugin registration. The following keys are currently recognized:

audience

The protocol, domain name, and port of your site. E.g. https://example.org:8443. This param is mandatory.

siteName

The human readable name of your site (the running Mojolicious app). Will be shown to the user when he or she signs in with the identity provider. This param is mandatory.

service

The URL of the API of the identity provider you selected. Default is https://verifier.login.persona.org/verify.

namespace

The name of a Mojolicious::Controller module. This controller provides the server-side functionality necessary to verify a user login. Default is Mojolicious::Plugin::MozPersona::Controller.

signinId

The id of the HTML element which provides the "onClick" handler to start the signin process. Default is personaSignin.

signinPath

The URL path on your server that get´s called with the assertion of the identity provider after the user signed in with the identity provider. The handler code for this URL is responsible to verify the users identity assertion and update the mojolicious session accordingly. Default is /_persona/signin.

signoutId

The id of the HTML element which provides the "onClick" handler to start the signout process. Default is personaSignout.

signoutPath

The URL path on your server that get´s called when user logs out. The handler code for this URL is responsible for removing the authentication information from the Mojolicious session. Default is /_persona/signout'.

autoHook

Hashref that tells the plugin wether to automatically add html elements to include necessary JavaScript and CSS components. Known values are:

css

Include the style rules for CSS "Buttons" as provided by Mozilla by inserting a <link rel="stylesheet" href="/_persona/persona-buttons.css"> element. Note that the CSS file is part of this distribution and not loaded from a Mozilla server. Cf. https://developer.mozilla.org/en-US/docs/persona/branding. This option is deactivated (set to 0) by default.

jquery

Include the jQuery JavaScript library. The exact effect of activating this option depends on the value provided:

bundled

If the option is set to bundled, the jQuery file that is part of the Mojolicious distribution is used by inserting a <script src="/mojo/jquery/jquery.js"> element.

<B>Beware:<B> Since the jQuery library bundled with Mojolicious is intended for internal use only, this is not a recommended practice: consider using your own independent copy or use the CDN.

cdn

Include the latest version of the jQuery JavaScript library by utilizing the official content delivery network; inserts <script src="http://code.jquery.com/jquery-latest.min.js">.

As of now, the latest version from the 1.x line of development is available at that URL. To minimize the risk of future incompatibilities please consider using your own independent copy (and set this option to false).

Prior to release 0.05 this option only took a boolean value and if that was true the bundled jQuery file was used. That is the reason why in release 0.05 any true value besides bundled and cdn still has the same effect as if bundled was passed in.

A future release will change this option to be off by default and will consider any value besides the two shown above as false.

persona

Include the Persona JavaScript code by inserting the appropriate <script src="$config{'personaJsPath'}"> element. See config param personaJs below.

local

Include the local JavaScript code that triggers the start of the login and logout processes and connects the persona authentication to the session of the local application by inserting the appropriate <script src="$config{'localJsPath'}">

uid

Make the email address of the persona user available to the local JavaScript code by setting a JavaScript variable.

All hooks except for the css hook are active by default.

Please note that these options are interconnected. E.g. the default local JavaScript code needs jQuery so if you keep local active and disable jquery you must include jQuery yourself! Similarly the default local JS code expects a JS variable with a specific name set to either "null" or the email address of the currenly logged-in user.

localJsPath

The URL to use for retrieving the JavaScript code that registers the onClick handler and callback functions which are necessary for performing the signin and signout process. Default is /_persona/localjs.

localJsTpl

The name of the template which provides the locally defined JavaScript "glue" between your app and the Persona IdP. Default is _persona/local_js.txt.ep. The given value is automatically split to determine which format and handler to use for rendering. Unless specified via the given value format => text and handler => ep are used as defaults.

personaJsPath

The URL or path to the Persona JavaScript code. Default is https://login.persona.org/include.js.

All configuration params the have a default value listed above are optional.

Besides siteName the "navigator.id.request" function additionally supports the following params: siteLogo, termsOfService, privacyPolicy, oncancel, and returnTo. You may provide string values for all of these when registering the plugin. The default local JavaScript code, however, ignores oncancel and returnTo and only passes the other three params to the Persona IdP.

METHODS

Mojolicious::Plugin::MozPersona inherits all methods from Mojolicious::Plugin and implements the following new ones:

`register`

$plugin->register(Mojolicious->new);

You usually don´t call that method yourself directly. Instead, Mojolicious calls this function when you register the plugin, e.g. via plugin 'MozPersona' .... See DESCRIPTION above for an explanation of what happens here.

HELPERS

None.

EXTRA FILES

The following files are part of this distribution and are available via these URL paths:

/_persona/email_sign_in_black.png
/_persona/email_sign_in_blue.png
/_persona/email_sign_in_red.png
/_persona/persona-buttons.css
/_persona/persona_sign_in_black.png
/_persona/persona_sign_in_blue.png
/_persona/persona_sign_in_red.png
/_persona/plain_sign_in_black.png
/_persona/plain_sign_in_blue.png
/_persona/plain_sign_in_red.png

The following template is part of this distribution:

_persona/local_js.txt.ep

AUTHORS

Heiko Jansen <hjansen@cpan.org>
Moritz Lenz <moritz@cpan.org>

COPYRIGHT AND LICENSE

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

To install Mojolicious::Plugin::MozPersona, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mojolicious::Plugin::MozPersona

CPAN shell

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

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

NAME

CONFIGURATION

METHODS

register

HELPERS

EXTRA FILES

SEE ALSO

AUTHORS

COPYRIGHT AND LICENSE

Module Install Instructions

`register`