doc/duplicate-users

   1
   2 User Collision in FreeRadius
   3 ----------------------------
   4
   5 0.  INTRODUCTION
   6
   7     A.  What is it?
   8
   9         User collision is the ability to uniquely authenticate duplicate
  10         usernames in radius. In addition, it provides resources to
  11         correctly identify each duplicate user in the accounting logs.
  12
  13     B.  Who needs it and why?
  14
  15         Many ISPs are acquiring other ISPs in local or remote areas.  This
  16         causes problems with centralizing services such as radius because
  17         of the overlap in usernames between ISPs.
  18
  19         For example:
  20
  21         o  ISP A (with 10,000 users) acquires ISP B (with 1,000 users).
  22         o  ISP A determines that 375 of ISP B's 1,000 usernames conflict
  23            with usernames already in use at ISP A (eg 'foo' is valid
  24            username on both ISPs)
  25         o  ISP A, therefore, cannot merge its user files with ISP B and
  26            centralize radius
  27
  28         Now, about now, many of you are thinking, "what about realms?"
  29         Well, realms are great, but, in general, it will require the end
  30         user to add "@domain.com", which is a pain. It means ISP A has to
  31         call 375 people and tell them to add that to their login name.
  32
  33         And now some of you are thinking, "why couldn't you add the realm
  34         in the server based on some other attribute (such as NAS-IP or
  35         Calling-Station)?"  The answer is, you could, but both of those
  36         solutions are a pill to maintain.  For example, what if you want
  37         to merge the huntgroups (and NASs) of ISP A and ISP B?  Then the
  38         NAS-IP method falls apart.  And god forbid the user call from a
  39         different number or change their line for Calling-Station.
  40
  41         So how to solve it?  Enter user collision code in radius...
  42
  43     C.  How does it work?
  44
  45         Currently, it only works when authenticating users via the
  46         following methods in FreeRadius:
  47
  48         o  'users' file ( Auth-Types 'Local' and 'Crypt-Local' _ONLY_ )
  49         o  cached password (and shadow) file users
  50                                 o  rlm_fastusers module (see README.rlm_fastusers)
  51
  52         That's it so far.  Perhaps other module authors will include it in
  53         their code later, but that is for them to decide.
  54
  55         Btw, the reason user collision cannot be implemented (efficiently)
  56         on a non-cached /etc/passwd file is because getpwnam() will always
  57         return the first user it finds with a matching username.  Thus, if
  58         you're going to use the /etc/passwd file, you MUST set 'cache =
  59         yes' in your radiusd.conf.  Or, you could always just put
  60         duplicate usernames in the 'users' files, but you should probably
  61         be caching anyway if you want a speedy server :)
  62
  63 1.  Authentication
  64
  65     It currently works by using the password of the user to uniquely
  66     identify and auth- enticate them.
  67
  68     Example:
  69
  70     ISP A user 'foo' has password 'bar'
  71     ISP B user 'foo' has password 'bleah'
  72
  73     If the user logs in with 'bar' as their password, their login will be
  74     accepted and they will get the reply attributes associated with what
  75     you've entered for the user 'foo' password 'bar' entry.
  76
  77     If the user logs in with 'bleah' as the password, again, they'll be
  78     authenticated, but they will get the reply attributes associated with
  79     user 'foo' password 'bleah'.
  80
  81     So, what happens if two users have the same password?  IT
  82     BREAKS.  Well, ok, it doesn't "break", but every user with the
  83     associated pass will get the same reply attributes, causing grief for
  84     you.  THE CODE DOES NOT CHECK FOR THIS, THAT IS YOUR JOB!
  85
  86     NOTE:  Again, user collision authentication *depends* on the passwords
  87     being distinct!
  88
  89     So the security minded among us are now agast.  I'm not much for this
  90     method myself, but trust me, the corporate folks are gonna love it.
  91     And it's not inherently insecure as long as the passwords remain
  92     different.
  93
  94 2.  Accounting
  95
  96     Ok, so now, how can we tell in the accounting logs which user 'foo'
  97     logged in?  Well, again, you have a little work to do.  The code
  98     identifies the user via a unique value assigned to the 'Class' reply
  99     attribute in the users file.
 100
 101     For example:
 102
 103     foo Auth-Type := Local, User-Password == "bar"
 104     Class = 0x0001
 105
 106     foo Auth-Type := Local, User-Password == "bleah"
 107     Class = 0x0002
 108
 109     Now, you'd add other attributes as well, but let's just start with
 110     'Class' by itself as a reply.  When a user 'foo' logs in with password
 111     'bar', the 'Class=0x0001' reply item gets sent back to the NAS they
 112     dialed into.  The NAS then adds 'Class=0x0001' to the Accounting
 113     'Start' packet it sends for that user, thus uniquely identifying *this*
 114     'foo' in the your accounting logs.
 115
 116     If the user 'foo' logs in with password 'bleah', you will get
 117     'Class=0x0002' in your accounting logs.
 118
 119     Now, again, you should note that it is *your job* to make sure the
 120     'Class' values are different for each user.  If you don't, I can assure
 121     you the phones will ring off the hook when bitchy users get their
 122     bills.
 123
 124     Obviously, this method works only for users in your 'users' files.
 125
 126     If you are using a cached passwd file, then the "Full name" field in
 127     the passwd file you cached will be passed back to the NAS as the value
 128     of 'Class'.
 129
 130     Example:
 131
 132     /etc/passwd  ->  test:x:500:500:0x1001:/dev/null:/dev/null
 133
 134     In this case, "0x1001" will be passed as the value for the 'Class'
 135     attribute when the Auth-Accept packet gets sent back to the NAS, and
 136     then you should see 'Class=0x1001' for that user in your accounting
 137     logs.
 138
 139     Once again, it is your job to ensure that these Class values are unique
 140     for each user.
 141
 142 D.  *Does* it work?
 143
 144     As of 10-01-2000, it is *extremely alpha*.  If you find bugs, by all
 145     means let met know at jeff@apex.net, but make sure you include
 146     relavent sections of your 'users' file and debug output from the
 147     server (radiusd -X).
 148
 149 1.  USAGE
 150
 151                 Set 'usercollide=yes' in your radiusd.conf and either restart or
 152     kill -HUP radiusd.
 153
 154 2.  CAVEATS
 155
 156     Currently does not work with all modules (ie, sql, ldap, etc).
 157
 158 3.  ACKNOWLEDGEMENT
 159
 160     Jeff Carneal - Author
 161     Alan DeKok - for telling me about the 'Class' attribute :)
 162