== 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]