internal package Foswiki::LoginManager

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

• Foswiki::LoginManager::ApacheLogin - This is login manager that you can specify in the security setup section of configure. It instructs Foswiki to cooperate with your web server (typically Apache) to require authentication information (username & password) from users. It requires that you configure your web server to demand authentication for scripts named "login" and anything ending in "auth". The latter should be symlinks to existing scripts; e.g., viewauth -> view, editauth -> edit, and so on.
• Foswiki::LoginManager::Session - Class to provide CGI::Session like infra-structure, compatible with Runtime Engine mechanisms other than CGI.
• Foswiki::LoginManager::TemplateLogin - This is a login manager that you can specify in the security setup section of configure. It provides users with a template-based form to enter usernames and passwords, and works with the PasswordManager that you specify to verify those passwords.

internal package Foswiki::LoginManager

The package is also a Factory for login managers and also the base class for all login managers.

On it's own, an object of this class is used when you specify 'none' in the security setup section of configure. When it is used, logins are not supported. If you want to authenticate users then you should consider TemplateLogin or ApacheLogin, which are subclasses of this class.

If you are building a new login manager, then you should write a new subclass of this class, implementing the methods marked as VIRTUAL. There are already examples in the lib/Foswiki/LoginManager directory.

The class has extensive tracing, which is enabled by $Foswiki::cfg{Trace}{LoginManager}. The tracing is done in such a way as to let the perl optimiser optimise out the trace function as a no-op if tracing is disabled.

Here's an overview of how it works:

Early in Foswiki::new, the login manager is created. The creation of the login manager does two things:

1. If sessions are in use, it loads CGI::Session but doesn't initialise the session yet.
2. Creates the login manager object

Slightly later in Foswiki::new, loginManager->loadSession is called.

1. Calls loginManager->getUser to get the username before the session is created
   • Foswiki::LoginManager::ApacheLogin looks at REMOTE_USER (only for authenticated scripts)
   • Foswiki::LoginManager::TemplateLogin just returns undef
2. If the NO_FOSWIKI_SESSION environment variable is defined, then no session is created and the username is returned. This might be defined for search engine bots, depending on how the web server is configured
3. Reads the FOSWIKISID cookie to get the SID (or the FOSWIKISID parameters in the CGI query if cookies aren't available, or IP2SID mapping if that's enabled).
4. Creates the CGI::Session object, and the session is thereby read.
5. If the username still isn't known, reads it from the cookie. Thus Foswiki::LoginManager::ApacheLogin overrides the cookie using REMOTE_USER, and Foswiki::LoginManager::TemplateLogin always uses the session.

Later again in Foswiki::new, plugins are given a chance to override the username found from the loginManager.

The last step in Foswiki::new is to find the user, using whatever user mapping manager is in place.

ObjectData twiki

The Foswiki object this login manager is attached to.

StaticMethod makeLoginManager( $session ) → $Foswiki::LoginManager

Factory method, used to generate a new Foswiki::LoginManager object for the given session.

ClassMethod new ($session, $impl)

Construct the user management object

ObjectMethod finish()

Break circular references.

ClassMethod _real_trace ($session, $impl)

Construct the user management object

ClassMethod _IP2SID ($session, $impl)

read/write IP to SID map, return SID

ObjectMethod loadSession($defaultUser, $pwchecker) → $login

Get the client session data, using the cookie and/or the request URL. Set up appropriate session variables in the session object and return the login name.

$pwchecker is a pointer to an object that implements checkPassword

$defaultUser is a username to use if one is not available from other sources. The username passed when you create a Foswiki instance is passed in here.

ObjectMethod redirectToLoggedOutUrl($authUser, $defaultUser)

Helper method, called by loadSession, to redirect to the non-authenticated url and return the non-authenticated "default user" login name.

$authUser is the currently logged in user, derived from the request's username.

$defaultUser is a username to use if one is not available from other sources. The username passed when you create a Foswiki instance is passed in here.

ObjectMethod checkAccess()

Check if the script being run in this session is authorised for execution. If not, throw an access control exception.

ObjectMethod complete()

Complete processing after the client's HTTP request has been responded to. Flush the user's session (if any) to disk.

StaticMethod expireDeadSessions()

Delete sessions and passthrough files that are sitting around but are really expired. This assumes that the sessions are stored as files.

This is a static method, but requires Foswiki::cfg. It is designed to be run from a session or from a cron job.

ObjectMethod userLoggedIn( $authUser, $wikiname)

Called when the user is known. It's invoked from Foswiki::UI::Register::finish and from loadSession (above) once credentials are validated.

1. when the user follows the link in their verification email message
2. or when the session store is read
3. when the user authenticates (via templatelogin / sudo)

• $authUser - string login name
• $wikiname - string wikiname

ObjectMethod _myScriptURLRE ($thisl)

ObjectMethod _rewriteURL ($this, $url) → $url

ObjectMethod _rewriteFORM ($thisl)

ObjectMethod endRenderingHandler()

This handler is called by getRenderedVersion just before the plugins postRenderingHandler. So it is passed all HTML text just before it is printed.

DEPRECATED Use postRenderingHandler instead.

ObjectMethod rewriteRedirectUrl( $url ) ->$url

Rewrite the URL used in a redirect if necessary to include any session identification.

• $url - target of the redirection.

ObjectMethod getSessionValues() → \%values

Get a name->value hash of all the defined session variables

ObjectMethod getCGISession()

Get the currect CGI session object

ObjectMethod getSessionValue( $name ) → $value

Get the value of a session variable.

ObjectMethod setSessionValue( $name, $value )

Set the value of a session variable.

ObjectMethod clearSessionValue( $name ) → $boolean

Clear the value of a session variable. We do not allow setting of AUTHUSER.

ObjectMethod forceAuthentication() → boolean

VIRTUAL METHOD implemented by subclasses

Triggered by an access control violation, this method tests to see if the current session is authenticated or not. If not, it does whatever is needed so that the user can log in, and returns 1.

If the user has an existing authenticated session, the function simply drops though and returns 0.

ObjectMethod loginUrl( ... ) → $url

VIRTUAL METHOD implemented by subclasses

Return a full URL suitable for logging in.

• ... - url parameters to be added to the URL, in the format required by Foswiki::getScriptUrl()

ObjectMethod getUser()

Should be implemented by subclasses

If there is some other means of getting a username - for example, Apache has remote_user() - then return it. Otherwise, return undef and the username stored in the session will be used.

This method of getting the user assumes that the identified user has been authenticated in some way (for example, by the web server)

ObjectMethod isValidLoginName( $name ) → $boolean

Check for a valid login name (not an existance check, just syntax). Default behaviour is to check the login name against $Foswiki::cfg{LoginNameFilterIn}

ObjectMethod _LOGIN ($thisl)

ObjectMethod _LOGOUTURL ($thisl)

ObjectMethod _LOGOUT ($thisl)

ObjectMethod _AUTHENTICATED ($thisl)

ObjectMethod _CANLOGIN ($thisl)

ObjectMethod _SESSION_VARIABLE ($thisl)

ObjectMethod _LOGINURL ($thisl)

ObjectMethod _dispLogon ($thisl)

PrivateMethod _skinSelect ()

Internal use only TODO: what does it do?

StaticMethod removeUserSessions()

Delete session files for a user that is being removed from the system. Removing the Session prevents any further damage from a spammer when the account has been removed.

This is a static method, but requires Foswiki::cfg. It is designed to be run from a session.