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-Bitcar
    d>.

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.