Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IAuthenticator

Timestamp:

Apr 6, 2012, 6:14:48 PM (12 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IAuthenticator

@@ +1 @@
+== Extension Point : ''IAuthenticator'' ==
+
+||'''Interface'''||''IAuthenticator''||'''Since'''||0.9||
+||'''Module'''||''trac.web''||'''Source'''||[source:trunk/trac/web/api.py api.py]||
+
+An ''IAuthenticator'' authenticates users' web requests.
+
+== Purpose ==
+
+Trac allows anonymous and authenticated users. Users are by default authenticated when they can login via basic HTTP authentication.
+
+This default authentication process can be replaced or augmented by plugins implementing IAuthenticator.
+
+== Usage ==
+
+Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
+
+The only functionality required of an IAuthenticator is to return a username for any given request (or `None` if the request can not be authenticated).
+
+Here usually things like `req.remote_addr` (the user's IP address), `req.remote_user` (the user's HTTP name) and `req.incookie` (cookies) are useful.
+
+The default implementation `trac.web.auth.LoginModule` also provides authentication cookie management with various [TracIni#trac-section options] and the ''Login'' and '' Logout'' links. To retain this functionality it can be useful to wrap or inherit from `LoginModule`.
+
+Trac calls all authenticators via `trac.web.main.RequestDispatcher.authenticate` which lazily initializes the `req.authname` property.
+
+== Examples ==
+
+The following minimal example replaces the entire login process of trac with a simple authenticator module that automatically authenticates only those requests originating from the local IP address 127.0.0.1 as the user named ''local''.
+
+{{{#!python
+from trac.core import *
+from trac.web.api import IAuthenticator
+
+class LocalAuthenticator(Component):
+
+    implements(IAuthenticator)
+
+    def authenticate(self, req):
+        if req.remote_addr == '127.0.0.1':
+            return 'local'
+        return None
+}}}
+
+== Available Implementations ==
+
+In Trac:
+* [source:trunk/trac/web/auth.py LoginModule]
+
+In third-party plugins:
+* th:AccountManagerPlugin: `acct_mgr.web_ui.LoginModule`
+ * Form-based login
+* th:HttpAuthPlugin: `httpauth.filter.HTTPAuthFilter`
+ * HTTP authentication (required for th:XmlRpcPlugin) that is compatible with th:AccountManagerPlugin
+* th:SharedCookieAuthPlugin: sharedcookieauth.sharedcookieauth.SharedCookieAuth
+ * See #8486
+* th:CaptchaAuthPlugin: `captchaauth.auth.AuthCaptcha`
+ * Captcha-based authentication
+* [https://github.com/dairiki/authopenid-plugin authopenid-plugin]: `authopenid.authopenid.AuthOpenIdPlugin`
+ * OpenID-based authentication
+
+== Additional Information and References ==
+ * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.web.auth.IAuthenticator-class.html epydoc]
+ * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_web_auth.html#trac.web.auth.IAuthenticator API Reference]
+ * Related tickets:
+  * [query:keywords~=authentication&group=status authentication in keywords]
+
+ * TracAuthenticationIntroduction
+ * TracStandalone#Authenticationfortracdbehindaproxy
+ * TracDev/TracSession
+ 
+ * Mailing list threads:
+  * [trac-dev:3839 Login name conversion]
+  * [trac-dev:6054 Common logon cookie]
+  * [trac-dev:4809 Why authenticate twice?] (!AccountManager integration)
+  * [trac-dev:2404 Replacing REMOTE_USER]