NAME

Plack::Middleware::Auth::Bitcard - Bitcard authentication for Plack, which I suppose is what you might have guessed from the name

SYNOPSIS

   use strict;
   use warnings;
   
   use Authen::Bitcard;
   use Plack::Builder;
   
   my $app = sub {
      my $env = shift;
      my $username = $env->{BITCARD}{username};
      ...;
   };
   
   my $bc = "Authen::Bitcard"->new;
   $bc->token("12345678");
   $bc->api_secret("1234567890ABCDEF");
   
   builder {
      enable "Auth::Bitcard", bitcard => $bc;
      $app;
   };

DESCRIPTION

This module provides Plack middleware for Bitcard authentication.

What is Bitcard? It's a trusted third-party authentication system. Like OpenID but centralised, somewhat outdated, and pretty obscure.

So why use it? You probably shouldn't. An exception would be if you need login functionality for a website that is aimed at Perl developers. This is because Bitcard is already used as login for rt.cpan.org and cpanratings.perl.org, so many Perl developers already have a login set up.

Simple usage

The example in the SYNOPSIS section shows how easy it is to add Bitcard authentication to an existing PSGI app.

You'll need a Bitcard token and API secret for your website - to get these, sign into http://www.bitcard.org/, go to your account settings, click on "My Sites", then add a new site. You will need to tell it your site's name, and a URL. This URL should be the "base" URL for your PSGI app with /_bitcard_boomerang added to the end. For example, if you are serving http://bugs.example.com/ using Plack, then the URL you want is http://bugs.example.com/_bitcard_boomerang. Once you've entered that information, the bitcard.org site will issue you with a token and API secret.

With this simple setup, all requests to your site will be protected by Bitcard authentication. When somebody first hits your site, they'll be instantly redirected to bitcard.org to login.

Once they've logged in, their Bitcard details, including their username will be in $env->{BITCARD}.

No login necessary

You may want to specify that certain parts of your site do not require a login; or perhaps visitors from certain IP addresses do not need to login; or whatever.

This module accepts a coderef which can check these sorts of criteria:

   builder {
      enable "Auth::Bitcard",
         bitcard => $bc,
         skip_if => sub { my $env = shift; ... };
      $app;
   };

If the coderef returns true, then Bitcard authentication will be skipped for the given request.

Showing different views of the site

Perhaps you don't always need people to login to your site. Maybe you are happy for them to browse a public version of your site, and they only need to login if they want to access the super-awesome features.

In this case, you can provide an on_unauth action:

   builder {
      enable "Auth::Bitcard",
         bitcard   => $bc,
         on_unauth => sub { my $env = shift; ... };
      $app;
   };

on_unauth is a PSGI app in its own right, and is expected to return a PSGI-style arrayref.

Displaying login/logout links

You can obtain login/logout URLs using the following:

   my $login_url    = $env->{BITCARD_URL}->(login_url => $env);
   my $logout_url   = $env->{BITCARD_URL}->(logout_url => $env);

There are also URLs for the user's account settings page, and to register for a new bitcard account.

   my $account_url  = $env->{BITCARD_URL}->(account_url => $env);
   my $register_url = $env->{BITCARD_URL}->(register_url => $env);

When logged in people return to your site, they will arrive back at your site's base URL. If you wish to send them elsewhere, set a cookie containing the full URL you wish them to return to:

   my $res = "Plack::Response"->new;
   $res->cookies->{bitcard_return_to} = "http://example.com/goodbye";
   $res->redirect($env->{BITCARD_URL}->(logout_url => $env));
   return $res->finalize;

BUGS

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=Plack-Middleware-Auth-Bitcard.

SEE ALSO

Authen::Bitcard.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2013 by Toby Inkster.

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

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

cpanm Plack::Middleware::Auth::Bitcard

perl -MCPAN -e shell
install Plack::Middleware::Auth::Bitcard