git.infodrom.org Git - debian/mod-auth-mysql/blob - USAGE

   1 OK, so it's compiled cleanly and now it's time to use it.  You've come to
   2 the right place.
   3
   4 Creating the necessary SQL information
   5 --------------------------------------
   6
   7 At the very least, you need a table in your database which has a list of
   8 usernames and their corresponding passwords.  Having a field listing the
   9 group users belong to, or a separate table for that, is useful too, but you
  10 need usernames and passwords as a minimum.
  11
  12 For instance:
  13
  14 create table mysql_auth (
  15         username char(25) not null,
  16         passwd char(25),
  17         groups char(25),
  18         primary key (username)
  19 );
  20
  21 This would work quite well.
  22
  23 NOTE 1: You don't have to use a new table for the purpose of storing
  24 usernames and passwords; I quite happily use a 'members' table (with all
  25 sorts of other interesting information in it) with mod-auth-mysql.
  26
  27 NOTE 2: The names given above are merely the defaults for the module.  They
  28 can all be overridden if you have different names for your fields (eg
  29 password instead of passwd).
  30
  31 Once your table(s) is/are created, you need to put the data in as
  32 appropriate.
  33
  34
  35 Telling Apache to protect the website
  36 -------------------------------------
  37
  38 First up, tell the module where it should be getting it's info from:
  39
  40 Auth_MySQL_Info <host> <user> <password>
  41
  42 or
  43
  44 AuthMySQL_DefaultHost <host>
  45 AuthMySQL_DefaultUser <user>
  46 AuthMySQL_DefaultPassword <password>
  47
  48 This should be placed globally.
  49
  50 If you're going to use the same database all over your web server, you can
  51 use
  52
  53 Auth_MySQL_General_DB <database>
  54
  55 to set that.  This setting can be overridden in .htaccess files if
  56 AuthMySQL_AllowOverride is set.
  57
  58 On that topic, if you want .htaccess files to be restricted in what they're
  59 able to connect to database-wise, you can
  60
  61 AuthMySQL_AllowOverride no
  62
  63 and the host, user, password, and database name cannot be changed.
  64
  65 Create a .htaccess file in the directory you want to protect (or put the
  66 directives inside a Directory section in httpd.conf) with something like the
  67 following:
  68
  69 AuthName "My Company's Financial Information - Top Secret"
  70 AuthType Basic
  71 require valid-user
  72
  73 This will allow any user who can supply a username and password access.
  74
  75 If you replace the require line with
  76
  77 require user bill fred jane
  78
  79 then only users who can successfully authenticate as bill, fred, or jane
  80 will be allowed access.  Or, if you set the require line to
  81
  82 require group executives
  83
  84 then only users who are a part of the executives group will be allowed
  85 access to the documents in that directory.
  86
  87 A special note: multiple require lines are logically OR'd -- if the user's
  88 details match *any* of the require lines supplied, the user will be
  89 considered authenticated.  For example,
  90
  91 require user jane joe
  92 require group executives
  93
  94 means that if the user is jane or joe, or the user is in the executives
  95 group, they will be let in.  Neither jane nor joe have to be in the
  96 executives group.
  97
  98 Passwords
  99 -----------
 100
 101 There is also the slight matter of how the passwords are stored in the
 102 database.  Several different methods are available:
 103
 104 Plaintext
 105 Crypt_DES
 106 Crypt_MD5
 107 Crypt (basically Crypt_DES and Crypt_MD5, plus any other schemes your local
 108         crypt() call implements)
 109 PHP_MD5 (MD5 hashes, encoded the way PHP and MySQL both do it)
 110 SHA1Sum (SHA1 hashes, encoded as a 40 character lowercase hex string)
 111 MySQL (the hashing scheme used by the MySQL PASSWORD() function)
 112
 113 You should list all of the available ways your passwords can be encoded in
 114 the Auth_MySQL_Encryption_Types config item.  By default, only Crypt_DES is
 115 enabled.  A common example, if you're using a PHP script to manage
 116 passwords, might be:
 117
 118 Auth_MySQL_Encryption_Types PHP_MD5 Crypt
 119
 120 Note that adding more types to be checked slows down authentication, and
 121 allowing the Plaintext type means that any hashed passwords stored in the DB
 122 become plaintext equivalents.
 123
 124 The full set of directives available are now listed in the file DIRECTIVES,
 125 for ease of perusal.
 126
 127 Disable other Auth methods
 128 --------------------------
 129
 130 For some reason Apache has problems handing over authority to this
 131 module if this is requested an another auth module is also loaded.
 132
 133 If you have another authentication module loaded, you'll have to
 134 disable it the hard way.
 135
 136 AuthBasicAuthoritative Off
 137 AuthUserFile /dev/null
 138
 139 The following option is not sufficient
 140
 141 Auth_MySQL_Authoritative On
 142
 143 If you experience similar problems with group membership, try
 144 repeating the same procedure with AuthGroupFile.