~ntt-pf-lab/nova/monkey_patch_notification

<?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">

<head>

<title>Twisted Documentation: HTTP Authentication</title>

</head>

<h1 class="title">HTTP Authentication</h1>

Many of the previous examples have looked at how to serve content by using

existing resource classes or implementing new ones. In this example we'll use

Twisted Web's basic or digest HTTP authentication to control access to these

resources.

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.guard.html" title="twisted.web.guard">guard</a></code>, the Twisted Web

module which provides most of the APIs that will be used in this example, helps

you to

add <a href="http://en.wikipedia.org/wiki/Authentication" shape="rect">authentication</a>

and <a href="http://en.wikipedia.org/wiki/Authorization" shape="rect">authorization</a> to a

resource hierarchy. It does this by providing a resource which implements

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.resource.Resource.getChild.html" title="twisted.web.resource.Resource.getChild">getChild</a></code> to return

a <a href="dynamic-dispatch.html" shape="rect">dynamically selected resource</a>. The

selection is based on the authentication headers in the request. If those

headers indicate that the request is made on behalf of Alice, then Alice's

resource will be returned. If they indicate that it was made on behalf of Bob,

his will be returned. If the headers contain invalid credentials, an error

resource is returned. Whatever happens, once this resource is returned, URL

traversal continues as normal from that resource.

The resource that implements this is <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.guard.HTTPAuthSessionWrapper.html" title="twisted.web.guard.HTTPAuthSessionWrapper">HTTPAuthSessionWrapper</a></code>, though it is directly

responsible for very little of the process. It will extract headers from the

request and hand them off to a credentials factory to parse them according to

the appropriate standards (eg <a href="http://tools.ietf.org/html/rfc2617" shape="rect">HTTP

Authentication: Basic and Digest Access Authentication</a>) and then hand the

resulting credentials object off to 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>, the core

of <a href="../../../core/howto/cred.html" shape="rect">Twisted Cred</a>, a system for

uniform handling of authentication and authorization. We won't discuss Twisted

Cred in much depth here. To make use of it with Twisted Web, the only thing you

really need to know is how to implement an <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>.

You need to implement a realm because the realm is the object that actually

decides which resources are used for which users. This can be as complex or as

simple as it suitable for your application. For this example we'll keep it very

simple: each user will have a resource which is a static file listing of the

<code>public_html</code> directory in their UNIX home directory. First, we need

to import <code>implements</code> from <code>zope.interface</code> and <code>IRealm</code> from

<code>twisted.cred.portal</code>. Together these will let me mark this class as

a realm (this is mostly - but not entirely - a documentation thing). We'll also

need <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.static.File.html" title="twisted.web.static.File">File</a></code> for the actual

implementation later.

<pre class="python">1

from zope.interface import implements

from twisted.cred.portal import IRealm

from twisted.web.static import File

class PublicHTMLRealm(object):

implements(IRealm)

</pre>

A realm only needs to implement one method: <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>. This method is called

after any successful authentication attempt (ie, Alice supplied the right

password). Its job is to return the avatar for the user who succeeded in

authenticating. An avatar is just an object that represents a user. In

this case, it will be a <code>File</code>. In general, with <code>Guard</code>,

the avatar must be a resource of some sort.

<pre class="python">1

def requestAvatar(self, avatarId, mind, *interfaces):

if IResource in interfaces:

return (IResource, File("/home/%s/public_html" % (avatarId,)), lambda: None)

raise NotImplementedError()

</pre>

A few notes on this method:

<ul>

<li>The <code>avatarId</code> parameter is essentially the username. It's the

job of some other code to extract the username from the request headers and

make sure it gets passed here.</li>

<li>The <code>mind</code> is always <code>None</code> when writing a realm to

be used with <code>Guard</code>. You can ignore it until you want to write a

realm for something else.</li>

<li><code>Guard</code> is always

passed <code class="twisted.web.resource">IResource</code> as

the <code>interfaces</code> parameter. If <code>interfaces</code> only

contains interfaces your code doesn't understand,

100

raising <code>NotImplementedError</code> is the thing to do, as

101

above. You'll only need to worry about getting a different interface when

102

you write a realm for something other than <code>Guard</code>.</li>

103

<li>If you want to track when a user logs out, that's what the last element of

104

the returned tuple is for. It will be called when this avatar logs

105

out. <code>lambda: None</code> is the idiomatic no-op logout function.</li>

106

<li>Notice that the path handling code in this example is written very

107

poorly. This example may be vulnerable to certain unintentional information

108

disclosure attacks. This sort of problem is exactly the

109

reason <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.filepath.FilePath.html" title="twisted.python.filepath.FilePath">FilePath</a></code>

110

exists. However, that's an example for another day...</li>

111

</ul>

112

113

We're almost ready to set up the resource for this example. To create an

114

<code>HTTPAuthSessionWrapper</code>, though, we need two things. First, a

115

portal, which requires the realm above, plus at least one credentials

116

checker:

117

118

<pre class="python">1

119

120

121

122

from twisted.cred.portal import Portal

123

from twisted.cred.checkers import FilePasswordDB

124

125

portal = Portal(PublicHTMLRealm(), [FilePasswordDB('httpd.password')])

126

</pre>

127

128

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.checkers.FilePasswordDB.html" title="twisted.cred.checkers.FilePasswordDB">FilePasswordDB</a></code> is the

129

credentials checker. It knows how to read <code>passwd(5)</code>-style (loosely)

130

files to check credentials against. It is responsible for the authentication

131

work after <code>HTTPAuthSessionWrapper</code> extracts the credentials from the

132

request.

133

134

Next we need either <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.guard.BasicCredentialFactory.html" title="twisted.web.guard.BasicCredentialFactory">BasicCredentialFactory</a></code> or

135

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.web.guard.DigestCredentialFactory.html" title="twisted.web.guard.DigestCredentialFactory">DigestCredentialFactory</a></code>. The

136

former knows how to challenge HTTP clients to do basic authentication; the

137

latter, digest authentication. We'll use digest here:

138

139

<pre class="python">1

140

141

142

from twisted.web.guard import DigestCredentialFactory

143

144

credentialFactory = DigestCredentialFactory("md5", "example.org")

145

</pre>

146

147

The two parameters to this constructor are the hash algorithm and the HTTP

148

authentication realm which will be used. The only other valid hash algorithm is

149

"sha" (but be careful, MD5 is more widely supported than SHA). The HTTP

150

authentication realm is mostly just a string that is presented to the user to

151

let them know why they're authenticating (you can read more about this in the

152

<a href="http://tools.ietf.org/html/rfc2617" shape="rect">RFC</a>).

153

154

With those things created, we can finally

155

instantiate <code>HTTPAuthSessionWrapper</code>:

156

157

<pre class="python">1

158

159

160

161

162

resource = HTTPAuthSessionWrapper(portal, [credentialFactory])

163

</pre>

164

165

There's just one last thing that needs to be done

166

here. When <a href="rpy-scripts.html" shape="rect">rpy scripts</a> were introduced, it was

167

mentioned that they are evaluated in an unusual context. This is the first

168

example that actually needs to take this into account. It so happens that

169

<code>DigestCredentialFactory</code> instances are stateful. Authentication will

170

only succeed if the same instance is used to both generate challenges and

171

examine the responses to those challenges. However, the normal mode of operation

172

for an rpy script is for it to be re-executed for every request. This leads to a

173

new

174

<code>DigestCredentialFactory</code> being created for every request, preventing

175

any authentication attempt from ever succeeding.

176

177

There are two ways to deal with this. First, and the better of the two ways,

178

we could move almost all of the code into a real Python module, including the

179

code that instantiates the <code>DigestCredentialFactory</code>. This would

180

ensure that the same instance was used for every request. Second, and the easier

181

of the two ways, we could add a call to <code>cache()</code> to the beginning of

182

the rpy script:

183

184

<pre class="python">1

185

cache()

186

</pre>

187

188

<code>cache</code> is part of the globals of any rpy script, so you don't

189

need to import it (it's okay to be cringing at this

190

point). Calling <code>cache</code> makes Twisted re-use the result of the first

191

evaluation of the rpy script for subsequent requests too - just what we want in

192

this case.

193

194

Here's the complete example (with imports re-arranged to the more

195

conventional style):

196

197

<pre class="python"> 1

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

cache()

220

221

from zope.interface import implements

222

223

224

from twisted.cred.checkers import FilePasswordDB

225

226

from twisted.web.resource import IResource

227

from twisted.web.guard import HTTPAuthSessionWrapper, DigestCredentialFactory

228

229

class PublicHTMLRealm(object):

230

implements(IRealm)

231

232

def requestAvatar(self, avatarId, mind, *interfaces):

233

if IResource in interfaces:

234

235

raise NotImplementedError()

236

237

238

239

240

241

</pre>

242

243

And voila, a password-protected per-user Twisted Web server.

244

245

</div>

246

247

<a href="../index.html">Index</a>

248

Version: 10.0.0

249

</body>

250

</html>

b'\\ No newline at end of file'

Older »