← Back to branch summary

~ubuntu-branches/ubuntu/natty/moin/natty-updates

« back to all changes in this revision

Viewing changes to wiki/underlay/pages/HelpOnAuthentication/revisions/00000001

  • Committer: Bazaar Package Importer
  • Author(s): Jonas Smedegaard
  • Date: 2008-06-22 21:17:13 UTC
  • mfrom: (0.9.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20080622211713-fpo2zrq3s5dfecxg
Tags: 1.7.0-3
Simplify /etc/moin/wikilist format: "USER URL" (drop unneeded middle
CONFIG_DIR that was wrongly advertised as DATA_DIR).  Make
moin-mass-migrate handle both formats and warn about deprecation of
the old one.

Show diffs side-by-side

added added

removed removed

Lines of Context:
wiki/underlay/pages/HelpOnAuthentication/revisions/00000001
1
 
## Please edit system and help pages ONLY in the moinmaster wiki! For more
2
 
## information, please see MoinMaster:MoinPagesEditorGroup.
 
1
## Please edit system and help pages ONLY in the master wiki!
 
2
## For more information, please see MoinMoin:MoinDev/Translation.
3
3
##master-page:Unknown-Page
4
4
##master-date:Unknown-Date
5
 
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
 
5
#acl -All:write Default
6
6
#format wiki
7
7
#language en
8
8
= How Authentication works with MoinMoin =
9
9
 
10
 
MoinMoin historically has used some cookie-based authentication: you log in via the form on page UserPreferences, moin sets a cookie and from then on this cookie is used for authenticating you - until you log off and the cookie gets deleted (or until the cookie expires). 
11
 
 
12
 
For running moin in corporate environments this is often no option as access restrictions have to be enforced reliably. Starting with 1.3 moin could also use HTTP basic auth based authentication, when being run with some web servers (like Apache) supporting it. 
13
 
 
14
 
Starting with 1.5 moin now has freely configurable and kind of modular authentication. You use the `auth` configuration value to set up a list of authentication methods that are processed in exactly that order.
15
 
 
16
 
When an external user database is used you do not want to recreate all users in moin. For this case the configuration option `user_autocreate` was added to moin 1.5. If you set it to True a new user profile will be created automatically when a new user has passed authentication (and the auth method supports auto creation).
17
 
 
18
 
Presently the following authentication methods are supported:
19
 
 
20
 
 || '''Server setup''' || '''Authentication''' || '''Auth method in moin''' ||
21
 
 ||<|2 (> All || by moin via own cookie || `MoinMoin.auth.moin_cookie` ||
22
 
 || by moin via external cookie || see contrib/auth_externalcookie/ ||
23
 
 ||<|2 (> Apache with CGI, modpy or Fast``Cgi || by Apache modules: HTTP Basic, HTTP Digest, SSPI (aka NTLM) or LDAP || `MoinMoin.auth.http` ||
24
 
 || by moin via LDAP || `MoinMoin.auth.ldap_login` (must combine with moin_cookie to keep the session) ||
25
 
 || Apache+SSL with CGI, modpy or Fast``Cgi || by Apache via SSL client certificate || `MoinMoin.auth.sslclientcert` ||
26
 
 || Twisted || HTTP Basic (but does not request authentication by header, so this is currently only useful for automated stuff, not for browser use) || `MoinMoin.auth.http` ||
27
 
 || IIS || (?) || (?) ||
28
 
 
29
 
== Other "auth" methods ==
30
 
These are not strictly auth methods, as they don't authenticate users, but use auth information for other purposes:
31
 
 
32
 
 || `MoinMoin.auth.log` || will just log login/logout/name, nothing else ||
33
 
 || `MoinMoin.auth.smb_mount` || mount some smb share using user/password from login, umount on logout ||
34
 
 
35
 
`MoinMoin.auth.interwiki` is unfinished, experimental code - don't use.
 
10
MoinMoin historically has supported only username/password authentication and cookie-based sessions: you log in via the login form, moin sets a cookie and from then on this cookie is used for authenticating you - until you log off and the cookie gets deleted (or until the cookie expires). 
 
11
 
 
12
In many environments this is often not optimal as access restrictions should be based on other user databases like LDAP (Active Directory). Hence, modular authentication was developed for !MoinMoin. You use the `auth` configuration value to set up a list of authenticators that are processed in exactly that order.
 
13
 
 
14
When an external user database is used you do not want to recreate all users in moin. For this case the configuration option `user_autocreate` was added. If you set it to True a new user profile will be created automatically when a new user has passed authentication (and the authenticator supports auto creation).
 
15
 
 
16
Presently the following authenticators are supported:
 
17
 
 
18
 || '''Server setup''' || '''Authentication''' || '''Authenticator class in moin''' ||
 
19
 ||<|5 (> All || by moin via username/password || `MoinMoin.auth.MoinAuth` ||
 
20
 || by PHP session || `MoinMoin.auth.php_session.PHPSessionAuth` ||
 
21
 || by moin via external cookie || see `contrib/auth_externalcookie/` and HelpOnAuthentication/ExternalCookie||
 
22
 || by [[http://openid.net|OpenID]] || `MoinMoin.auth.openidrp.OpenIDAuth` ||
 
23
 || OpenID verification by http://botbouncer.com/ || `MoinMoin.auth.botbouncer.BotBouncer` ||
 
24
 ||<|2 (> Apache with CGI, modpy or Fast``Cgi || by Apache modules: HTTP Basic, HTTP Digest, SSPI (aka NTLM) or LDAP || `MoinMoin.auth.http.HTTPAuth` ||
 
25
 || by moin via LDAP || `MoinMoin.auth.ldap_login.LDAPAuth` ||
 
26
 || by moin via a remote moin wiki || `MoinMoin.auth.interwiki` - still experimental ||
 
27
 || Apache+SSL with CGI, modpy or Fast``Cgi || by Apache via SSL client certificate || `MoinMoin.auth.sslclientcert.SSLClientCertAuth` ||
 
28
 || Twisted || HTTP Basic (but does not request authentication by header, so this is currently only useful for automated stuff, not for browser use; uses Moin's internal user database but on its own does not allow signing up, hence only useful together with Moin``Auth) || `MoinMoin.auth.http.HTTPAuth` ||
 
29
 || IIS || HTTP Basic, SSPI (aka NTLM), (?) || `MoinMoin.auth.http.HTTPAuth`, (?) ||
 
30
 
 
31
== Other pseudo-authenticators ==
 
32
These are not strictly authenticators, as they don't authenticate users, but use auth information for other purposes:
 
33
 
 
34
 || `MoinMoin.auth.log.AuthLog` || will just log login/logout/request, nothing else ||
 
35
 || `MoinMoin.auth.smb_mount.SMBMount` || mount some smb share using user/password from login, umount on logout ||
 
36
 
36
37
 
37
38
== Shipped plugins ==
38
 
=== moin_cookie auth (default) ===
 
39
=== MoinAuth (default) ===
 
40
This is the default auth list moin uses (so if you just want that, you don't need to configure it).
 
41
 
39
42
{{{#!python
40
 
    from MoinMoin.auth import moin_cookie
41
 
    auth = [moin_cookie]
 
43
    from MoinMoin.auth import MoinAuth
 
44
    auth = [MoinAuth()]
42
45
}}}
43
46
 
44
 
This is the default auth list moin uses (so if you just want that, you don't need to configure it). It means that moin just tries to use the MOIN_ID cookie as it ever did.
45
 
 
46
 
For doing that, moin will just call the `MoinMoin.auth.moin_cookie` function. This function will look if there is a valid cookie:
47
 
 * if yes, it will use it to make and return a valid user object. The user is known now.
48
 
 * if no, the function does not return a user object. As as moin_cookie is the only auth method in the list, there is no other auth method to try and the user will stay unknown for that case.
49
 
 
50
 
=== http auth ===
 
47
=== HTTP authentication ===
51
48
 
52
49
To activate http authentication you have to add following lines to `wikiconfig.py`:
53
50
{{{#!python
54
 
    from MoinMoin.auth import http
55
 
    auth = [http]
 
51
    from MoinMoin.auth.http import HTTPAuth
 
52
    auth = [HTTPAuth()]
56
53
}}}
57
54
 
58
55
For HTTP basic auth used with a web server like Apache, the web server handles authentication before moin gets called. You either enter a valid username and password or your access will be denied by the web server.
59
56
 
60
 
So moin's http auth method will just check if user authentication happened:
61
 
 * if yes, it will return a user object based on the authenticated user name.
62
 
 * if no, it will not return a user object. In this example, there are no other auth methods, so the user will stay unknown.
63
 
 
64
 
Well, in reality, it is a bit more complicated indeed:
65
 
 * For Twisted we use the username and password stored in the moin user profile. Except wiki xmlrpc usage this is currently not used.
66
 
 * For NTLM and Negotiate, we split off everything before the last "\" (usually it is "Domain\username") and we also use title() to normalize "username" to "Username".
67
 
 
68
 
 (!) You usually do want to set `user_autocreate = True` for this auth method. moin will then auto create a user profile if the authenticated user does not already have one. So the user does not need to create the moin profile himself.
69
 
 
70
 
=== sslclientcert auth ===
 
57
Moin's HTTP authenticator will just check if user authentication happened and allow access if it has and a valid user is found for the given username.
 
58
 
 
59
Unfortunately, it is a bit more complicated:
 
60
 * For Twisted servers the authenticator uses the username and password stored in the moin user profile and allows users to change them both.
 
61
 * For NTLM and Negotiate, it splits off everything before the last backslash ("\") (usually it is "Domain\username") and we also use `title()` to normalize "username" to "Username".
 
62
 * The `user_autocreate` configuration value should be set to True for this authenticator to allow it to create new user profiles for authenticated users that do not have a profile yet.
 
63
 * See also HelpOnInstalling/ApacheOnWin32withDomainAuthentication for some win32-specific instructions.
 
64
 
 
65
=== SSL client certification authentication ===
71
66
To activate authentication via SSL client certificates you have to add following lines to `wikiconfig.py`:
72
67
{{{#!python
73
 
    from MoinMoin.auth import sslclientcert
74
 
    auth = [sslclientcert]
 
68
    from MoinMoin.auth.sslclientcert import SSLClientCertAuth
 
69
    auth = [SSLClientCertAuth()]
75
70
}}}
76
71
 
77
 
For SSL client certificate auth used with a web server like Apache, the web server handles authentication before moin gets called. You either have a valid SSL client certificate or your access will be denied by the web server.
78
 
 
79
 
So moin's sslclientcert auth method will just check if user authentication happened:
80
 
 * if yes, it will return a user object based on the email address or user name in the certificate.
81
 
 * if no, it will not return a user object. In this example, there are no other auth methods, so the user will stay unknown.
82
 
 
83
 
 (!) You usually do want to set `user_autocreate = True` for this auth method. moin will then auto create a user profile if the authenticated user does not already have one. So the user does not need to create the moin profile himself.
84
 
 
85
 
=== php_auth ===
 
72
SSL client certification authentication must be used with a web server like Apache that handles the SSL bits and just presents a few environment variables to Moin.
 
73
 
 
74
The SSLClientCertAuth authenticator has a few parameters that you pass to the constructor (example below):
 
75
|| '''Parameter''' || '''Default''' || '''Meaning''' ||
 
76
|| `authorities` || None || a list of authorities that are accepted, or None to accept all ||
 
77
|| `email_key` || True || indicates whether the email in the certificate should be used to find the Moin user ||
 
78
|| `name_key` || True || indiciates whether the name in the certificate should be used to find the Moin user ||
 
79
|| `use_email` || False || if set to True, the account email cannot be changed and is forced to the one given in the certificate ||
 
80
|| `use_name` || False || if set to True, the account name cannot be changed and is forced to the one given in the certificate ||
 
81
 
 
82
For example, to accept only certificates that Apache has verified and that are signed by a certain authority, use:
 
83
{{{#!python
 
84
    from MoinMoin.auth.sslclientcert import SSLClientCertAuth
 
85
    auth = [SSLClientCertAuth(authorities=['my.authority.tld'])]
 
86
}}} or similar.
 
87
 
 
88
 (!) You usually want to set `user_autocreate = True` in the configuration if you use this authenticator. Moin will then automatically create a user profile if the authenticated user does not already have one.
 
89
 
 
90
=== PHP session ===
86
91
To activate Single-Sign-On integration with PHP applications, use this module. It reads PHP session files and therefore directly integrates with existing PHP authentication systems.
87
92
 
88
93
To use this module, use the following lines of code in your configuration:
89
94
{{{#!python
90
 
    from MoinMoin.auth import php_auth
91
 
    auth = [php_auth()]
 
95
    from MoinMoin.auth.php_session import PHPSessionAuth
 
96
    auth = [PHPSessionAuth()]
92
97
}}}
93
 
php_auth has the following parameters: {{{#!python
94
 
php_auth(apps=['egw'], s_path="/tmp", s_prefix="sess_")
 
98
 
 
99
PHPSessionAuth has the following parameters: {{{#!python
 
100
    PHPSessionAuth(apps=['egw'], s_path="/tmp", s_prefix="sess_")
95
101
}}}
96
102
 * `apps` is a list of enabled applications
97
103
 * `s_path` is the path of the PHP session files
98
104
 * `s_prefix` is the prefix of the PHP session files
99
105
 
100
 
The only supported PHP application is eGroupware 1.2 currently. But it should be fairly easy to add a few lines of code that extract the necessary information from the PHP session.
101
 
 
102
 
== Combining multiple auth methods ==
103
 
For combining e.g. http and cookie authentication, your `wikiconfig.py` might contain:
104
 
{{{#!python
105
 
    from MoinMoin.auth import http, moin_cookie
106
 
    auth = [http, moin_cookie]
107
 
}}}
108
 
 
109
 
In this example, moin will first check if the http auth method gives a valid user. If yes, it will use just that. If not and `continue_flag` returned by http auth method is True, it will continue checking other auth list method - `moin_cookie` in this case... ( /!\ needs update /!\ )
110
 
 
111
 
 (!) Not all combinations make sense, of course.
112
 
 
113
 
== Making your own auth method ==
114
 
See the commented config file fragment `contrib/auth_externalcookie/` and `MoinMoin/auth.py` in your moin distribution archive for examples of how to do authentication.
115
 
 
116
 
Here is just a short summary of what's currently possible:
117
 
 * use UserPreferences login form as userinterface for your own auth method for entering name and password
 
106
The only supported PHP application is eGroupware 1.2 currently. But it should be fairly easy to add a few lines of code that extract the necessary information from the PHP session, if you do that, please open a feature request with a patch.
 
107
 
 
108
=== OpenID (with BotBouncer) ===
 
109
The OpenID authentication plugin allows users to sign in using their OpenID and connect that OpenID to a new or existing Moin account. To allow users to sign in with OpenID, add the plugin to the auth list, or to require OpenID with http://botbouncer.com/ verification use:
 
110
{{{#!python
 
111
    from MoinMoin.auth.openidrp import OpenIDAuth
 
112
    from MoinMoin.auth.botbouncer import BotBouncer
 
113
    auth = [OpenIDAuth(), BotBouncer("your-botbouncer-API-key")]
 
114
}}}
 
115
 
 
116
OpenID authentication requires anonymous sessions, set `anonymous_session_lifetime` to anything bigger than zero. See HelpOnConfiguration for more details on the value. For OpenID, very little time should be sufficient.
 
117
 
 
118
==== Advanced OpenID RP configuration ====
 
119
 
 
120
The OpenID RP code can also be configured for two use cases:
 
121
 1. You can force a specific provider to be used, there are two ways to achieve this:
 
122
  * Simply configure the `OpenIDAuth` authenticator like this: {{{
 
123
auth = OpenIDAuth(forced_service='http://myopenid.com/')
 
124
}}}
 
125
  * Create an `OpenIDServiceEndpoint` object and use that for the `forced_service` parameter: {{{
 
126
fs = OpenIDServiceEndpoint()
 
127
fs.type_uris = OPENID_2_0_TYPE
 
128
fs.server_url = 'http://localhost:8000/openidserver'
 
129
fs.claimed_id = 'http://specs.openid.net/auth/2.0/identifier_select'
 
130
 
 
131
auth = OpenIDAuth(forced_service=fs)
 
132
}}}
 
133
 In the latter case, no discovery needs to be done.
 
134
 
 
135
 2. You can specify functions to be called in various steps of the OpenID authentication process to, for example, implement Attribute Exchange. For now, this is not documented here, you'll have to look at the file `MoinMoin/auth/openidrp.py`.
 
136
 
 
137
=== LDAP based user authentication ===
 
138
 
 
139
The LDAP authenticator of MoinMoin enables single-sign-on (SSO) - assuming you already have a LDAP directory with your users, passwords, email adresses. On Linux this could be some OpenLDAP server, on a Windows server (usually the domain controller) this is called "Active Directory" (short: AD).
 
140
 
 
141
It works like this:
 
142
 * User enters his name and password via moin's login action and clicks on the login button.
 
143
 * On login, ldap_login.LDAPAuth checks username/password against LDAP.
 
144
  * If username/password is ok for LDAP, it creates or updates a user profile with values from ldap (name, alias, email) and creates a user object in the !MoinMoin process, then it hands over to the next authenticator...
 
145
  * If username/password is not ok for LDAP, it vetoes and aborts the login (no other authenticators checked).
 
146
 * If the login was successful, moin establishes a session for that user.
 
147
 
 
148
==== LDAP auth installation / configuration ====
 
149
You need to install python-ldap module (and everything it depends on, see its documentation).
 
150
 
 
151
You need an LDAP or AD server. :)
 
152
 
 
153
See `wiki/config/more_samples/ldap_wikiconfig_snippet.py` in your moin dist archive for a snippet you can use in your wiki config.
 
154
 
 
155
(!) Please also read the `README` file in that directory.
 
156
 
 
157
==== LDAP auth Problems? ====
 
158
!MoinMoin support does not know your LDAP server setup, so please follow these steps before asking for help:
 
159
 * Configure DEBUG logging for `MoinMoin.auth.ldap_login` and look into the log output.
 
160
 * Verify your settings and your user/password by e.g. using ldapsearch to query your LDAP server.
 
161
  * /!\ As long as you don't manage talking to your LDAP server with such a tool, you don't need to try with !MoinMoin.
 
162
 * Ask the administrator of your LDAP/AD server for help / for correct settings.
 
163
 * Maybe look into `MoinMoin/auth/ldap_login.py`, if you can debug or fix your problem there.
 
164
 
 
165
/!\ Only ask !MoinMoin support if you successfully used ldapsearch (or some similar tool) and you double checked your wiki config and it does still not work with moin.
 
166
 
 
167
=== XMLRPC auth ===
 
168
 
 
169
{{{#!python
 
170
import xmlrpclib
 
171
 
 
172
name = "TestUser"
 
173
password = "secret"
 
174
wikiurl = "http://localhost:8080/"
 
175
 
 
176
homewiki = xmlrpclib.ServerProxy(wikiurl + "?action=xmlrpc2", allow_none=True)
 
177
auth_token = homewiki.getAuthToken(name, password)
 
178
 
 
179
mc = xmlrpclib.MultiCall(homewiki)
 
180
mc.applyAuthToken(auth_token)
 
181
# you can add more xmlrpc method calls to the multicall here,
 
182
# they will run authenticated as user <name>.
 
183
result = mc()
 
184
}}}
 
185
 
 
186
== Combining multiple authenticators ==
 
187
For combining e.g. SSL client certificate and username/password authentication, your `wikiconfig.py` might contain:
 
188
{{{#!python
 
189
    from MoinMoin.auth import MoinAuth
 
190
    from MoinMoin.auth.sslclientcert import SSLClientCertAuth
 
191
    auth = [SSLClientCertAuth(), MoinAuth()]
 
192
}}}
 
193
 
 
194
In that case, any client certificates that the user provides will be used to log him on, but if they do not provide one they still have the option of logging on with their username/password.
 
195
 
 
196
== Writing your own authenticator ==
 
197
See the commented config file fragment `contrib/auth_externalcookie/` and `MoinMoin/auth/*.py` in your moin distribution archive for examples of how to do authentication. Also, the docstring in `MoinMoin/auth/__init__.py` contains an explanation of what can be done and how it is achieved.
 
198
 
 
199
Authenticators can
 
200
 * use the regular login form as their user interface for entering name and password
 
201
 * use the regular logout action for logging out
 
202
 * prohibit logging out (like SSL client certificate authentication that checks for every request)
118
203
 * search existing user profiles for a "matching" user (the match needs not be the name, it can also be the email address or something you put into aliasname)
119
 
 * create a user object and let it remember what attributes were determined by auth method (and thus should not be offered on UserPreferences)
 
204
 * create a user object and let it remember what attributes were determined by authenticator (and thus should not be offered on user preferences)
120
205
 * update values in user's profile from externally provided data
121
206
 * autocreate user profiles