If I am to follow What should a developer know before building a public web site? on authentication, then what options do I have ?
I have never used PEAR, and I'm not about to start. I have read about phpGALC but have yet to try it.
After the authentication do rights/access level kick in. I'm not a big fan of using a single tinyint value which decides what a user can and cannot do, besides its not very flexible. I have recently written a section system where I specify what kind of access each user type have access to, but is there something better ?
If you want a language, then PHP5.
Authentication is fairly straightforward. Authorization, through an ACL or whatever, can be complex.
Authentication is usually just matching a username and password with stored credentials. Just use SSL and hash passwords using a salt.
Authorization can be a beast and the solution depends on your requirements. You might try PhpGALC and the Zend Framework ACL component. Both options have roles, resources, and optional privileges although they are all named differently. The Zend ACL is simpler and more generic (rules can be defined simply in your code and it doesn't require a database). If your roles, resources, and privileges are not static, then with the Zend ACL you'll have to write code to populate the ACL from your data store. The big advantage of phpGALC is that it has a web GUI. I found the GUI clumsy, but unless you really understand your ACL, it can be dangerous to make changes directly in the database considering ACL complexities like role and resource inheritance. Keep in mind that the Zend ACL can be used on its own without any other Zend Framework dependencies besides Zend Exception.
ACL and Auth are the things I'm working on at this very moment. I'm using CakePHP at the moment, and it provides an extensive (albeit not simple) module for ACL, and a simple way to do authentication. I'm interested in answers too.
What I've gathered:
Learn to validate input, especially the difference between blacklists and whitelists
Consider carefully your email validation pattern
Consider what languages will you have to support (pesky little accents, tildes and the like get in the way in names, e.g. Añagaza or Alérta).
Roll-your-own or prebuilt?
ACL: keep it simple or it could swallow you whole.
Careful about CSRF and XSRF!
I'm not a big fan of using a single tinyint value which desides what a
user can and cannot do, besides its
not very flexible.
That depends... Are you referring to using the value as an integer or as a bitfield?
If you're using it simply as a number (level 5 user has all the abilities of level 1-4 users, plus a little more), then, yeah, that's not very flexible.
If you're using it as a bitfield, it gives you 8 (sets of) capabilities which can be turned on or off in any combination for any user. I'd call that flexible. And, if 8 capabilities isn't enough for you, it's trivial to change the tinyint (8 bits) to a smallint (16 bits/capabilities), int (32 bits), or bigint (64 bits), which should be more than sufficient for just about any application most of us are likely to write.
Most frameworks have an authentication module built-in. So you may want to checkout Zend, CakePHP, Code Ignighter, etc.
Also one thing that tends to get confusing is the difference between escaping and encoding data. Things are a lot more flexible when data is encoded then escaped.
User Authentication makes sure that if a user tries to access a page which application denies free access, it redirects the user to logging page and after a successful login brings back to the requested page. One such implementation of cake's default Auth is explained in following wrt pitfalls, approach and ways.
http://enbake.com/cakephp-user-authentication-auth-component
The framework doesnt make you restricted. But rather grants you speed of dev with existing modules and more organized code. Can show you comparison b/w frameworks if interested.
Related
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 10 years ago.
Improve this question
I am interested in performing advanced access control for users to access resources within software systems. I work in healthcare IT and a younger me has frequently underestimated the complexity of role-based access control in healthcare. But this question should apply to anyone with complex ACL requirements.
For quite some time php gacl has been my go-to library for the purposes of handling the very complex ACL control issues inside Health IT systems. But I am now working more with javascript in general and node specifically. I have searched npm for libraries to do Access Control in a generalizable way.
I would like to have support for defining actions rather than merely users and resources (3-tier instead of 2) and I would like to have user, action and resource groups, and by implication I would like to have ACL inheritance.
The classic examples from the Star Wars themed manual to that library are rules like:
All members of the crew have (visit, configure, and use) access to
the guns, engines, cockpit and lounge, expect for chewie.
All droids have (visit and use) access to the cockpit, but only R2D2 has
configure access to the engines.
Han has all types of access to all
types of resources.
The basic concepts here include the notion that you can make rules that apply to either groups of users(i.e. crew, passengers or droids) or individuals (Han, and Chewie), that you can have different types of access (visit, configure, use) or groups of access (maintence access = configure + repair + use) to different resources (engine and cockpit) which could also be grouped, (battle-stations = cockpit + guns).
This allows for the configuration of extraordinarily complex access control rules, with relatively simple group-based administration.
So far, I have seen nothing like this outside of php-gacl. I have taken a look at the wonderful javascript based ACL projects and all of them advertise simplicity and ease of use rather than comprehensiveness. This is also true of other typical php ACL libraries (i.e. Zend ACL)
Is someone working on an "advanced ACL" project for node? Is there perhaps a much better approach that I should be looking for somewhere?
php-gacl comes with three parts, one is a php-based admin GUI (that is admittedly over-complex), and an API for CRUD on the rules (that could be easily converted to a REST interface I think) and a very small file that provides ACL checking functionality.
Technically, only the last type would need to be fully ported over to node in order for that software model to work?
On a deeper level, I want to understand what approaches have been used successfully to handle this problem. How is this problem typically solved? Bonus points for those who effectively discuss this problem in terms of node/javascript and perhaps even a particular database approach (relational vs non-relational). I understand that there are lots of theoretical underpinnings for doing this right/wrong (i.e. lots of opinion over RBAC, vs ACL). What I want is something theoretically solid, or almost-solid that still "just works" from a library standpoint. I am focused on Javascript, but it would be nice to understand how other languages are practically solving this problem.
If you can avoid using any kind of ACL, you are usually better off. They are complex to administer. You would be better off modeling three levels of security checks:
URL/IP Address/or other accesspoint security check
Method upon resources check. Whatever entities you want to modify or manipulate you put permission checks on that. I.E. Business rules type of access.
Entity Resource check. If a user/API/OAuth token has access AT ALL to an entity
This can be accomplished using an RBAC. The roles for your organization/site each are assigned a set of access/modification/manipulation permissions. Users are assigned a role(s), but the three levels of checks check the PERMISSIONS, not the role.
I would look at Spring Security and RBAC as a google search, and model on that. Here are a few links that I have found useful:
http://www.xaprb.com/blog/2006/08/16/how-to-build-role-based-access-control-in-sql/
http://www.xaprb.com/blog/2006/08/18/role-based-access-control-in-sql-part-2/
(because all the 'primitive' examples and crazily named checks in Spring Security, you will be advised to read articles that offer the use of alternative names and uses for the Spring permission 'hasRole()' checks. The following article discusses this in the design of an RBAC)
http://springinpractice.com/2010/10/27/quick-tip-spring-security-role-based-authorization-and-permissions/
(A good presentation on flexible uses of Spring Security, including RBAC)
http://www.infoq.com/presentations/Spring-Security-3
(The following gives a GOOD description of the RBAC problem and solutions, and is designed for PHP)
http://www.tonymarston.net/php-mysql/role-based-access-control.html
A PHP framework with a RBAC implementation:
http://trac.symfony-project.org/wiki/UserRbac
And finally, the class diagram for Spring Security. You will notice that it allows putting security information in a PARALLEL table to the entities being protected. This is by design, so that Spring Security can be added later, or taken out, or replaced easily. But it also means more tables.
http://code.google.com/p/uclm-esi-alarcos/source/browse/trunk/documentation/memoria-pfc/Figuras/Cap5/spring-security-class-diagram.png?r=295
I am just about to undertake building a relatively large PHP system, I just need some ideas on how to implement a certain feature.
I will allow users to register. Once registered, the user will have a security level which will be assigned to their account.
So if I had security levels 1, 2 and 3, what would be the best way to show certain things to people with certain security levels ?
Thank you in advance.
Before you reinvent the wheel, be sure to look whether Zend_ACL is for you. I haven't used it myself but from what it promises in the docs, it can do what you need and much more.
Pekka's comments about looking at the Zend API's are good. Many of the Frameworks for PHP are currently (sadly) badly implemented junk (with hideously amateur code underneath), but the Zend API's are almost uniquely valuable.
If you do roll your own, which there is nothing wrong with doing if you can't find something that fits what you want (and can't be extended easily), then I'd take an OO approach and expose user properties via a class.
e.g.
$user = new User($session->userId);
if (!$user->isAdministrator && !$user->canViewReports)
someErrorHandler("You do not have permission to access this content.");
I'd avoid having fixed levels, but instead follow a roles based approach.
i.e. I'd avoid having levels like:
Staff
Manager
Administrator
And instead I'd go for properties (just as illustrative examples):
read_access
write_access
can_view_logs
can_view_reports
is_administrator
This allows you to be easily more explicit later, when you (inevitably) discover you want an additional permissions group you want have to go back and change existing code.
That doesn't mean putting users in groups is a bad idea (it's not and you could implement this using a groups system, e.g. where by a user could be in both "Reporting" and "Logs"), but assumptions about security levels being hierarchical are typically the wrong approach (e.g. Level 1=Staff, Level 2=Managers, Level 3=Admin) - this is because you almost always end up needing a system that's more flexible than a simple hierarchical system allows.
In practice if you do end up taking this approach, you may want to have a Permissions or Group class, to avoid having an overly large User class (which might end up full of stuff for getting user properties, setting new passwords, etc).
e.g.
$group = new Group($session->userId);
if (!$group->Administrators && !$group->Reporting)
someErrorHandler("You do not have permission to access this content.");
I'm trying to design the authentication of my web application in an object oriented manner. Is this a concern of my domain in which case I would have something like this:
$user->authenticate($authenticator);
$user->login($authenticator);
Where $authenticator is an interface to my authentication service.
Or would this be a cross cutting concern and I would do it the other way around.
$authenticator->authenticate($user);
$session->setUser($user);
The first way seems more "OO" to me, since I don't have to ask anything from my user object...it passes the information the authenticator needs. But it feels like I'm "polluting" my domain in a certain respect...logging in is not a business requirement of my application...it is a side effect from the fact that I need a method of authentication to protect my application.
Unless your Domain includes authentication as a central concept, I would say that it's a cross-cutting concern and not part of the Domain Model.
Most developers write business applications that model something entirely different than software security. Authentication is a very important part of many applications, but really has nothing to do with the Domain itself.
That doesn't mean that you can't deal with authentication in an object-oriented way.
In Domain-Driven Design terminology, the business concept you model is part of your Core Domain while you could choose to implement authentication and other security concepts in a Generic Subdomain.
I can't help with the php-specific things, but in .NET, security is pretty much something that's just handled by the platform if you do it right. Here it's a truly cross-cutting concern by implementation, so that's how it's done elsewhere (FWIW).
IMHO passing an Authenticator is bad OO. Why should a user understand how to authenticate itself? It's a user it doesn't even need to know what an authenticator is. Also, passing an authenticator seems strange to me unless you plan on having different ways of authenticating a user thus having a need to pass different types of authenticators to your user. You make it seem like authentication isn't a major part of your application so I doubt you will have more than one way of authenticating a user.
I think your second approach makes more sense although still seems like overkill to me. My favorite framework is symfony and they have a great plugin called sfGuard that handles authentication. Take a look at the source code of the plugin and see if it gives you any inspiration.
Coupling
$user->authenticate($authenticator);
$user->login($authenticator);
Inversion of control
$authenticator->authenticate($user);
$session->setUser($user);
Coupling is bad, inversion is good. Go with the later.
As a web developer I am using PHP and I know that I have to worry about security but when you use a framework, there is a lot-of code and design that you relay on but that you didn't code or design and for instance I am using CakePHP.
so in this case with frameworks how much should i worry about security ?
You should always continue respecting the basic principles of security :
don't trust the user
never trust the user
Which kinda means :
filter / validate everything that comes to your application
escape any output.
Using a framework doesn't change much about that, except that :
Output to the database often es some layer of the framework, which should deal with escaping
Frameworks often provide filtering / validation solutions ; use them ;-)
Frameworks often have some guidelines ; read them.
As a sidenote : you said this :
there is a lot-of code and design that
you relay on but that you didn't code
or design
Considering you are using a well-known framework that lots of people use, this code has probably been more tested/reviewed than any code you could write ;-)
That's an advantage of open-source, actually : you are not the only one responsible for the code, and lots of eyes have seen it -- which means lots of hands have enhanced it.
There are a lot of things to consider when dealing with security in an application. As Pascal said, it is a good idea to use a popular framework that has had a number of people looking at it.
I see a few areas of concern in regards to CakePHP.
The first issue is the end user. You should expect someone to do something foolish on every page you build. Some examples of this are:
A person clicking the submit button rapidly over and over. This may skew or mess up your system in a way if you're not careful. The solution for this is not based on the framework, but rather your coding methodology and testing.
SQL Injection and other bad things. Any field on a page can be potentially abused, therefore every form element must be sanitized. CakePHP has simple methods to take care of these security issues. http://book.cakephp.org/view/153/Data-Sanitization
Clean URL's are very important. You should never design a system that allows a user to access integer primary keys directly. For instance, if you have a site that has /show_user/2098 then someone can simply type in show_user/2097 to see someone else's account. CakePHP allows you to incorporate slugs or UUID's quite easily, to prevent this from happening.
Second, you must be concerned with attacks dealing with the code and permissions itself. For example:
Never use eval() or system() in your code from data that may come from the end user. There have been applications in the past written in perl that have been hijacked because of this issue.
The folder structure and permissions is important in regards to security. Users should never have access to get into a writable directory. With CakePHP the folder structure is designed so that you can point apache directly to app/webroot. This means the tmp directory is outside of the apache path, making the system a bit more secure.
Third, you should be concerned with the protection of your administration pages and who has permissions to access what.
CakePHP has an Auth and an Acl component that allows you to choose what users get access to which pages. This makes use of custom Cake Sessions which can be stored in a database, by using PHP or written to the file system.
I would suggest reading up on some of the important components and being sure you set them up properly, to ensue you have built an application without security flaws. Take a look at some of these elements as you research further: http://book.cakephp.org/view/170/Core-Components
I suggest you check out ESAPI: http://www.owasp.org/index.php/Category:OWASP_Enterprise_Security_API#tab=PHP
It is not a framework per se, but does contain a lot of tools for the problems Pascal mentions.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a book, tool, software library, tutorial or other off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 8 years ago.
Improve this question
I see there are a few. Which ones are maintained and easy to use? What are their pros and cons?
Update (May 14, 2010):
It turns out, the russian developer Ilya Konyukhov picked up the gauntlet after reading this and created a new auth library for CI based on DX Auth, following the recommendations and requirements below.
And the resulting Tank Auth is looking like the answer to the OP's question. I'm going to go out on a limb here and call Tank Auth the best authentication library for CodeIgniter available today. It's a rock-solid library that has all the features you need and none of the bloat you don't:
Tank Auth
Pros
Full featured
Lean footprint (20 files) considering the feature set
Very good documentation
Simple and elegant database design (just 4 DB tables)
Most features are optional and easily configured
Language file support
reCAPTCHA supported
Hooks into CI's validation system
Activation emails
Login with email, username or both (configurable)
Unactivated accounts auto-expire
Simple yet effective error handling
Uses phpass for hashing (and also hashes autologin codes in the DB)
Does not use security questions
Separation of user and profile data is very nice
Very reasonable security model around failed login attempts (good protection against bots and DoS attacks)
(Minor) Cons
Lost password codes are not hashed in DB
Includes a native (poor) CAPTCHA, which is nice for those who don't want to depend on the (Google-owned) reCAPTCHA service, but it really isn't secure enough
Very sparse online documentation (minor issue here, since the code is nicely documented and intuitive)
Download Tank Auth here
Original answer:
I've implemented my own as well (currently about 80% done after a few weeks of work). I tried all of the others first; FreakAuth Light, DX Auth, Redux, SimpleLogin, SimpleLoginSecure, pc_user, Fresh Powered, and a few more. None of them were up to par, IMO, either they were lacking basic features, inherently INsecure, or too bloated for my taste.
Actually, I did a detailed roundup of all the authentication libraries for CodeIgniter when I was testing them out (just after New Year's). FWIW, I'll share it with you:
DX Auth
Pros
Very full featured
Medium footprint (25+ files), but manages to feel quite slim
Excellent documentation, although some is in slightly broken English
Language file support
reCAPTCHA supported
Hooks into CI's validation system
Activation emails
Unactivated accounts auto-expire
Suggests grc.com for salts (not bad for a PRNG)
Banning with stored 'reason' strings
Simple yet effective error handling
Cons
Only lets users 'reset' a lost password (rather than letting them pick a new one upon reactivation)
Homebrew pseudo-event model - good intention, but misses the mark
Two password fields in the user table, bad style
Uses two separate user tables (one for 'temp' users - ambiguous and redundant)
Uses potentially unsafe md5 hashing
Failed login attempts only stored by IP, not by username - unsafe!
Autologin key not hashed in the database - practically as unsafe as storing passwords in cleartext!
Role system is a complete mess: is_admin function with hard-coded role names, is_role a complete mess, check_uri_permissions is a mess, the whole permissions table is a bad idea (a URI can change and render pages unprotected; permissions should always be stored exactly where the sensitive logic is). Dealbreaker!
Includes a native (poor) CAPTCHA
reCAPTCHA function interface is messy
FreakAuth Light
Pros
Very full featured
Mostly quite well documented code
Separation of user and profile data is a nice touch
Hooks into CI's validation system
Activation emails
Language file support
Actively developed
Cons
Feels a bit bloated (50+ files)
And yet it lacks automatic cookie login (!)
Doesn't support logins with both username and email
Seems to have issues with UTF-8 characters
Requires a lot of autoloading (impeding performance)
Badly micromanaged config file
Terrible View-Controller separation, with lots of program logic in views and output hard-coded into controllers. Dealbreaker!
Poor HTML code in the included views
Includes substandard CAPTCHA
Commented debug echoes everywhere
Forces a specific folder structure
Forces a specific Ajax library (can be switched, but shouldn't be there in the first place)
No max limit on login attempts - VERY unsafe! Dealbreaker!
Hijacks form validation
Uses potentially unsafe md5 hashing
pc_user
Pros
Good feature set for its tiny footprint
Lightweight, no bloat (3 files)
Elegant automatic cookie login
Comes with optional test implementation (nice touch)
Cons
Uses the old CI database syntax (less safe)
Doesn't hook into CI's validation system
Kinda unintuitive status (role) system (indexes upside down - impractical)
Uses potentially unsafe sha1 hashing
Fresh Powered
Pros
Small footprint (6 files)
Cons
Lacks a lot of essential features. Dealbreaker!
Everything is hard-coded. Dealbreaker!
Redux / Ion Auth
According to the CodeIgniter wiki, Redux has been discontinued, but the Ion Auth fork is going strong: https://github.com/benedmunds/CodeIgniter-Ion-Auth
Ion Auth is a well featured library without it being overly heavy or under advanced. In most cases its feature set will more than cater for a project's requirements.
Pros
Lightweight and simple to integrate with CodeIgniter
Supports sending emails directly from the library
Well documented online and good active dev/user community
Simple to implement into a project
Cons
More complex DB schema than some others
Documentation lacks detail in some areas
SimpleLoginSecure
Pros
Tiny footprint (4 files)
Minimalistic, absolutely no bloat
Uses phpass for hashing (excellent)
Cons
Only login, logout, create and delete
Lacks a lot of essential features. Dealbreaker!
More of a starting point than a library
Don't get me wrong: I don't mean to disrespect any of the above libraries; I am very impressed with what their developers have accomplished and how far each of them have come, and I'm not above reusing some of their code to build my own. What I'm saying is, sometimes in these projects, the focus shifts from the essential 'need-to-haves' (such as hard security practices) over to softer 'nice-to-haves', and that's what I hope to remedy.
Therefore: back to basics.
Authentication for CodeIgniter done right
Here's my MINIMAL required list of features from an authentication library. It also happens to be a subset of my own library's feature list ;)
Tiny footprint with optional test implementation
Full documentation
No autoloading required. Just-in-time loading of libraries for performance
Language file support; no hard-coded strings
reCAPTCHA supported but optional
Recommended TRUE random salt generation (e.g. using random.org or random.irb.hr)
Optional add-ons to support 3rd party login (OpenID, Facebook Connect, Google Account, etc.)
Login using either username or email
Separation of user and profile data
Emails for activation and lost passwords
Automatic cookie login feature
Configurable phpass for hashing (properly salted of course!)
Hashing of passwords
Hashing of autologin codes
Hashing of lost password codes
Hooks into CI's validation system
NO security questions!
Enforced strong password policy server-side, with optional client-side (Javascript) validator
Enforced maximum number of failed login attempts with BEST PRACTICES countermeasures against both dictionary and DoS attacks!
All database access done through prepared (bound) statements!
Note: those last few points are not super-high-security overkill that you don't need for your web application. If an authentication library doesn't meet these security standards 100%, DO NOT USE IT!
Recent high-profile examples of irresponsible coders who left them out of their software: #17 is how Sarah Palin's AOL email was hacked during the Presidential campaign; a nasty combination of #18 and #19 were the culprit recently when the Twitter accounts of Britney Spears, Barack Obama, Fox News and others were hacked; and #20 alone is how Chinese hackers managed to steal 9 million items of personal information from more than 70.000 Korean web sites in one automated hack in 2008.
These attacks are not brain surgery. If you leave your back doors wide open, you shouldn't delude yourself into a false sense of security by bolting the front. Moreover, if you're serious enough about coding to choose a best-practices framework like CodeIgniter, you owe it to yourself to at least get the most basic security measures done right.
<rant>
Basically, here's how it is: I don't care if an auth library offers a bunch of features, advanced role management, PHP4 compatibility, pretty CAPTCHA fonts, country tables, complete admin panels, bells and whistles -- if the library actually makes my site less secure by not following best practices. It's an authentication package; it needs to do ONE thing right: Authentication. If it fails to do that, it's actually doing more harm than good.
</rant>
/Jens Roland
Note that the "comprehensive listing" by Jens Roland doesn't include user roles. If you're interested in assigning different user roles (like admin/user or admin/editor/user), these libraries allow it:
Ion_Auth (rewrite of Redux)
Redux
Backend Pro
Tank_Auth (#1 above in Jens's list) doesn't have user roles. I realize it's not exactly part of authentication, but since
authentication and role management are both handled upon page load
Both involve security
The same table/model can be used for both.
Both can be set up to load in the controller constructor (or even autoload)
It makes a LOT of sense to have one library to handle both, if you need it. I'm switching to Ion_Auth from Tank_Auth because of this.
Ion_auth! Looks very promising and small footprint! I like..
http://github.com/benedmunds/CodeIgniter-Ion-Auth
I'm the developer of Redux Auth and some of the issues you mentioned have been fixed in the version 2 beta. You can download this off the offcial website with a sample application too.
Requires autoloading (impeding performance)
Uses the inherently unsafe concept of 'security questions'. Dealbreaker!
Security questions are now not used and a simpler forgotten password system has been put in place.
Return types are a bit of a hodgepodge of true, false, error and success codes
This was fixed in version 2 and returns boolean values. I hated the hodgepodge as much as you.
Doesn't hook into CI's validation system
The sample application uses the CI's validation system.
Doesn't allow a user to resend a 'lost password' code
Work in progress
I also implemented some other features such as email views, this gives you the choice of being able to use the CodeIgniter helpers in your emails.
It's still a work in progress so if have any more suggestions please keep them coming.
-Popcorn
Ps : Thanks for recommending Redux.
I've come across Flexi Auth (http://haseydesign.com/flexi-auth/). It looks very promising, and I've started using it. It has wonderfful features. Fully integrates with CI, and comes with two different library files, in which one is very heavy loaded with all the functions and the other one contains only the validations.
One of the best is that the newly registered member gets temporary access for a given amount of time on the site, until they click on the link from their email and activate.
Maybe you'd find Redux suiting your needs. It's no overkill and comes packed solely with bare features most of us would require. The dev and contributors were very strict on what code was contributed.
This is the official page
Ion_Auth beats tank_auth mainly for two reasons, user roles and documentation, these two are missing from tank_auth.
I use a customized version of DX Auth. I found it simple to use, extremely easy to modify and it has a user guide (with great examples) that is very similar to Code Igniter's.
Also take a look at BackendPro
Ultimately you will probably end up writing something custom, but there's nothing wrong with borrowing concepts from DX Auth, Freak Auth, BackendPro, etc.
My experiences with the packaged apps is they are specific to certain structures and I have had problems integrating them into my own applications without requiring hacks, then if the pre-package has an update, I have to migrate them in.
I also use Smarty and ADOdb in my CI code, so no matter what I would always end up making major code changes.
Tank Auth looks good but the documentation is just a one-page explanation of how to install, plus a quick run-down of each PHP file. At least that's all I found after lots of Googling. Maybe what people mean above when they say that Tank Auth is well-documented is that the code is well-commented. That's a good thing, but different than documentation. It would have been nice to have some documentation about how to integrate Tank Auth's features with your existing code.
I'm trying Ion_Auth and appreciate it, btw...
SimpleLoginSecure
Makes authentication simple and secure.