1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/authenticators.html Sat Apr 09 23:25:58 2005 +0000
1.3 @@ -0,0 +1,101 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<html xmlns="http://www.w3.org/1999/xhtml">
1.8 +<head>
1.9 + <title>Application-Wide Authenticators</title>
1.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +
1.14 +<body>
1.15 +<h1>Application-Wide Authenticators</h1>
1.16 +
1.17 +<p>Authenticators are special classes which can, in conjunction with
1.18 +mechanisms in the server environment, judge whether a user of an application
1.19 +is recognised or not. The process of using authenticators is as follows:</p>
1.20 +<ol>
1.21 + <li>Set up authentication in the server environment or framework in which
1.22 + the application is to be deployed.</li>
1.23 + <li>Introduce an authenticator class in the application.</li>
1.24 +</ol>
1.25 +
1.26 +<h2>Setting Up Authentication</h2>
1.27 +
1.28 +<p>The exact details of configuring authentication mechanisms in each server
1.29 +environment may vary substantially. For example, Apache environments require
1.30 +that <code>Auth</code> directives be specified in the Apache configuration
1.31 +files (see <code>docs/ModPython/NOTES.txt</code>); in Zope environments,
1.32 +protected folders can be defined to hold the application when deployed (see
1.33 +<code>docs/Zope/NOTES.txt</code>).</p>
1.34 +
1.35 +<h2>Defining an Authenticator</h2>
1.36 +
1.37 +<p>An authenticator must be defined within your application in order to make
1.38 +decisions about users who have presented their credentials; this
1.39 +authenticator will respond with a decision when prompted by the server or
1.40 +underlying framework, either allowing or denying access for the user whose
1.41 +identity has been presented to the server/framework.</p>
1.42 +
1.43 +<p>The code for an authenticator usually looks like this:</p>
1.44 +<pre>class MyAuthenticator:
1.45 +
1.46 + "This is an authenticator - something which decides whether a user is known to the application."
1.47 +
1.48 + def authenticate(self, trans):
1.49 + user = trans.get_user()
1.50 + [Make a decision about the validity of the user.]
1.51 + [Return a true value if the user is allowed to access the application.]
1.52 + [Return a false value if the user is not recognised or allowed to access the application.]
1.53 +
1.54 + def get_auth_type(self):
1.55 + "This method returns 'Basic' in most deployments."
1.56 + return "Basic"
1.57 +
1.58 + def get_realm(self):
1.59 + "This method returns something to distinguish this authentication mechanism from others."
1.60 + return "MyRealm"</pre>
1.61 +
1.62 +<p>In this mechanism, authenticators rely on authentication information from
1.63 +the server/framework and have a "global" effect on access to the application.
1.64 +However, it is always possible to test the user identity later on and to
1.65 +change the way an application behaves accordingly.</p>
1.66 +
1.67 +<div class="WebStack">
1.68 +<h3>WebStack API - User Identity</h3>
1.69 +
1.70 +<p>Transaction objects have the following methods for inspecting and
1.71 +redefining the identity of users:</p>
1.72 +<dl>
1.73 + <dt><code>get_user</code></dt>
1.74 + <dd>This gets the name of the user attempting to access the
1.75 + application.</dd>
1.76 + <dt><code>set_user</code></dt>
1.77 + <dd>This sets the name of the user, thus affecting subsequent calls to
1.78 + <code>get_user</code>, allowing certain parts of an application to view
1.79 + users according to other criteria than their basic username - for
1.80 + example, one might use <code>set_user</code> to redefine each user's
1.81 + identity in terms of the role that user may have in an application.</dd>
1.82 +</dl>
1.83 +</div>
1.84 +
1.85 +<h2>Introducing an Authenticator</h2>
1.86 +
1.87 +<p>Authenticator objects are created in the adapter code - see <a
1.88 +href="writing-adapters.html">"Writing Adapters"</a> for more information.</p>
1.89 +
1.90 +<h2>Anonymous Access</h2>
1.91 +
1.92 +<p>With application-wide authenticators, anonymous access to resources and
1.93 +applications can be difficult to permit alongside access by specific users,
1.94 +mostly because servers and frameworks which employ HTTP authentication
1.95 +schemes do so globally for a given application.</p>
1.96 +
1.97 +<h2>Logout Functions</h2>
1.98 +
1.99 +<p>With application-wide authenticators, a logout function may not be
1.100 +available if the server/framework has been configured to use HTTP
1.101 +authentication schemes, mainly because no logout mechanism generally exists
1.102 +for such schemes.</p>
1.103 +</body>
1.104 +</html>