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.