From: Subject: UW/ID-AUTH Web Page Authentication Date: Wed, 14 Nov 2001 08:38:33 +0100 MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_NextPart_000_0044_01C16CE7.BEF2E880"; type="text/html" X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4522.1200 This is a multi-part message in MIME format. ------=_NextPart_000_0044_01C16CE7.BEF2E880 Content-Type: text/html; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable Content-Location: http://ist.uwaterloo.ca/security/howto/2000-02-18.html UW/ID-AUTH Web Page Authentication

UW/ID-AUTH Web Page Authentication

Information Systems and Technology
University of Waterloo=20
18-Feb-2000

3D[IST]=20

Synopsis

The UWdir Identification and Authentication service can be = used to=20 provide authenticated access to web pages (and scripts) under the = Apache Web=20 Server (which is widely available on xhier'ed systems). The = information=20 manager can limit access to just those users who ought to have access = and=20 forbid others. This note describes how to configure access controls, = notes=20 some issues for web programmers and shows how a user can acquire a UW = userid=20 and password.=20
You should not consider using the Authentication = Services=20 described here unless you have first configured your Apache web = server to=20 enable SSL protected services. See the Quick = Guide:=20 Configuring Apache-SSL.

Discussion

If you have never accessed a web site that requires = authentication=20 please see the Sample = Page.=20 The sample restricts access to login name "guest" with the = password=20 "sample" -- try it a few times with the wrong name/password and = then=20 finally with the right answer. The Sample = Page=20 makes some important observations that you should know.=20

The UWdir Authentication Service is implemented by a Microsoft = Domain. The=20 Domain is named "uwaterloo.ca". It's implemented on an NT4 = Primary=20 Domain Controller (PDC) called "stork" with an NT4 Backup Domain = Controller=20 (BDC) called "ibis". The Authentication Protocol between clients (like = the=20 Apache web server) and servers (either PDC or BDC) is called the = Server=20 Message Block (SMB) Protocol. The SMB protocol is also used when = client=20 systems (like a Windows95 PC) mount file systems from Microsoft file = servers.=20 The SMB protocol is reasonably secure -- it's not perfect by = any=20 means, but it is good enough.

Getting a UWuserid and Password

There are lots of users who are already in the = uwaterloo.ca=20 Domain -- they use the same login name and password when they login in = the=20 morning, when they mount file systems (on servers that participate in = the=20 domain), etc. The objective of the UWdir ID/AUTH project was to = establish a=20 single userid/password pair that could be used by lots of services. = There are=20 many more users who don't have a userid/password in the = uwaterloo.ca=20 Domain --- they use systems that don't participate.=20

Any current UW faculty, staff, or student (with a very few = exceptions) may=20 approach the UWdir system and obtain a UWuserid and Password. Self = service=20 maintenance of UWdir data requires a userid/password in the=20 uwaterloo.ca Domain. For more information on that see the UWdir and Authentication = Services=20 site. The site uses SSL to protect sensitive data you might transmit = to the=20 server -- you'll see this note on the page:=20

Authentication services are protected by the Secure Socket Layer = (SSL)=20 using a certificate signed by the IST Certificate=20 Authority. If you have not done so already, you should load the=20 certificate for that authority -- click = here and=20 follow the instructions.

Access to various pages at = that site=20 will require authentication. The methods used there helped to shape = this=20 document.

Sample Configuration Files

A sample .htaccess file that limits access to = any=20 user who can authenticate in the uwaterloo domain. All data in the = directory=20 (and any data in subdirectories included within that directory) are = access=20 controlled:=20 
# 1) Information text for login panel, basic protocol

AuthName "UWaterloo/NT Domain Authentication"
AuthType Basic

# 2) The Apache/Authentication method and paramers

PerlAuthenHandler Apache::AuthenSmb
PerlSetVar myPDC stork
PerlSetVar myBDC ibis
PerlSetVar myDOMAIN uwaterloo.ca

# 3) Conditions/Requirements to be met=20

require valid-user

In the first section the AuthName directive defines the = Realm. That=20 will appear in the login panel that your browser pops up when = authentication=20 is required. I recommend you use the value I've shown in the example. = The=20 AuthType defines how the browser communicates the login name = and=20 password to the Apache web server (this will always be the "Basic" = protocol).=20

In the second section the PerlAuthenHandler directive = defines the=20 method used by the Apache web server to do the authentication. The=20 Apache::AuthenSmb method authenticates a name/password pair = using the=20 Server Message Block (SMB) Protocol -- that's the Microsoft protocol = for=20 authenticating against a Domain. The PerlSetVar directives are = to set=20 some extra variables for the authentication method -- viz. = where is=20 the Primary Domain Controller (the PDC), where is the Backup Domain = Controller=20 (the BDC) and what is the name of the Domain.=20

Beware: the Apache::AuthenSmb = method is=20 part of the libauthen_perl xhier package, which is not a = prerequisite=20 for the xhiered web server packages.

The final section imposes a requirement -- the user must be a=20 valid-user. That means the user must have successfully = authenticated.=20 Ie. the name/password pair is correct in the uwaterloo.ca = Domain. The=20 server will not challenge the browser to authenticate unless there is = a=20 requirement.=20

A sample .htaccess file that limits access to a short list = of users=20 (an Authorization list):=20 

AuthName "UWaterloo/NT Domain Authentication"
AuthType Basic

PerlAuthenHandler Apache::AuthenSmb
PerlSetVar myPDC stork
PerlSetVar myBDC ibis
PerlSetVar myDOMAIN uwaterloo.ca

# must only be one of this list of users

require user reggers rwatt mikeb
require user jvoskam wcwince
You should understand the first require = directive to=20 be satisified if the user has authenticated and is any one of the = users=20 listed. Likewise you can list several require directives -- the = requirements are satisified if at least one is satisified. Note the=20 distinction between Authentication (the user presents a valid = user/password=20 pair) and Authorization (the user is one of those listed). =

Group Membership Requirements

The Apache web server also supports group membership directives = like the=20 following to manage Authorization:=20 

require group cs304 cs205 es127
Group membership authorization requires that an=20 authenticated user be a member of one of the groups listed. Apache = implements=20 several group membership methods (compare with authentication = methods) but a discussion of those is outside the scope of = this=20 document -- I've given you some hints to get started. Suffice to say = there=20 will be a specification of the method and some variables for = the=20 method. See the Server=20 Documentation on this machine and especially the Apache=20 directives for Group authorization.

Common Gateway Interface (CGI)

Common Gateway Interface (CGI) scripts can be access = controlled as=20 well. The preferred method for scripting in the Apache Web server is = to use=20 the SetHandler directive (not the cgiwrap method that = predates=20 functionality now built into the server). For example, this is a = fragment from=20 the .htaccess file used for self service access to Update Your = Information in=20 UWdir:=20 
AuthName "UWaterloo/NT Domain Authentication"
AuthType Basic

PerlAuthenHandler Apache::AuthenSmb
PerlSetVar myPDC stork
PerlSetVar myBDC ibis
PerlSetVar myDOMAIN uwaterloo.ca

<Files Update>            # script to update user's UWdir entry
     require valid-user
     SetHandler cgi-script
</Files>
If authentication is required to access a CGI script = then=20 the authenticated user's name is available to the script. The script = mentioned=20 in this example is written in Perl and contains these statements:=20 
my ($you)    =3D $ENV{REMOTE_USER};

 ....

unless ($you) {
    syslog("auth|err","MgmtUWdir(Signon-ERR): did not authenticate =
$peer");
    Die("ERROR: Serious configuration problems");
}
The authenticated user name is provided in an = environment=20 variable and the script may safely assume that the user has = authenticated and=20 meets all require directives. Note: the CGI script has no = access to=20 the user's password! The user gives the password to the server, = not to=20 the script.

Cautions/Beware

Some final observations:=20

  • When things don't work as expected: check the server log=20 files! 
    [2:51pm aix43] tail =
/software/www_server/logs/error_log
[Fri Mar  3 11:06:03 2000] [crit] [client 129.97.108.185] \
  (13)The file access permissions do not allow the specified action.: \
  /home/reggers/public_html/.htaccess pcfg_openfile: \
  unable to check htaccess file, ensure it is readable
[Fri Mar  3 13:52:14 2000] [alert] [client 129.97.108.185] \
  /home/reggers/public_html/.htaccess: AuthName takes one argument, \
  The authentication realm (e.g. "Members Only")

  • All of this works well with the Apache web server (versions 1.2 = and 1.3=20 distributed with xhier) -- UWdir web pages use all the strategies = described=20 here. The web server has to be built to support Perl extensions (the = xhier=20 version is) and you'll need the the Apache::AuthenSmb module = (that's=20 part of the xhier libauthen_perl xhier package). The Apache = server=20 distributed in xhier supports SSL. The Apache server distributed = your vendor=20 (Linux, AIX or etc.) may not support SSL, the = Apache::AuthenSmb=20 module or any other Perl extensions. Other web servers (eg. the = Oracle Web=20 Server) may not support NT Domain Authentication.=20

  • Microsoft's Internet Information Service (the IIS web server so = common=20 on NT) no doubt will support authentication against an NT = Domain --=20 we've not had an opportunity to investigate very far. It ought to be = trivial=20 if the server is a member of the domain. Likewise IIS will support = SSL with=20 a host certificate signed by the local CA -- we have some first = draft=20 documentation we've developed.=20

  • It's considered very bad form to ask a user to submit their = login name=20 and password and not protect their password with SSL. The = user needs=20 to be cautious and note the URL that they've requested when a login = is=20 required.=20

  • Apache-1.3 supports the SSLRequireSSL and that can be = used to=20 force a secure connection when transmitting a password -- highly = recommended=20 (but not supported in Apache-1.2).=20

  • The error message you get back when a login fails (you didn't = submit a=20 valid user/password pair) is exactly the same as the error message = you get=20 back when you don't satisfy the requirements. Consider a site = restricted to=20 users larry, mary and bob. A user fred = will be=20 denied access even if he submits his valid user name/password. The = error he=20 gets is exactly the same as the page mary gets when she types = her=20 password incorrectly! There is no clear distinction between = Authentication=20 and Authorization failure.=20

  • Some browsers (Internet Explorer for one, others perhaps) will = let a=20 user save their userid/passwd that they give in response to a login=20 challenge. Saving your password is a very bad idea -- = especially on=20 systems that are shared by several users!=20

  • All browsers cache the user name/password when you successfully = login.=20 The name/password is submitted, without user intervention, when you = access=20 other pages that require authentication. There is no good way to = clear the=20 cache short of exiting the browser. That makes the authentication = strategy=20 we've described here inappropriate on public kiosk-style work = stations!=20

  • There is no guest user in the uwaterloo.ca domain! = The=20 sample used a different authentication method.=20

  • In the not so olden days Microsoft authentication servers were = case=20 insensitive -- if a user's password is "Jan3y" then "jan3y" will = work just=20 as well. The Domain server can be configured to not allow that but = it would=20 break all the "olden systems" we still have.
2000/03/02-2000/10/19; Reg Quinton, Information Systems and Technology =
------=_NextPart_000_0044_01C16CE7.BEF2E880 Content-Type: image/gif Content-Transfer-Encoding: base64 Content-Location: http://ist.uwaterloo.ca/ISTlogo.gif R0lGODlhYABfALMAAP///wAAAJ2dnYAGHPDm6F1dXSwsLNK3vKJJWkZGRv7+/saQmrNreIKCgpIq PeHM0CH5BAEAAAAALAAAAABgAF8AAAT+EMhJq7046827/2AojmRpnmiqrmzrvuZxbAoB3yAzT8ww MJPHAOHY4Y4SI2AxUCQHB6ZzCR0ikUKGDXCASoSL3rQHcAAzhMP2SmIOtorfhFnkaQcLjcMhZ48I CE0TCGcbBGsXe10Pfh0EOhMEPkonj10OD4iNFwd7A4wSCwdTKZKieJsbCAt7DqQuXT6gCpSpAAoO C4SaLWmgAEK/jWu4XpsMDo+8OIF5Eq9sTg5EdVcKrM22EmY+DNDMA8nI32wPZsJHgEXhBOTat3vL KQqBMgju2g9drDfF6O8UOmHDh4LAAoLvEARyoaAQQA7XaqFghfDhhUcM/oWQhMrih2v+PpyZIMDH oUcNgfZU9HBA40kLZm693KQPxQMG3jIcaMCTp4cHDwQIHSpgCwGiSJMOlXgCFx8EGQQEmBrAgKEC BqhqnbpD6tavXwtguKlFhBBaDqJuzaCgAditOw68nRtArIU4Q6BuDBcTg9epVi8oSECXatfCYO1W MCVFxIFV+P5WxVAAMdcklrcqrpAr3EoRAgyINpDgguTCcUUnUJ1V62rSohtgeLTA5QVR8kQQaE21 AFMNbqkGhkHkUwq5WmWPCA4YRycfuU4wn/rZwvThH/SJ3BDl8W8JAlav3iyhcu8S10HgDQdLK/by WsmDSA9ClLncJCS/B2B+qvwP9H3+cAAyxqygn3Xu4QeceyHQYdwGQoTEwYEVnNZAdRQECMIDCnHQ BU7fgcfgYl8ZUFQIGjriQx8aCKTGhCNW0N9WBhRwIgcpdoBbBz1MAqNwF/E2l4345OgCUAoCQKEF u2XWwDJGarMkk9PRZQAvUWpwyAtTXhQeYldWkGUG65g0G5IexmjITqu9pdwEXXJAEgNEbMDHitv5 peYHRwlJXYZ7yllSWijhtEBtPzZHwmBbCQAokCHgVBMLcYJAgGaPKupRpSDMWNoEY27CKYBqhtrI qB5MaaofqHag4ao2VdQqB55mOlkID2D4WJ6cbJUkW1u9CQCsc5hR3T4IKRBsCTP+BqDErIv15cEh tlFAWHzV3nWAnwG8QuwzW76A3FfKKcAabOi6KWagDzXr3zOZJbgupC8xiikAl8Z72byaspGkAs3a pWy8Bmi06iMotERIBwdcW5cE+SKWgADurLqPCXixku0EtAiwgwJKIZUrhEjJqU+BIxSxh5kzwbTi gyMUg0nLNGgn7QgMHEQzWxTgEmJ29+xMwS5BqBCLzjs35AMCvwoYThZCd/EIOytcQ09HNEuyBxMb R4r1zo/lnEwvOxiURyYPDbgGMk2TEMgPN6eCDB9tV4JHLHWrAAcUwfg7Dd1yuyJBOGz7MXUt7Rxx Mb5EN0LLBcgskLfXk18x9Q94lWNACyhaC91D4aV44sxjmePQOQtMAFCn0KEUiI1tq0MchRVUsMLy TBR98UNjSzROhC42aN2DDdeYUbotHwZiw4c4SfB5R9OYwnoH9CjifBNrDwBAH2KsMv20I+M7RB9S 9PUA0t//IUMkB6Gd/vvwxy///PTXz0EEADs= ------=_NextPart_000_0044_01C16CE7.BEF2E880 Content-Type: image/jpeg Content-Transfer-Encoding: base64 Content-Location: http://ist.uwaterloo.ca/security/howto/images/back.jpg /9j/4AAQSkZJRgABAgEASABIAAD/7QG4UGhvdG9zaG9wIDMuMAA4QklNA+kAAAAAAHgAAwAAAEgA SAAAAAAC2gIo/+H/4gL5AkYDRwUoA/wAAgAAAEgASAAAAAAC2gIoAAEAAABkAAAAAQABAQEAAAAB Jw8AAQABAAAAAAAAAAAAAAAAAAIAGQGQAAAAAABAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAA4 QklNA+0AAAAAABAASAAAAAEAAQBIAAAAAQABOEJJTQPzAAAAAAAIAAAAAAAAAAA4QklNJxAAAAAA AAoAAQAAAAAAAAACOEJJTQP1AAAAAABIAC9mZgABAGxmZgAGAAAAAAABAC9mZgABAKGZmgAGAAAA AAABADIAAAABAFoAAAAGAAAAAAABADUAAAABAC0AAAAGAAAAAAABOEJJTQP4AAAAAABwAAD///// ////////////////////////A+gAAAAA/////////////////////////////wPoAAAAAP////// //////////////////////8D6AAAAAD/////////////////////////////A+gAADhCSU0EBgAA AAAAAgAC/+4ADkFkb2JlAGSAAAAAAf/bAIQADAgICAkIDAkJDBELCgsRFQ8MDA8VGBMTFRMTGBEM DAwMDAwRDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAENCwsNDg0QDg4QFA4ODhQUDg4ODhQR DAwMDAwREQwMDAwMDBEMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwM/8AAEQgAYABgAwEiAAIR AQMRAf/EAT8AAAEFAQEBAQEBAAAAAAAAAAMAAQIEBQYHCAkKCwEAAQUBAQEBAQEAAAAAAAAAAQAC AwQFBgcICQoLEAABBAEDAgQCBQcGCAUDDDMBAAIRAwQhEjEFQVFhEyJxgTIGFJGhsUIjJBVSwWIz NHKC0UMHJZJT8OHxY3M1FqKygyZEk1RkRcKjdDYX0lXiZfKzhMPTdePzRieUpIW0lcTU5PSltcXV 5fVWZnaGlqa2xtbm9jdHV2d3h5ent8fX5/cRAAICAQIEBAMEBQYHBwYFNQEAAhEDITESBEFRYXEi EwUygZEUobFCI8FS0fAzJGLhcoKSQ1MVY3M08SUGFqKygwcmNcLSRJNUoxdkRVU2dGXi8rOEw9N1 4/NGlKSFtJXE1OT0pbXF1eX1VmZ2hpamtsbW5vYnN0dXZ3eHl6e3x//dAAQABv/aAAwDAQACEQMR AD8A9GHtHKbcToFKQmn5BFSwlS8p1TaKQLQElLFgTe3hJz5UNZSUkcdICZo8U0kJCSkpnP7o+aGT rqiF2kKOwclJSzXaqTgCowJTgT3SU//Q9FAcE+3u5Rc4ypAyNSipQMmAE5b4mEwIHCkAOTqUlMDH ASACRBJ0TQQUlMnN00TNHjwn3GIT699ElK3DwTF274JbR3PyShJSgB2GiRmNE4BPJ0UiQElP/9H0 QCU5GibcVMERqipgCZRI8SogDnukZnQJKZEho05UdeSmg904geZSUrhNukqYb4qLi1qSlvhqniOT qnDhGiiG6yUlMtY0US091MEnRo+ag+Qkp//S9GO3gJASkPIJ4J0CKlSBwmk/BLYZklOGg8lJSwPh qnBhMSQYCcDTXRJSxeeygZKmSANAo6JKUAQlOvKm0AhRLDKSmQPYapbZ1KW6BCYvJ0SU/wD/0/Rw AdJUpa1QGvCRb4mEVLPdPCZpSjXRSASUtu8FJuupUHAgqTYiSUlLu93CiWQFOWhR55OiSlhITgHu lpymJKSlyG90vhoEhPhqlEauPySU/wD/1PRwY0ak4QOZKZvkJKltJ5RUj1TsKk4gaBRhJS5IJ4SM p5ACaZSUrb4n5JAeSbvpqpapKXAJ1KTiAmc48BQM90lLh5lORPKiG90jokp//9k= ------=_NextPart_000_0044_01C16CE7.BEF2E880--