--- /dev/null
+
+User Collision in FreeRadius
+----------------------------
+
+0. INTRODUCTION
+
+ A. What is it?
+
+ User collision is the ability to uniquely authenticate duplicate usernames in radius.
+ In addition, it provides resources to correctly identify each duplicate user in the
+ accounting logs.
+
+ B. Who needs it and why?
+
+ Many ISPs are acquiring other ISPs in local or remote areas. This causes problems with
+ centralizing services such as radius because of the overlap in usernames between ISPs.
+
+ For example:
+
+ o ISP A (with 10,000 users) acquires ISP B (with 1,000 users).
+ o ISP A determines that 375 of ISP B's 1,000 usernames conflict with usernames
+ already in use at ISP A (eg 'foo' is valid username on both ISPs)
+ o ISP A, therefore, cannot merge its user files with ISP B and centralize radius
+
+ Now, about now, many of you are thinking, "what about realms?" Well, realms are great,
+ but, in general, it will require the end user to add "@domain.com", which is a pain.
+ It means ISP A has to call 375 people and tell them to add that to their login name.
+
+ And now some of you are thinking, "why couldn't you add the realm in the server
+ based on some other attribute (such as NAS-IP or Calling-Station)?" The answer is,
+ you could, but both of those solutions are a pill to maintain. For example, what if
+ you want to merge the huntgroups (and NASs) of ISP A and ISP B? Then the NAS-IP
+ method falls apart. And god forbid the user call from a different number or change
+ their line for Calling-Station.
+
+ So how to solve it? Enter user collision code in radius...
+
+ C. How does it work?
+
+ Currently, it only works when authenticating users via the following methods in
+ FreeRadius:
+
+ o 'users' file ( Auth-Types 'Local' and 'Crypt-Local' _ONLY_ )
+ o cached password (and shadow) file users
+
+ That's it so far. Perhaps other module authors will include it in their code
+ later, but that is for them to decide.
+
+ Btw, the reason user collision cannot be implemented (efficiently) on a non-cached
+ /etc/passwd file is because getpwnam() will always return the first user it finds
+ with a matching username. Thus, if you're going to use the /etc/passwd file, you
+ MUST set 'cache = yes' in your radiusd.conf. Or, you could always just put
+ duplicate usernames in the 'users' files, but you should probably be caching anyway
+ if you want a speedy server :)
+
+ 1. Authentication
+
+ It currently works by using the password of the user to uniquely identify and auth-
+ enticate them.
+
+ Example:
+
+ ISP A user 'foo' has password 'bar'
+ ISP B user 'foo' has password 'bleah'
+
+ If the user logs in with 'bar' as their password, their login will be accepted and
+ they will get the reply attributes associated with what you've entered for the
+ user 'foo' password 'bar' entry.
+
+ If the user logs in with 'bleah' as the password, again, they'll be authenticated,
+ but they will get the reply attributes associated with user 'foo' password 'bleah'.
+
+ So, what happens if two users have the same password? IT BREAKS. Well, ok, it
+ doesn't "break", but every user with the associated pass will get the same reply
+ attributes, causing grief for you. THE CODE DOES NOT CHECK FOR THIS, THAT IS
+ YOUR JOB!
+
+ NOTE: Again, user collision authentication *depends* on the passwords being distinct!
+
+ So the security minded among us are now agast. I'm not much for this method myself,
+ but trust me, the corporate folks are gonna love it. And it's not inherently insecure
+ as long as the passwords remain different.
+
+ 2. Accounting
+
+ Ok, so now, how can we tell in the accounting logs which user 'foo' logged in? Well,
+ again, you have a little work to do. The code identifies the user via a unique
+ value assigned to the 'Class' reply attribute in the users file.
+
+ For example:
+
+ foo Auth-Type := Local, Password == "bar"
+ Class = 0x0001
+
+ foo Auth-Type := Local, Password == "bleah"
+ Class = 0x0002
+
+ Now, you'd add other attributes as well, but let's just start with 'Class' by itself
+ as a reply. When a user 'foo' logs in with password 'bar', the 'Class=0x0001' reply
+ item gets sent back to the NAS they dialed into. The NAS then adds 'Class=0x0001'
+ to the Accounting 'Start' packet it sends for that user, thus uniquely identifying
+ *this* 'foo' in the your accounting logs.
+
+ If the user 'foo' logs in with password 'bleah', you will get 'Class=0x0002' in your
+ accounting logs.
+
+ Now, again, you should note that it is *your job* to make sure the 'Class' values
+ are different for each user. If you don't, I can assure you the phones will ring
+ off the hook when bitchy users get their bills.
+
+ Obviously, this method works only for users in your 'users' files.
+
+ If you are using a cached passwd file, then the "Full name" field in the passwd
+ file you cached will be passed back to the NAS as the value of 'Class'.
+
+ Example:
+
+ /etc/passwd -> test:x:500:500:0x1001:/dev/null:/dev/null
+
+ In this case, "0x1001" will be passed as the value for the 'Class' attribute
+ when the Auth-Accept packet gets sent back to the NAS, and then you should
+ see 'Class=0x1001' for that user in your accounting logs.
+
+ Once again, it is your job to ensure that these Class values are unique for
+ each user.
+
+ D. *Does* it work?
+
+ As of 10-01-2000, it is *extremely alpha*. If you find bugs, by all means let
+ met know at jeff@apex.net, but make sure you include relavent sections of your
+ 'users' file and debug output from the server (radiusd -X).
+
+
+1. USAGE
+
+ Run configure with the --with-usercollide option. Then 'make' and 'make install' again.
+
+
+2. CAVEATS
+
+ It *only* works with cached passwd files and users (Local and Crypt-Local _ONLY_) in
+ your 'users' file. Any other authentication method will not cause user collisions not
+ to work.
+
+
+3. ACKNOWLEDGEMENT
+
+ Jeff Carneal - Author
+ Alan DeKok - for telling me about the 'Class' attribute :)
+
projects / freeradius.git / commitdiff