.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Catalyst::Authentication::Store 3pm"
.TH Catalyst::Authentication::Store 3pm "2011-09-30" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Authentication::Store \- All about authentication stores
.SH "MULTIPLE BACKENDS"
.IX Header "MULTIPLE BACKENDS"
\&\fB\s-1NOTE\s0\fR This is documentation for the old store system used in versions of
Catalyst::Plugin::Authentication prior to 0.10.  This is \s-1NOT\s0 how the 
new realm-based stores work. This is here for reference only.
.PP
See Catalyst::Plugin::Authentication::Internals instead.
.SH "OLD STORE DOCUMENTATION BELOW"
.IX Header "OLD STORE DOCUMENTATION BELOW"
A key issue to understand about authentication stores is that there are
potentially many of them. Each one is registered into the application, and has
a name.
.PP
For most applications, there is only one, and in this framework it is called
\&'default'.
.PP
When you use a plugin, like
.PP
.Vb 4
\&    use Catalyst qw/
\&        Authentication
\&        Authentication::Store::Foo
\&    /;
.Ve
.PP
the Store plugins typically only act at setup time. They rarely do more than
check out the configuration, and register e.g. Store::Foo, and set it
as the default store.
.PP
.Vb 1
\&    _\|_PACKAGE_\|_\->default_auth_store( $store );
\&
\&    # the same as
\&
\&    _\|_PACKAGE_\|_\->register_auth_stores( default => $store );
.Ve
.SH "WORKING WITH USERS"
.IX Header "WORKING WITH USERS"
All credential verifiers should accept either a user object, or a user \s-1ID.\s0
.PP
If a user \s-1ID\s0 is provided, then they will fetch the user object from the default
store, and check against it.
.PP
This should be pretty much \s-1DWIM\s0 all the time.
.PP
When you need multiple authentication backends per application then you must
fetch things yourself. For example:
.PP
.Vb 1
\&    my $user = $c\->get_auth_store("other_store")\->get_user($id);
\&
\&    $c\->login( $user, $supplied_password );
.Ve
.PP
Instead of just:
.PP
.Vb 1
\&    $c\->login( $id, $supplied_password );
.Ve
.PP
which will go to the default store.
.SH "WRITING A BACKEND"
.IX Header "WRITING A BACKEND"
Writing an authentication storage backend is a very simple matter.
.PP
The only method you really need to support is \f(CW\*(C`get_user\*(C'\fR.
.PP
This method should accept an arbitrary list of parameters (determined by you or
the credential verifyer), and return an object inheriting
Catalyst::Authentication::User.
.PP
For introspection purposes you can also define the \f(CW\*(C`user_supports\*(C'\fR method. See
below for optional features. This is not necessary, but might be in the future.
.SS "Integrating with Catalyst::Plugin::Session"
.IX Subsection "Integrating with Catalyst::Plugin::Session"
If your users support sessions, your store should also define the
\&\f(CW\*(C`from_session\*(C'\fR method. When the user object is saved in the session the
\&\f(CW\*(C`for_session\*(C'\fR method is called, and that is used as the value in the session
(typically a user id). The store is also saved in the hash. If
\&\f(CW\*(C`$user\->store\*(C'\fR returns something registered, that store's name is used. If
not, the user's class is used as if it were a store (and must also support
\&\f(CW\*(C`from_session\*(C'\fR).
.SS "Optional Features"
.IX Subsection "Optional Features"
Each user has the \f(CW\*(C`supports\*(C'\fR method. For example:
.PP
.Vb 1
\&    $user\->supports(qw/password clear/);
.Ve
.PP
should return a true value if this specific user has a clear text password.
.PP
This is on a per user (not necessarily a per store) basis. To make assumptions
about the store as a whole,
.PP
.Vb 1
\&    $store\->user_supports(qw/password clear/);
.Ve
.PP
is supposed to be the lowest common denominator.
.PP
The standardization of these values is to be goverened by the community,
typically defined by the credential verification plugins.
.SS "Stores implying certain credentials"
.IX Subsection "Stores implying certain credentials"
Sometimes a store is agnostic to the credentials (\s-1DB\s0 storage, for example), but
sometimes it isn't (like an Htpasswd file).
.PP
If you are writing a backend that wraps around a module, like
Catalyst::Authentication::Store::Htpasswd wraps around
Authen::Htpasswd, it makes sense to delegate the credential checks.
.PP
This particular example caused the following \*(L"feature\*(R" to be added:
.PP
.Vb 1
\&    $user\->supports(qw/password self_check/);
.Ve
.SS "Writing a plugin to go with the backend"
.IX Subsection "Writing a plugin to go with the backend"
Typically the backend will do the heavy lifting, by registering a store.
.PP
These plugins should look something like this:
.PP
.Vb 2
\&    sub setup {
\&        my $c = shift;
\&
\&        $c\->default_auth_store(
\&            # a store can be an object or a class
\&            Catalyst::Authentication::Store::Foo::Backend\->new(
\&                ...
\&            )
\&        );
\&
\&        $c\->NEXT::setup(@_);
\&    }
.Ve