Foswiki User Authentication Supplement

This document shows suggested configuration settings for several common Foswiki authentication mechanisms.

This Document is under development and may include incomplete or unverified information

Other references:

• UserAuthentication
• UserAuthenticationFAQ

Authentication Scenarios

Open system

This configuration might be used in a personal information wiki (one man wiki) or a small workgroup environment where no controls are required, and anyone can edit without any attribution. No login is required.

• The only user names present will be those shipped with the default installation.
• Everybody edits as 'guest'.
• No access controls; anyone can read anything, anyone can edit (almost) anything.

Open registration

This configuration is appropriate for a wiki behind a firewall, where anyone with access to the network can register on the wiki. It's very simple to set up, and is commonly used in environments where there is no single sign-on (SSO) available.

• Users have to register before they can edit, but there is no checking that a user is a valid person.
• Users can set their password during the registration process.
• Passwords must be at least 8 characters, and are returned in the user's registration confirmation e-mail.
• Foswiki handles usernames and passwords internally.
• User changes are "signed" - you can see who edited what.
• You can define groups of users.
• Access controls available topics
• Attachments are not access controlled!

Pre-registration

Like open registration except that users are pre-registered in bulk, and registration is closed to new users.

• Admins can register new users

Access control of attachments

In the preceding configurations, attachments are not subject to access controls. However you can enable access control checking for attachments, though it comes at a performance cost. If access control of attachments is important to you, then your first option is to use one of the web server authentication mechanisms described below, and always require that a user be logged in (no anonymous access to attachments). Your second option (the most secure, but also the slowest in performance terms) is to require access control checks on every attachment access.

Using the web server to secure attachments

To be written

Applying access controls to attachment

To be written

Web server authentication

Web server sign-on is frequently used in a corporate environment. The Login ID is typically not the Wiki name. Authentication is provided by a module plugged in to the web server; by the time a request reaches Foswiki, the web server has already validated the user and established their "corporate identity". Most web servers support a range of different authentication methods; in the following we'll discuss the most common Apache authentication modules.

Apache authentication using Basic Auth

Basic Auth is the simplest authentication mechanism provided by the Apache web server. Passwords are passed in the clear

• Uses a password file stored on the server, called the '.htpasswd' file.
• Userid/Password are stored in the Apache .htpasswd file. Foswiki can optionally manage the file, or it can be handled by an external function. Registration is allowed, but it may be assumed that the userid/password has previously been established external to Foswiki, so the password is not included on the registration screen. Note: (In Foswiki 1.0.x: In order to allow the user to enter the password on registration, the registration page needs to be updated manually.)

Apache authentication using X.509 certification

X.509 authentication is used in environments where users have X.509 personal identity certificates. It provides a good balance of convenience and security. The user is authenticated by SSL Client Authentication - that is, the user's web browser must supply the user's personal identity certificate during the SSL connection negotiation. The webserver is generally configured to refuse connections that don't supply a satisfactory certificate. Foswiki maps information in the X.509 certificate to the user's name and WikiName. This is highly configurable to deal with the multitude of certificate issuers. Login is automatic - yet highly secure. The .htpasswd file is used - but data storage is not compatible with Apache Auth. For higher security, web browsers/certificates can require a password for access to the client's certificate store - this does not involve Foswiki. For details, see: X509UserPlugin.

Apache authentication using LDAP

See 'LDAP' below for more information on LDAP.

Apache authentication using Windows NTLM

Apache authentication using Windows SSPI

LDAP

Probably the most common single sign on (SSO) solution is to use an LDAP (Lightweight Directory Access Protocol) server to check users and get their details. LDAP is implemented by a number of different SSO services, including Microsoft's "Active Directory" product.

WARNING! LDAP is simply a network protocol, which supports remote access to a database of user information. There are a number of different schemas that might be used on an LDAP server. Make sure that your server supports a standard schema.

In the simplest case LDAP can be used just for user authentication, and the standard Foswiki user information services (user and group topics) used for all other user information.

to be written: instructions for setting up LDAP (for example, with auth_ldap)

Windows2003Authentication contains a sample instruction for TemplateAuth using LdapContrib to Windows 2003 LDAP/ActiveDirectory.

LDAP-based user authentication and information service

_to be written: instructions for setting up LdapContrib

Other SSO solutions

• Shibboleth
• JA-SIG Central Authentication Service (CAS)
• Web-SSO
• Kerberos - Windows2003Authentication
• Java Open Single Sign-On (JOSSO)
• SigSSO
• PAM

Cross-reference of configuration settings

Location	Setting	Default	Open System	Simple Auth	Apache
Core	{UserMappingManager}	'Foswiki::Users::TopicUserMapping';	BaseUserMapping
Core	{RenderLoggedIn ButUnknownUsers}	$FALSE;
Core	{PasswordManager}	'Foswiki::Users::HtPasswdUser';	None
Core	{MinPasswordLength}	1;		8
Core	{LoginManager}	'Foswiki::LoginManager::TemplateLogin';	None		ApacheLogin
{Sessions}	{UseClientSessions}	1;
{Sessions}	{ExpireAfter}	21600;
{Sessions}	{ExpireCookiesAfter}	0;
{Sessions}	{IDsInURLs}	0;
{Sessions}	{UseIPMatching}	1;
{Sessions}	{MapIP2SID}	0;
{TemplateLogin}	{PreventBrowser RememberingPassword}	0;
{LoginNameFilterIn}	qr/^[^\s\*?~^\$@%`"'&;	<>\x00-\x1f]+$/;
{Htpasswd}	{FileName}	'{DataDir}/.htpasswd';			set as required
{Htpasswd}	{Encoding}	'crypt';	(ignored)	poor default	poor default
{Register}	{EnableNewUserRegistration}	$TRUE;	FALSE
{Register}	{HidePasswd}	$TRUE;		FALSE
{Register}	{NeedVerification}	$FALSE;		(optional)
{Register}	{RegistrationAgentWikiName}	'RegistrationAgent';
{Register}	{AllowLoginName}	$FALSE;			TRUE
{CasPlugin}	{LoginManager}	'Foswiki::LoginManager::CasLogin';
{Ldap}	{LoginManager}	'Foswiki::LoginManager::LdapApacheLogin';
{Ldap}	{PasswordManager}	'Foswiki::Users::LdapPassword';
{Ldap}	{UserMappingManager}	'Foswiki::Users::LdapUserMapping';
{Ldap}	{Host}	'my.domain.com';
{Ldap}	{Port}	389;
{Ldap}	{Version}	'3';
{Ldap}	{Base}	'dc=my,dc=domain,dc=com';
{Ldap}	{BindDN}	'';
{Ldap}	{BindPassword}	'secret';
{Ldap}	{UseSASL}	0;
{Ldap}	{SASLMechanism}	'PLAIN CRAM-MD5 EXTERNAL ANONYMOUS';
{Ldap}	{UseTLS}	0;
{Ldap}	{TLSSSLVersion}	'tlsv1';
{Ldap}	{TLSVerify}	'require';
{Ldap}	{TLSCAPath}	'';
{Ldap}	{TLSCAFile}	'';
{Ldap}	{TLSClientCert}	'';
{Ldap}	{TLSClientKey}	'';
{Ldap}	{UserBase}	'ou=people,dc=my,dc=domain,dc=com';
{Ldap}	{LoginFilter}	'objectClass=posixAccount';
{Ldap}	{LoginAttribute}	'uid';
{Ldap}	{WikiNameAttribute}	'cn';
{Ldap}	{NormalizeWikiNames}	1;
{Ldap}	{NormalizeLoginNames}	0;
{Ldap}	{WikiNameAliases}	'';
{Ldap}	{AllowChangePassword}	0;
{Ldap}	{SecondaryPasswordManager}	'none';
{Ldap}	{GroupBase}	'ou=group,dc=my,dc=domain,dc=com';
{Ldap}	{GroupFilter}	'objectClass=posixGroup';
{Ldap}	{GroupAttribute}	'cn';
{Ldap}	{PrimaryGroupAttribute}	'gidNumber';
{Ldap}	{MemberAttribute}	'memberUid';
{Ldap}	{MemberIndirection}	0;
{Ldap}	{WikiGroupsBackoff}	1;
{Ldap}	{NormalizeGroupNames}	0;
{Ldap}	{MapGroups}	1;
{Ldap}	{MaxCacheAge}	86400;
{Ldap}	{PageSize}	500;
{X509UserPlugin}	{LoginManager}	'Foswiki::LoginManager::X509Login';
{X509UserPlugin}	{PasswordManager}	'Foswiki::Users::X509PasswdUser';
{X509UserPlugin}	{UserMappingManager}	'Foswiki::Users::X509UserMapping';
{X509UserPlugin}	{System}	"; - Internal use only
{X509UserPlugin}	{Debug}	0;
{X509UserPlugin}	{ForceAuthentication}	1;
{X509UserPlugin}	{RequireWikinameFromCertificate}	1;
{X509UserPlugin}	{RegisterInUsersTopic}	1;
{X509UserPlugin}	{Cert2Wiki}	"^CN";
{X509UserPlugin}	{RegistrationTopic}	"UserRegistration";
{X509UserPlugin}	{RegisterUsersWithLoginName}	0;