← Back to branch summary

~certify-web-dev/twisted/certify-trunk

« back to all changes in this revision

Viewing changes to doc/howto/cred.html

  • Committer: Bazaar Package Importer
  • Author(s): Free Ekanayaka
  • Date: 2010-03-09 13:32:00 UTC
  • mfrom: (2.2.6 sid)
  • Revision ID: james.westby@ubuntu.com-20100309133200-xs2rrzwnn9k86sbx
Tags: 10.0.0-2
* Include changes from 9.0.0-2 which got skipped
* python-twisted depends on version >= 10.0 of other packages

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/howto/cred.html
1
 
<?xml version="1.0" encoding="utf-8"?>
2
 
<!DOCTYPE html
3
 
  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'
4
 
  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
5
 
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
 
1
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
6
2
  <head>
7
3
<title>Twisted Documentation: Cred: Pluggable Authentication</title>
8
4
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
35
31
<p>To sketch out how this works - a <q>Realm</q> corresponds to an application
36
32
domain and is in charge of avatars, which are network-accessible business logic
37
33
objects.  To connect this to an authentication database, a top-level object
38
 
called a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.Portal.html" title="twisted.cred.portal.Portal">Portal</a></code> stores a
 
34
called a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.Portal.html" title="twisted.cred.portal.Portal">Portal</a></code> stores a
39
35
realm, and a number of credential checkers.  Something that wishes to log in,
40
 
such as a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">Protocol</a></code>,
 
36
such as a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.protocol.Protocol.html" title="twisted.internet.protocol.Protocol">Protocol</a></code>,
41
37
stores a reference to the portal. Login consists of passing credentials and a
42
 
request interface (e.g. POP3's <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.protocols.pop3.IMailbox.html" title="twisted.protocols.pop3.IMailbox">IMailbox</a></code>) to the portal. The portal passes
 
38
request interface (e.g. POP3's <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.protocols.pop3.IMailbox.html" title="twisted.protocols.pop3.IMailbox">IMailbox</a></code>) to the portal. The portal passes
43
39
the credentials to the appropriate credential checker, which returns an avatar
44
40
ID. The ID is passed to the realm, which returns the appropriate avatar.  For a
45
41
Portal that has a realm that creates mailbox objects and a credential checker
59
55
<p>This is the the core of login, the point of integration between all the objects
60
56
in the cred system.  There is one
61
57
concrete implementation of Portal, and no interface - it does a very
62
 
simple task.  A <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.Portal.html" title="twisted.cred.portal.Portal">Portal</a></code>
 
58
simple task.  A <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.Portal.html" title="twisted.cred.portal.Portal">Portal</a></code>
63
59
associates one (1) Realm with a collection of
64
60
CredentialChecker instances.  (More on those later.)</p>
65
61
 
68
64
This has only 2 methods -</p>
69
65
 
70
66
<ul>
71
 
<li><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.Portal.login.html" title="twisted.cred.portal.Portal.login">login</a></code><code>(credentials, mind, *interfaces)</code>
 
67
<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.Portal.login.html" title="twisted.cred.portal.Portal.login">login</a></code><code>(credentials, mind, *interfaces)</code>
72
68
 
73
 
<p>The docstring is quite expansive (see <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.html" title="twisted.cred.portal">twisted.cred.portal</a></code>), but in
 
69
<p>The docstring is quite expansive (see <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.html" title="twisted.cred.portal">twisted.cred.portal</a></code>), but in
74
70
brief, this is what you call when you need to call in order to connect
75
71
a user to the system.  Typically you only pass in one interface, and the mind is
76
72
<code class="python">None</code>. The interfaces are the possible interfaces the returned
86
82
<p>The logout method has to be called when the avatar is logged out. For POP3 this means
87
83
when the protocol is disconnected or logged out, etc..</p>
88
84
</li>
89
 
<li><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.Portal.registerChecker.html" title="twisted.cred.portal.Portal.registerChecker">registerChecker</a></code><code>(checker, *credentialInterfaces)</code>
 
85
<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.Portal.registerChecker.html" title="twisted.cred.portal.Portal.registerChecker">registerChecker</a></code><code>(checker, *credentialInterfaces)</code>
90
86
 
91
87
<p>which adds a CredentialChecker to the portal. The optional list of interfaces are interfaces of credentials
92
88
that the checker is able to check.</p>
94
90
 
95
91
    <h3>The CredentialChecker<a name="auto3"/></h3>
96
92
 
97
 
<p>This is an object implementing <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.checkers.ICredentialsChecker.html" title="twisted.cred.checkers.ICredentialsChecker">ICredentialsChecker</a></code> which resolves some
 
93
<p>This is an object implementing <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.checkers.ICredentialsChecker.html" title="twisted.cred.checkers.ICredentialsChecker">ICredentialsChecker</a></code> which resolves some
98
94
credentials to an avatar ID.
99
95
 
100
96
Whether the credentials are stored in an in-memory data structure, an
114
110
checker mechanisms soon.</p>
115
111
 
116
112
<p>A credential checker should raise an error if it cannot authenticate
117
 
the user, and return <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.checkers.ANONYMOUS.html" title="twisted.cred.checkers.ANONYMOUS">twisted.cred.checkers.ANONYMOUS</a></code>
 
113
the user, and return <code>twisted.cred.checkers.ANONYMOUS</code>
118
114
for anonymous access.</p>
119
115
 
120
116
    <h3>The Credentials<a name="auto4"/></h3>
126
122
several method calls in order to determine a result.</p>
127
123
 
128
124
<p>Twisted comes with a number of credentials interfaces and implementations
129
 
in the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.credentials.html" title="twisted.cred.credentials">twisted.cred.credentials</a></code> module,
130
 
such as <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.credentials.IUsernamePassword.html" title="twisted.cred.credentials.IUsernamePassword">IUsernamePassword</a></code>
131
 
and <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.credentials.IUsernameHashedPassword.html" title="twisted.cred.credentials.IUsernameHashedPassword">IUsernameHashedPassword</a></code>.</p>
 
125
in the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.credentials.html" title="twisted.cred.credentials">twisted.cred.credentials</a></code> module,
 
126
such as <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.credentials.IUsernamePassword.html" title="twisted.cred.credentials.IUsernamePassword">IUsernamePassword</a></code>
 
127
and <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.credentials.IUsernameHashedPassword.html" title="twisted.cred.credentials.IUsernameHashedPassword">IUsernameHashedPassword</a></code>.</p>
132
128
 
133
129
    <h3>The Realm<a name="auto5"/></h3>
134
130
<p>A realm is an interface which connects your universe of <q>business
135
131
objects</q> to the authentication system.</p>
136
132
 
137
 
<p><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.IRealm.html" title="twisted.cred.portal.IRealm">IRealm</a></code> is another one-method interface:</p>
 
133
<p><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.IRealm.html" title="twisted.cred.portal.IRealm">IRealm</a></code> is another one-method interface:</p>
138
134
 
139
135
<ul>
140
 
<li><code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.portal.IRealm.requestAvatar.html" title="twisted.cred.portal.IRealm.requestAvatar">requestAvatar</a></code><code>(avatarId, mind, *interfaces)</code>
 
136
<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.portal.IRealm.requestAvatar.html" title="twisted.cred.portal.IRealm.requestAvatar">requestAvatar</a></code><code>(avatarId, mind, *interfaces)</code>
141
137
 
142
138
<p>This method will typically be called from 'Portal.login'.  The avatarId
143
139
is the one returned by a CredentialChecker.</p>
436
432
<p> To build a plugin for cred, you should first define an <code class="python">authType</code>, a short one-word string that defines
437
433
your plugin to the command-line. Once you have this, the convention is
438
434
to create a file named <code>myapp_plugins.py</code> in the
439
 
<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugins.html" title="twisted.plugins">twisted.plugins</a></code> module path. </p>
 
435
<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.plugins.html" title="twisted.plugins">twisted.plugins</a></code> module path. </p>
440
436
 
441
437
<p> Below is an example file structure for an application that defines
442
438
such a plugin: </p>
468
464
<p>
469
465
Once you have created this structure within your application, you can
470
466
create the code for your cred plugin by building a factory class which
471
 
implements <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.cred.checkers.ICheckerFactory.html" title="twisted.cred.checkers.ICheckerFactory">ICheckerFactory</a></code>.
 
467
implements <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.checkers.ICheckerFactory.html" title="twisted.cred.checkers.ICheckerFactory">ICheckerFactory</a></code>.
472
468
These factory classes should not consist of a tremendous amount of
473
469
code. Most of the real application logic should reside in the cred
474
470
checker itself. (For help on building those, scroll up.)
565
561
</div>
566
562
 
567
563
    <p><a href="index.html">Index</a></p>
568
 
    <span class="version">Version: 9.0.0</span>
 
564
    <span class="version">Version: 10.0.0</span>
569
565
  </body>
570
566
</html>
 
 
b'\\ No newline at end of file'