(no commit message)

[openafs-wiki.git] / TWiki / TWikiLoginManagerDotPm.mdwn

# <a name="Package &lt;code&gt;TWiki::_LoginManager="></a> Package =TWiki::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](http://www.dementia.org/twiki/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/TWiki/LoginManager` directory.

The class has extensive tracing, which is enabled by $TWiki::cfg\{Trace\}\{LoginManager.pm\}. 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 TWiki::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 TWiki::new, loginManager-&gt;loadSession is called.

1. Calls loginManager-&gt;getUser to get the username **before** the session is created
  - TWiki::LoginManager::ApacheLogin looks at REMOTE\_USER (only for authenticated scripts)
  - TWiki::LoginManager::TemplateLogin just returns undef
2. reads the TWIKISID cookie to get the SID (or the TWIKISID parameters in the CGI query if cookies aren't available, or [[IP2SID]] mapping if that's enabled).
3. Creates the CGI::Session object, and the session is thereby read.
4. If the username still isn't known, reads it from the cookie. Thus TWiki::LoginManager::ApacheLogin overrides the cookie using REMOTE\_USER, and TWiki::LoginManager::TemplateLogin **always** uses the session.

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

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

## <a name="ObjectData &lt;code&gt;twiki="></a> [[ObjectData]] =twiki

The TWiki object this login manager is attached to.

<div>
  <ul>
    <li><a href="#Package =TWiki::_LoginManager="> Package TWiki::LoginManager</a><ul>
        <li><a href="#ObjectData =twiki="> ObjectData twiki</a></li>
        <li><a href="#StaticMethod *make_LoginManager*"> StaticMethod makeLoginManager <tt>($twiki) -&gt; $TWiki::LoginManager</tt></a></li>
        <li><a href="#ClassMethod <strong>new</strong> ($session,$imp"> ClassMethod new <tt>($session,$impl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
        <li><a href="#ClassMethod <strong>_real_trace</strong> ($sess"> ClassMethod _real_trace <tt>($session,$impl)</tt></a></li>
        <li><a href="#ClassMethod <strong>_IP2SID</strong> ($session,"> ClassMethod _IP2SID <tt>($session,$impl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>loadSession</strong> ($def"> ObjectMethod loadSession <tt>($defaultUser) -&gt; $login</tt></a></li>
        <li><a href="#ObjectMethod <strong>checkAccess</strong> ()"> ObjectMethod checkAccess <tt>()</tt></a></li>
        <li><a href="#ObjectMethod <strong>complete</strong> ()"> ObjectMethod complete <tt>()</tt></a></li>
        <li><a href="#StaticMethod *expire_DeadSession"> StaticMethod expireDeadSessions <tt>()</tt></a></li>
        <li><a href="#ObjectMethod <strong>user_LoggedIn</strong> ($l"> ObjectMethod userLoggedIn <tt>($login,$wikiname)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_my_ScriptURLRE</strong> ("> ObjectMethod _myScriptURLRE <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_rewriteURL</strong> ($thi"> ObjectMethod _rewriteURL <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_rewriteFORM</strong> ($th"> ObjectMethod _rewriteFORM <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod *end_RenderingHandl"> ObjectMethod endRenderingHandler <tt>()</tt></a></li>
        <li><a href="#ObjectMethod <strong>_pushCookie</strong> ($thi"> ObjectMethod _pushCookie <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>addCookie</strong> ($c)"> ObjectMethod addCookie <tt>($c)</tt></a></li>
        <li><a href="#ObjectMethod <strong>modifyHeader</strong> (\%h"> ObjectMethod modifyHeader <tt>(\%header)</tt></a></li>
        <li><a href="#ObjectMethod *redirect_CgiQuery*"> ObjectMethod redirectCgiQuery <tt>($url)</tt></a></li>
        <li><a href="#ObjectMethod *get_SessionValues*"> ObjectMethod getSessionValues <tt>() -&gt; \%values</tt></a></li>
        <li><a href="#ObjectMethod *get_SessionValue*"> ObjectMethod getSessionValue <tt>($name) -&gt; $value</tt></a></li>
        <li><a href="#ObjectMethod *set_SessionValue*"> ObjectMethod setSessionValue <tt>($name,$value)</tt></a></li>
        <li><a href="#ObjectMethod *clear_SessionValue"> ObjectMethod clearSessionValue <tt>($name) -&gt; $boolean</tt></a></li>
        <li><a href="#ObjectMethod *forceAuthenticatio"> ObjectMethod forceAuthentication <tt>() -&gt; boolean</tt></a></li>
        <li><a href="#ObjectMethod <strong>loginUrl</strong> (...) ->"> ObjectMethod loginUrl <tt>(...) -&gt; $url</tt></a></li>
        <li><a href="#ObjectMethod <strong>getUser</strong> ()"> ObjectMethod getUser <tt>()</tt></a></li>
        <li><a href="#ObjectMethod <strong>_LOGIN</strong> ($thisl)"> ObjectMethod _LOGIN <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_LOGOUTURL</strong> ($this"> ObjectMethod _LOGOUTURL <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_LOGOUT</strong> ($thisl)"> ObjectMethod _LOGOUT <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_AUTHENTICATED</strong> ($"> ObjectMethod _AUTHENTICATED <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_CANLOGIN</strong> ($thisl"> ObjectMethod _CANLOGIN <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod *_SESSION_VARIABLE*"> ObjectMethod _SESSION_VARIABLE <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_LOGINURL</strong> ($thisl"> ObjectMethod _LOGINURL <tt>($thisl)</tt></a></li>
        <li><a href="#ObjectMethod <strong>_dispLogon</strong> ($this"> ObjectMethod _dispLogon <tt>($thisl)</tt></a></li>
        <li><a href="#PrivateMethod _skinSelect ()"> PrivateMethod _skinSelect ()</a></li>
      </ul>
    </li>
  </ul>
</div>

## <a name="StaticMethod &lt;strong&gt;make_LoginManager*"></a> [[StaticMethod]] \*makeLoginManager `($twiki) -> $TWiki::LoginManager`

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

## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$imp"></a> [[ClassMethod]] **new** `($session,$impl)`

Construct the user management object

## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`

Break circular references.

## <a name="ClassMethod &lt;strong&gt;_real_trace&lt;/strong&gt; ($sess"></a> [[ClassMethod]] **\_real\_trace** `($session,$impl)`

Construct the user management object

## <a name="ClassMethod &lt;strong&gt;_IP2SID&lt;/strong&gt; ($session,"></a> [[ClassMethod]] **\_IP2SID** `($session,$impl)`

read/write IP to SID map, return SID

## <a name="ObjectMethod &lt;strong&gt;loadSession&lt;/strong&gt; ($def"></a> [[ObjectMethod]] **loadSession** `($defaultUser) -> $login`

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

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

## <a name="ObjectMethod &lt;strong&gt;checkAccess&lt;/strong&gt; ()"></a> [[ObjectMethod]] **checkAccess** `()`

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

## <a name="ObjectMethod &lt;strong&gt;complete&lt;/strong&gt; ()"></a> [[ObjectMethod]] **complete** `()`

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

## <a name="StaticMethod &lt;strong&gt;expire_DeadSession"></a> [[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 TWiki::cfg. It is designed to be run from a session or from a cron job.

## <a name="ObjectMethod &lt;strong&gt;user_LoggedIn&lt;/strong&gt; ($l"></a> [[ObjectMethod]] **userLoggedIn** `($login,$wikiname)`

Called when the user is known. It's invoked from TWiki::UI::Register::finish for instance,

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)

- `$login` - string login name
- `$wikiname` - string wikiname

## <a name="ObjectMethod &lt;strong&gt;_my_ScriptURLRE&lt;/strong&gt; ("></a> [[ObjectMethod]] **\_myScriptURLRE** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_rewriteURL&lt;/strong&gt; ($thi"></a> [[ObjectMethod]] **\_rewriteURL** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_rewriteFORM&lt;/strong&gt; ($th"></a> [[ObjectMethod]] **\_rewriteFORM** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;end_RenderingHandl"></a> [[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.

## <a name="ObjectMethod &lt;strong&gt;_pushCookie&lt;/strong&gt; ($thi"></a> [[ObjectMethod]] **\_pushCookie** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;addCookie&lt;/strong&gt; ($c)"></a> [[ObjectMethod]] **addCookie** `($c)`

Add a cookie to the list of cookies for this session.

- `$c` - a CGI::Cookie

## <a name="ObjectMethod &lt;strong&gt;modifyHeader&lt;/strong&gt; (\%h"></a> [[ObjectMethod]] **modifyHeader** `(\%header)`

Modify a HTTP header

- `\%header` - header entries

## <a name="ObjectMethod &lt;strong&gt;redirect_CgiQuery*"></a> [[ObjectMethod]] \*redirectCgiQuery `($url)`

Generate an HTTP redirect on STDOUT, if you can. Return 1 if you did.

- `$url` - target of the redirection.

## <a name="ObjectMethod &lt;strong&gt;get_SessionValues*"></a> [[ObjectMethod]] \*getSessionValues `() -> \%values`

Get a name-&gt;value hash of all the defined session variables

## <a name="ObjectMethod &lt;strong&gt;get_SessionValue*"></a><a name="ObjectMethod *get_SessionValue&lt;/strong&gt; "></a> [[ObjectMethod]] **getSessionValue** `($name) -> $value`

Get the value of a session variable.

## <a name="ObjectMethod &lt;strong&gt;set_SessionValue*"></a><a name="ObjectMethod *set_SessionValue&lt;/strong&gt; "></a> [[ObjectMethod]] **setSessionValue** `($name,$value)`

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

## <a name="ObjectMethod &lt;strong&gt;clear_SessionValue"></a> [[ObjectMethod]] \*clearSessionValue `($name) -> $boolean`

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

## <a name="ObjectMethod &lt;strong&gt;forceAuthenticatio"></a> [[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.

## <a name="ObjectMethod &lt;strong&gt;loginUrl&lt;/strong&gt; (...) -"></a><a name="ObjectMethod &lt;strong&gt;loginUrl&lt;/strong&gt; (...) - "></a> [[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 TWiki::getScriptUrl()

## <a name="ObjectMethod &lt;strong&gt;getUser&lt;/strong&gt; ()"></a> [[ObjectMethod]] **getUser** `()`

**VIRTUAL METHOD** 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.

## <a name="ObjectMethod &lt;strong&gt;_LOGIN&lt;/strong&gt; ($thisl)"></a> [[ObjectMethod]] **\_LOGIN** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_LOGOUTURL&lt;/strong&gt; ($this"></a> [[ObjectMethod]] **\_LOGOUTURL** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_LOGOUT&lt;/strong&gt; ($thisl)"></a> [[ObjectMethod]] **\_LOGOUT** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_AUTHENTICATED&lt;/strong&gt; ($"></a> [[ObjectMethod]] **\_AUTHENTICATED** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_CANLOGIN&lt;/strong&gt; ($thisl"></a> [[ObjectMethod]] **\_CANLOGIN** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_SESSION_VARIABLE*"></a> [[ObjectMethod]] \*\_SESSION\_VARIABLE `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_LOGINURL&lt;/strong&gt; ($thisl"></a> [[ObjectMethod]] **\_LOGINURL** `($thisl)`

## <a name="ObjectMethod &lt;strong&gt;_dispLogon&lt;/strong&gt; ($this"></a> [[ObjectMethod]] **\_dispLogon** `($thisl)`

## <a name="PrivateMethod _skinSelect ()"></a> [[PrivateMethod]] \_skinSelect ()

Internal use only TODO: what does it do?