~soren/nova/iptables-security-groups

<?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: Cred: Pluggable Authentication</title>

</head>

<h1 class="title">Cred: Pluggable Authentication</h1>

<div class="toc"><ol><li><a href="#auto0">Goals</a></li><li><a href="#auto1">Cred objects</a></li><ul><li><a href="#auto2">The Portal</a></li><li><a href="#auto3">The CredentialChecker</a></li><li><a href="#auto4">The Credentials</a></li><li><a href="#auto5">The Realm</a></li><li><a href="#auto6">The Avatar</a></li><li><a href="#auto7">The Mind</a></li></ul><li><a href="#auto8">Responsibilities</a></li><ul><li><a href="#auto9">Server protocol implementation</a></li><li><a href="#auto10">Application implementation</a></li><li><a href="#auto11">Deployment</a></li></ul><li><a href="#auto12">Cred plugins</a></li><ul><li><a href="#auto13">Authentication with cred plugins</a></li><li><a href="#auto14">Building a cred plugin</a></li></ul><li><a href="#auto15">Conclusion</a></li></ol></div>

<h2>Goals<a name="auto0"/></h2>

Cred is a pluggable authentication system for servers. It allows any

number of network protocols to connect and authenticate to a system, and

communicate to those aspects of the system which are meaningful to the specific

protocol. For example, Twisted's POP3 support passes a <q>username and

password</q> set of credentials to get back a mailbox for the specified email

account. IMAP does the same, but retrieves a slightly different view of the

same mailbox, enabling those features specific to IMAP which are not available

in other mail protocols.

Cred is designed to allow both the backend implementation of the business

logic - called the avatar - and the authentication database - called

the credential checker - to be decided during deployment. For example,

the same POP3 server should be able to authenticate against the local UNIX

password database or an LDAP server without having to know anything about how

or where mail is stored.

To sketch out how this works - a <q>Realm</q> corresponds to an application

domain and is in charge of avatars, which are network-accessible business logic

objects. To connect this to an authentication database, a top-level object

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

realm, and a number of credential checkers. Something that wishes to log in,

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>,

stores a reference to the portal. Login consists of passing credentials and a

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

the credentials to the appropriate credential checker, which returns an avatar

ID. The ID is passed to the realm, which returns the appropriate avatar. For a

Portal that has a realm that creates mailbox objects and a credential checker

that checks /etc/passwd, login consists of passing in a username/password and

the IMailbox interface to the portal. The portal passes this to the /etc/passwd

credential checker, gets back a avatar ID corresponding to an email account,

passes that to the realm and gets back a mailbox object for that email

account.

Putting all this together, here's how a login request will typically be

processed:

<h2>Cred objects<a name="auto1"/></h2>

<h3>The Portal<a name="auto2"/></h3>

This is the the core of login, the point of integration between all the objects

in the cred system. There is one

concrete implementation of Portal, and no interface - it does a very

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>

associates one (1) Realm with a collection of

CredentialChecker instances. (More on those later.)

If you are writing a protocol that needs to authenticate against

something, you will need a reference to a Portal, and to nothing else.

This has only 2 methods -

<ul>

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

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

brief, this is what you call when you need to call in order to connect

a user to the system. Typically you only pass in one interface, and the mind is

<code class="python">None</code>. The interfaces are the possible interfaces the returned

avatar is expected to implement, in order of preference.

The result is a deferred which fires a tuple of:

<ul>

<li>interface the avatar implements (which was one of the interfaces passed in the *interfaces

tuple)</li>

<li>an object that implements that interface (an avatar)</li>

<li>logout, a 0-argument callable which disconnects the connection that was

established by this call to login</li>

</ul>

The logout method has to be called when the avatar is logged out. For POP3 this means

when the protocol is disconnected or logged out, etc..

</li>

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

which adds a CredentialChecker to the portal. The optional list of interfaces are interfaces of credentials

that the checker is able to check.

</li></ul>

<h3>The CredentialChecker<a name="auto3"/></h3>

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

credentials to an avatar ID.

Whether the credentials are stored in an in-memory data structure, an

Apache-style htaccess file, a UNIX password database, an SSH key database,

or any other form, an implementation of <code>ICredentialsChecker</code> is

how this data is connected to cred.

100

101

A credential checker

102

stipulates some requirements of the credentials it can check by

103

specifying a credentialInterfaces attribute, which is a list of

104

interfaces. Credentials passed to its requestAvatarId method must

105

implement one of those interfaces.

106

107

For the most part, these things will just check usernames and passwords

108

and produce the username as the result, but hopefully we will be seeing

109

some public-key, challenge-response, and certificate based credential

110

checker mechanisms soon.

111

112

A credential checker should raise an error if it cannot authenticate

113

the user, and return <code>twisted.cred.checkers.ANONYMOUS</code>

114

for anonymous access.

115

116

<h3>The Credentials<a name="auto4"/></h3>

117

Oddly enough, this represents some credentials that the user presents.

118

Usually this will just be a small static blob of data, but in some

119

cases it will actually be an object connected to a network protocol.

120

For example, a username/password pair is static, but a

121

challenge/response server is an active state-machine that will require

122

several method calls in order to determine a result.

123

124

Twisted comes with a number of credentials interfaces and implementations

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>.

128

129

<h3>The Realm<a name="auto5"/></h3>

130

A realm is an interface which connects your universe of <q>business

131

objects</q> to the authentication system.

132

133

<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:

134

135

<ul>

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>

137

138

This method will typically be called from 'Portal.login'. The avatarId

139

is the one returned by a CredentialChecker.

140

141

<div class="note">Note: Note that <code>avatarId</code> must always be a string. In

142

particular, do not use unicode strings. If internationalized support is needed,

143

it is recommended to use UTF-8, and take care of decoding in the realm. </div>

144

145

The important thing to realize about this method is that if it is being

146

called, the user has already authenticated. Therefore, if possible,

147

the Realm should create a new user if one does not already exist

148

whenever possible. Of course, sometimes this will be impossible

149

without more information, and that is the case that the interfaces

150

argument is for.

151

</li>

152

</ul>

153

154

Since requestAvatar should be called from a Deferred callback, it may

155

return a Deferred or a synchronous result.

156

157

<h3>The Avatar<a name="auto6"/></h3>

158

159

An avatar is a business logic object for a specific user. For POP3, it's

160

a mailbox, for a first-person-shooter it's the object that interacts with

161

the game, the actor as it were. Avatars are specific to an application,

162

and each avatar represents a single <q>user</q>.

163

164

165

166

As mentioned before, the mind is usually None, so you can skip this

167

bit if you want.

168

169

Masters of Perspective Broker already know this object as the ill-named

170

<q>client object</q>. There is no <q>mind</q> class, or even interface, but it

171

is an object which serves an important role - any notifications which are to be

172

relayed to an authenticated client are passed through a 'mind'. In addition, it

173

allows passing more information to the realm during login in addition to the

174

avatar ID.

175

176

The name may seem rather unusual, but considering that a Mind is

177

representative of the entity on the <q>other end</q> of a network connection

178

that is both receiving updates and issuing commands, I believe it is

179

appropriate.

180

181

Although many protocols will not use this, it serves an important role.

182

It is provided as an argument both to the Portal and to the Realm,

183

although a CredentialChecker should interact with a client program

184

exclusively through a Credentials instance.

185

186

Unlike the original Perspective Broker <q>client object</q>, a Mind's

187

implementation is most often dictated by the protocol that is

188

connecting rather than the Realm. A Realm which requires a particular

189

interface to issue notifications will need to wrap the Protocol's mind

190

implementation with an adapter in order to get one that conforms to its

191

expected interface - however, Perspective Broker will likely continue

192

to use the model where the client object has a pre-specified remote

193

interface.

194

195

(If you don't quite understand this, it's fine. It's hard to explain,

196

and it's not used in simple usages of cred, so feel free to pass None

197

until you find yourself requiring something like this.)

198

199

<h2>Responsibilities<a name="auto8"/></h2>

200

201

<h3>Server protocol implementation<a name="auto9"/></h3>

202

203

The protocol implementor should define the interface the avatar should implement,

204

and design the protocol to have a portal attached. When a user logs in using the

205

protocol, a credential object is created, passed to the portal, and an avatar

206

with the appropriate interface is requested. When the user logs out or the protocol

207

is disconnected, the avatar should be logged out.

208

209

The protocol designer should not hardcode how users are authenticated or the

210

realm implemented. For example, a POP3 protocol implementation would require a portal whose

211

realm returns avatars implementing IMailbox and whose credential checker accepts

212

username/password credentials, but that is all. Here's a sketch of how the code

213

might look - note that USER and PASS are the protocol commands used to login, and

214

the DELE command can only be used after you are logged in:

215

216

<pre class="python"> 1

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

from zope.interface import Interface

274

275

from twisted.protocols import basic

276

from twisted.python import log

277

from twisted.cred import credentials, error

278

from twisted.internet import defer

279

280

class IMailbox(Interface):

281

"""Interface specification for mailbox."""

282

def deleteMessage(index): pass

283

284

285

class POP3(basic.LineReceiver):

286

# ...

287

def __init__(self, portal):

288

self.portal = portal

289

290

def do_DELE(self, i):

291

# uses self.mbox, which is set after login

292

i = int(i)-1

293

self.mbox.deleteMessage(i)

294

self.successResponse()

295

296

def do_USER(self, user):

297

self._userIs = user

298

self.successResponse('USER accepted, send PASS')

299

300

def do_PASS(self, password):

301

if self._userIs is None:

302

self.failResponse("USER required before PASS")

303

return

304

user = self._userIs

305

self._userIs = None

306

d = defer.maybeDeferred(self.authenticateUserPASS, user, password)

307

d.addCallback(self._cbMailbox, user)

308

309

def authenticateUserPASS(self, user, password):

310

if self.portal is not None:

311

return self.portal.login(

312

cred.credentials.UsernamePassword(user, password),

313

None,

314

IMailbox

315

)

316

raise error.UnauthorizedLogin()

317

318

def _cbMailbox(self, ial, user):

319

interface, avatar, logout = ial

320

321

if interface is not IMailbox:

322

self.failResponse('Authentication failed')

323

log.err("_cbMailbox() called with an interface other than IMailbox")

324

return

325

326

self.mbox = avatar

327

self._onLogout = logout

328

self.successResponse('Authentication succeeded')

329

log.msg("Authenticated login for " + user)

330

</pre>

331

332

<h3>Application implementation<a name="auto10"/></h3>

333

334

The application developer can implement realms and credential checkers. For example,

335

she might implement a realm that returns IMailbox implementing avatars, using MySQL

336

for storage, or perhaps a credential checker that uses LDAP for authentication.

337

In the following example, the Realm for a simple remote object service (using

338

Twisted's Perspective Broker protocol) is implemented:

339

340

<pre class="python"> 1

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

from twisted.spread import pb

363

from twisted.cred.portal import IRealm

364

365

class SimplePerspective(pb.Avatar):

366

367

def perspective_echo(self, text):

368

print 'echoing',text

369

return text

370

371

def logout(self):

372

print self, "logged out"

373

374

375

class SimpleRealm:

376

implements(IRealm)

377

378

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

379

if pb.IPerspective in interfaces:

380

avatar = SimplePerspective()

381

return pb.IPerspective, avatar, avatar.logout

382

else:

383

raise NotImplementedError("no interface")

384

</pre>

385

386

<h3>Deployment<a name="auto11"/></h3>

387

388

Deployment involves tying together a protocol, an appropriate realm and a credential

389

checker. For example, a POP3 server can be constructed by attaching to it a portal

390

that wraps the MySQL-based realm and an /etc/passwd credential checker, or perhaps

391

the LDAP credential checker if that is more useful. The following example shows

392

how the SimpleRealm in the previous example is deployed using an in-memory credential checker:

393

394

<pre class="python"> 1

395

396

397

398

399

400

401

402

403

404

405

406

407

408

from twisted.cred.checkers import InMemoryUsernamePasswordDatabaseDontUse

409

410

portal = Portal(SimpleRealm())

411

checker = InMemoryUsernamePasswordDatabaseDontUse()

412

checker.addUser("guest", "password")

413

portal.registerChecker(checker)

414

reactor.listenTCP(9986, pb.PBServerFactory(portal))

415

reactor.run()

416

</pre>

417

418

<h2>Cred plugins<a name="auto12"/></h2>

419

420

<h3>Authentication with cred plugins<a name="auto13"/></h3>

421

422

Cred offers a plugin architecture for authentication methods. The

423

primary API for this architecture is the command-line; the plugins are

424

meant to be specified by the end-user when deploying a TAP (twistd

425

plugin).

426

427

For more information on writing a twistd plugin and using cred

428

plugins for your application, please refer to the <a href="tap.html" shape="rect">Writing a twistd plugin</a> document.

429

430

<h3>Building a cred plugin<a name="auto14"/></h3>

431

432

To build a plugin for cred, you should first define an <code class="python">authType</code>, a short one-word string that defines

433

your plugin to the command-line. Once you have this, the convention is

434

to create a file named <code>myapp_plugins.py</code> in the

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.

436

437

Below is an example file structure for an application that defines

438

such a plugin:

439

440

<ul>

441

<li>MyApplication/

442

<ul>

443

<li>setup.py</li>

444

<li>myapp/

445

<ul>

446

447

448

<li>server.py</li>

449

</ul>

450

</li>

451

<li>twisted/

452

<ul>

453

<li>plugins/

454

<ul>

455

<li>myapp_plugins.py</li>

456

</ul>

457

</li>

458

</ul>

459

</li>

460

</ul>

461

</li>

462

</ul>

463

464

465

Once you have created this structure within your application, you can

466

create the code for your cred plugin by building a factory class which

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>.

468

These factory classes should not consist of a tremendous amount of

469

code. Most of the real application logic should reside in the cred

470

checker itself. (For help on building those, scroll up.)

471

472

473

474

The core purpose of the CheckerFactory is to translate an <code class="python">argstring</code>, which is passed on the command line,

475

into a suitable set of initialization parameters for a Checker

476

class. In most cases this should be little more than constructing a

477

dictionary or a tuple of arguments, then passing them along to a new

478

checker instance.

479

480

481

<pre class="python"> 1

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

from twisted import plugin

516

517

from myapp.cred import SpecialChecker

518

519

class SpecialCheckerFactory(object):

520

"""

521

A checker factory for a specialized (fictional) API.

522

"""

523

# The class needs to implement both of these interfaces

524

# for the plugin system to find our factory.

525

implements(checkers.ICheckerFactory, plugin.IPlugin)

526

527

# This tells AuthOptionsMixin how to find this factory.

528

authType = "special"

529

530

# This is a one-line explanation of what arguments, if any,

531

# your particular cred plugin requires at the command-line.

532

argStringFormat = "A colon-separated key=value list."

533

534

# This help text can be multiple lines. It will be displayed

535

# when someone uses the "--help-auth-type special" command.

536

authHelp = """Some help text goes here ..."""

537

538

# This will be called once per command-line.

539

def generateChecker(self, argstring=""):

540

argdict = dict((x.split('=') for x in argstring.split(':')))

541

return SpecialChecker(**dict)

542

543

# We need to instantiate our class for the plugin to work.

544

theSpecialCheckerFactory = SpecialCheckerFactory()

545

</pre>

546

547

For more information on how your plugin can be used in your

548

application (and by other application developers), please see the <a href="tap.html" shape="rect">Writing a twistd plugin</a> document.

549

550

<h2>Conclusion<a name="auto15"/></h2>

551

552

After reading through this tutorial, you should be able to

553

554

<ul>

555

<li>Understand how the cred architecture applies to your application</li>

556

<li>Integrate your application with cred's object model</li>

557

<li>Deploy an application that uses cred for authentication</li>

558

<li>Allow your users to use command-line authentication plugins</li>

559

</ul>

560

561

</div>

562

563

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

564

Version: 10.0.0

565

</body>

566

</html>

b'\\ No newline at end of file'

Older »