store the persist_in_session setting in the session

[catagits/Catalyst-Authentication-Store-LDAP.git] / README

diff --git a/README b/README
index d7700cb..bd4f03e 100644 (file)
--- a/README
+++ b/README
@@ -38,8 +38,12 @@ SYNOPSIS
                    user_field          => "uid",
                    user_filter         => "(&(objectClass=posixAccount)(uid=%s))",
                    user_scope          => "one", # or "sub" for Active Directory
-                   user_search_options => { deref => "always" },
+                   user_search_options => {
+                     deref => 'always',
+                     attrs => [qw( distinguishedname name mail )],
+                   },
                    user_results_filter => sub { return shift->pop_entry },
+                   persist_in_session  => 'all',
                  },
                },
              },
@@ -50,8 +54,8 @@ SYNOPSIS
             my ( $self, $c ) = @_;
 
             $c->authenticate({
-                              id          => $c->req->param("login"), 
-                              password    => $c->req->param("password") 
+                              id          => $c->req->param("login"),
+                              password    => $c->req->param("password")
                              });
             $c->res->body("Welcome " . $c->user->username . "!");
         }
@@ -131,7 +135,7 @@ CONFIGURATION OPTIONS
 
         user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
         user_field:  samaccountname
-        user_filter: (sAMAccountName=%s) 
+        user_filter: (sAMAccountName=%s)
         user_scope: sub
 
     He also notes: "I found the case in the value of user_field to be
@@ -221,7 +225,7 @@ CONFIGURATION OPTIONS
                               }
                               return undef; # i.e., no match
                             }
- 
+
   use_roles
     Whether or not to enable role lookups. It defaults to true; set it to 0
     if you want to always avoid role lookups.
@@ -270,6 +274,21 @@ CONFIGURATION OPTIONS
     *bindpw* fields. If this is set to false, then the role search will
     instead be performed when bound as the user you authenticated as.
 
+  persist_in_session
+    Can take one of the following values, defaults to *username*:
+
+   username
+    Only store the username in the session and lookup the user and its roles
+    on every request. That was how the module worked until version 1.015 and
+    is also the default for backwards compatibility.
+
+   all
+    Store the user object and its roles in the session and never look it up
+    in the store after login.
+
+    NOTE: It's recommended to limit the user attributes fetched from LDAP
+    using user_search_options / attrs to not exhaust the session store..
+
   entry_class
     The name of the class of LDAP entries returned. This class should exist
     and is expected to be a subclass of Net::LDAP::Entry