NOTE: This is a HistoricalDocument topic. It used to be distributed in an earlier TWiki release, but is no longer part of the official TWiki distribution. Post questions, error notes, and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

Basic Authentication

This page explains what Basic Authentication is.

Basic Authentication is not a TWiki service, it is a service of your web server. Configuration of Basic Authentication is necessarily a function of your web server, both Apache and IIS require the web server administrator to set parameters to initiate this service. To implement Basic Authentication for your specific web server you will need to consult each server's documentation for the particulars. In short, you will need to read another manual than the TWiki manuals to get Basic Authentication working. This page will give you a broad explanation of the principles of Basic Authentication.

Basic Authentication and Security

Caution is in order before you charge off and set up Basic Authentication. First, it is not really secure. Unless you have SSL2 encryption enabled, or are connecting over a VPN, the traffic between the server and a client is plain text. A packet sniffer can read the traffic and concievably read your userid and password as Basic Authentication starts up. Hiding this traffic and the rest of a session is why encryption exists. However, like a lock on your front door, the idea behind Basic Authentication is to deter the casual snoop.

A second caution, if there is a bug in your configuration or in your server, Basic Authentication can fail in a hard-to-detect manner. This obscurity is due to the authenticated session actually being layered over a connection-less protocol (HTTP).

Client and Server Interaction

To avoid having the user resend his/her userid and password with every HTTP connection the client and server have resorted to a couple of common conventions. These conventions are:

1. The client browser remembers the userid and password for a given domain name and "realm". The browser then automatically sends the userid and password with every HTTP transaction (command/response pair). Security is not helped by this userid/password being resent in plaintext with every transaction.
   
   
2. The server remembers the IP# of the incoming connection and associates it with the userid of that session. Every subsequent connection then assumes the userid when a connection arrives from an IP# associated with a previously authenticated userid. Apparently TWiki does not time out this information which it stores in the (twiki dir)/data/remoteusers.txt file. See the TWiki documentation on Partial Authentication for more on this.

Debugging your Basic Authentication means scouring out all the authentication information on both your client and server. Until you do so a Basic Authentication bug can be elusive. Of course you need administrator access to the web server to configure, test, and often debug Basic Authentication.

User Login and Logout

Many modern browsers allow one to "clear" passwords and other information from the browser data store. However, once authenticated to a page many browsers, FireFox for one, will preserve that authentication till the program is terminated. Certainly in FireFox, just closing the authenticated window will not when reopened trigger a Basic Authentication challenge; for the program and all associated windows and tabs must also be terminated to force re-authentication. To avoid this necessity in FireFox or Mozilla use the Clear HTTP Auth or Web Developer extensions.

When you set up Basic Authentication you will see that TWiki needs a means of user login and user logout. This would allow you to easily shift between users to see what view, edit, etc. authorizations are working.

Because Basic Authentication information is stored on the client the Apache documentation (link below), and other experts believe its not possible to have a user log out. This is in fact not true for one, on "log out," can change the realm supplied to a given client IP# invalidating the client-side stored realm paired with userid/password. The result would be a classic Basic Authentication challenge.

Links to Server Documentation

In order to understand how to implement Basic Authentication on your server, you need to read beyond the TWiki documentation:

Apache

• Apache Authentication, Authorization, and Access Control
• Apache Tutorial - .htaccess files

IIS (Internet Information Services)

• About Authentication (includes Basic Authentication)
• Enabling and Configuring Authentication

-- Contributors: TWiki:Main.RichardFreytag, TWiki:Main.PeterThoeny

Comments & Questions about this Supplemental Document Topic

I have yet to find an explicit means of doing this in TWiki. The closest means is the ChangePassword dialog (which only appears alongside the TWiki.TWikiRegistrationPub rather than TWiki.TWikiRegistration dialog). Accordingly I have cludged the ChangePassword dialog into a LogIn dialog; available for your use.

-- RichardFreytag - 19 Dec 2004

Thanks for explaining this Richard, such contributions are always welcome.

-- MartinCleaver - 19 Dec 2004

Thanks for this good overview explanation Richard. I've been using basic authentication for a few years without understanding as much as you've just given us.

-- MattWilkie - 20 Dec 2004

Richard:

1. Check out the SessionPlugin and use the %LOGIN_OR_WELCOME% tag in the WebLeftBar
2. When logging in you don't want to type your password twice!

-- MartinCleaver - 21 Dec 2004

Thanks Martin! I am learning so am resorting to kludges to get past thin spots in an effort to get things done. If on the LogIn screen you TAB into the second password field its automatically filled. Like I said, a serious kludge that amazingly works while still prompting others with more knowledge.

I check out SessionPlugin and it sounds good but not clear to this newbie quite what it does that isn't already addressed by other authentication methods. If its such a help, and it sounds like it is, why isn't SessionPlugin installed by default?

Documentation generally seems to miss detailing the why of a thing in a rush to give the how. The why (and why not), is only clear after giving it a try - and possibly breaking something and catching flack from user(s).

-- RichardFreytag - 21 Dec 2004

Thanks Richard for contributing this nice document. We will take it into the official documentation. I made a few changes: No need to link to itself (BasicAuthentication vs. Basic Authentication); write in third person; and a few other things.

-- PeterThoeny - 23 Dec 2004

See also: AdminSkillsAssumptions, ApacheConfigGenerator, ApacheLdapAuthSetup, AppendixFileSystem, AuthenticatedButStillTWikiGuest, BasicAuthentication, ChangePasswordDiscussion, CustomUserGroupNotations, DakarMergeProgress, HowToEnableSingleSignOn, HowToLogOff, IncludeTopicsAndWebPages, LogoutAndLogin, ManagingUsers, NewTWikiAdminSteps, PamAuthenticationWithoutApache, PatternSkinPalette, SecuringTWikiSite, SupplementalDocument, TWiki04x02WindowsInstallationGuide, TWikiAccessControl, TWikiAdminCookBook, TWikiDocumentation, TWikiHistory, TWikiInstallationGuide, TWikiInstallationNotes, TWikiOnWindowsIISCygwin, TWikiPreferencesComments, TWikiReferenceManual, TWikiReleaseNotes04x00, TWikiReleaseNotes04x01, TWikiReleaseNotes04x02, TWikiReleaseNotes05x00, TWikiReleaseNotes06x01, TWikiScalability, TWikiScripts, TWikiSiteTools, TWikiSkins, TWikiSystemRequirements, TWikiUpgradeGuide, TWikiUpgradeTo01Dec2000, TWikiUpgradeTo01Dec2001, TWikiUpgradeTo01Sep2004, TWikiUserAuthentication, TWikiUserAuthenticationSupplement, TWikiUserMappingContrib, TWikiUsernameVsLoginUsername, TWikiVariablesNtoZ, UsingSslForAuthenticationOnly, VarAUTHREALM, VarBUBBLESIG, VarLOGIN, VarLOGINURL, VarLOGOUT, VarLOGOUTURL, VarREMOTEUSER, VarSESSIONID, VarSESSIONVAR, VarSESSIONVARIABLE, VarUSERINFO, VarUSERNAME, VarUSERREPORT, VarUSERSIG, VarWIKINAME, VarWIKIUSERNAME, VarWIKIUSERSTOPIC, WebNotify, WelcomeGuest, WikiName, Windows2003Authentication, WindowsInstallCookbook, WindowsInstallCookbookForTWiki04x01, WindowsInstallCookbookHistory