<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Developer’s Authorization — Swift v1.0.2 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.0.2',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Swift v1.0.2 documentation" href="index.html" />
<link rel="next" title="Misc" href="misc.html" />
<link rel="prev" title="Object" href="object.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="misc.html" title="Misc"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="object.html" title="Object"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Swift v1.0.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="developer-s-authorization">
<span id="auth"></span><h1>Developer’s Authorization<a class="headerlink" href="#developer-s-authorization" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-swift.auth.server">
<span id="auth-server"></span><h2>Auth Server<a class="headerlink" href="#module-swift.auth.server" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="swift.auth.server.AuthController">
<em class="property">class </em><tt class="descclassname">swift.auth.server.</tt><tt class="descname">AuthController</tt><big>(</big><em>conf</em>, <em>ring=None</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <tt class="xref docutils literal"><span class="pre">object</span></tt></p>
<p>Sample implementation of an authorization server for development work. This
server only implements the basic functionality and isn’t written for high
availability or to scale to thousands (or even hundreds) of requests per
second. It is mainly for use by developers working on the rest of the
system.</p>
<p>The design of the auth system was restricted by a couple of existing
systems.</p>
<p>This implementation stores an account name, user name, and password (in
plain text!) as well as a corresponding Swift cluster url and account hash.
One existing auth system used account, user, and password whereas another
used just account and an “API key”. Here, we support both systems with
their various, sometimes colliding headers.</p>
<p>The most common use case is by the end user:</p>
<ul class="simple">
<li>The user makes a ReST call to the auth server requesting a token and url
to use to access the Swift cluster.</li>
<li>The auth system validates the user info and returns a token and url for
the user to use with the Swift cluster.</li>
<li>The user makes a ReST call to the Swift cluster using the url given with
the token as the X-Auth-Token header.</li>
<li>The Swift cluster makes an ReST call to the auth server to validate the
token for the given account hash, caching the result for future requests
up to the expiration the auth server returns.</li>
<li>The auth server validates the token / account hash given and returns the
expiration for the token.</li>
<li>The Swift cluster completes the user’s request.</li>
</ul>
<p>Another use case is creating a new account:</p>
<ul class="simple">
<li>The developer makes a ReST call to create a new account.</li>
<li>The auth server makes ReST calls to the Swift cluster’s account servers
to create a new account on its end.</li>
<li>The auth server records the information in its database.</li>
</ul>
<p>A last use case is recreating existing accounts; this is really only useful
on a development system when the drives are reformatted quite often but
the auth server’s database is retained:</p>
<ul class="simple">
<li>A developer makes an ReST call to have the existing accounts recreated.</li>
<li>For each account in its database, the auth server makes ReST calls to
the Swift cluster’s account servers to create a specific account on its
end.</li>
</ul>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><em>conf</em> – The [auth-server] dictionary of the auth server configuration
file</li>
<li><em>ring</em> – Overrides loading the account ring from a file; useful for
testing.</li>
</ul>
</td>
</tr>
</tbody>
</table>
<p>See the etc/auth-server.conf-sample for information on the possible
configuration parameters.</p>
<dl class="method">
<dt id="swift.auth.server.AuthController.add_storage_account">
<tt class="descname">add_storage_account</tt><big>(</big><em>account_name=''</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.add_storage_account" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates an account within the Swift cluster by making a ReST call to
each of the responsible account servers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>account_name</em> – The desired name for the account; if omitted a
UUID4 will be used.</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">False upon failure, otherwise the name of the account
within the Swift cluster.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.create_account">
<tt class="descname">create_account</tt><big>(</big><em>new_account</em>, <em>new_user</em>, <em>new_password</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.create_account" title="Permalink to this definition">¶</a></dt>
<dd><p>Handles the create_account call for developers, used to request
an account be created both on a Swift cluster and in the auth server
database.</p>
<p>This will make ReST requests to the Swift cluster’s account servers
to have an account created on its side. The resulting account hash
along with the URL to use to access the account, the account name, the
user name, and the password is recorded in the auth server’s database.
The url is constructed now and stored separately to support changing
the configuration file’s default_cluster_url for directing new accounts
to a different Swift cluster while still supporting old accounts going
to the Swift clusters they were created on.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><em>new_account</em> – The name for the new account</li>
<li><em>new_user</em> – The name for the new user</li>
<li><em>new_password</em> – The password for the new account</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">False if the create fails, storage url if successful</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.get_conn">
<tt class="descname">get_conn</tt><big>(</big><em>*args</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.get_conn" title="Permalink to this definition">¶</a></dt>
<dd>Returns a DB API connection instance to the auth server’s SQLite
database. This is a contextmanager call to be use with the ‘with’
statement. It takes no parameters.</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.handleREST">
<tt class="descname">handleREST</tt><big>(</big><em>env</em>, <em>start_response</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.handleREST" title="Permalink to this definition">¶</a></dt>
<dd><p>Handles routing of ReST requests. This handler also logs all requests.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><em>env</em> – WSGI environment</li>
<li><em>start_response</em> – WSGI start_response function</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.handle_account_create">
<tt class="descname">handle_account_create</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.handle_account_create" title="Permalink to this definition">¶</a></dt>
<dd><p>Handles Rest requests from developers to have an account created.</p>
<dl class="docutils">
<dt>Valid URL paths:</dt>
<dd><ul class="first last simple">
<li>PUT /account/<account-name>/<user-name> - create the account</li>
</ul>
</dd>
<dt>Valid headers:</dt>
<dd><ul class="first last simple">
<li>X-Auth-Key: <password> (Only required when creating an account)</li>
</ul>
</dd>
</dl>
<p>If the HTTP request returns with a 204, then the account was created,
and the storage url will be available in the X-Storage-Url header.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>request</em> – webob.Request object</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.handle_account_recreate">
<tt class="descname">handle_account_recreate</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.handle_account_recreate" title="Permalink to this definition">¶</a></dt>
<dd><p>Handles ReST requests from developers to have accounts in the Auth
system recreated in Swift. I know this is bad ReST style, but this
isn’t production right? :)</p>
<dl class="docutils">
<dt>Valid URL paths:</dt>
<dd><ul class="first last simple">
<li>POST /recreate_accounts</li>
</ul>
</dd>
</dl>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>request</em> – webob.Request object</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.handle_auth">
<tt class="descname">handle_auth</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.handle_auth" title="Permalink to this definition">¶</a></dt>
<dd><p>Handles ReST requests from end users for a Swift cluster url and auth
token. This can handle all the various headers and formats that
existing auth systems used, so it’s a bit of a chameleon.</p>
<dl class="docutils">
<dt>Valid URL paths:</dt>
<dd><ul class="first last simple">
<li>GET /v1/<account-name>/auth</li>
<li>GET /auth</li>
<li>GET /v1.0</li>
</ul>
</dd>
<dt>Valid headers:</dt>
<dd><ul class="first last">
<li><p class="first">X-Auth-User: <account-name>:<user-name></p>
</li>
<li><p class="first">X-Auth-Key: <password></p>
</li>
<li><dl class="first docutils">
<dt>X-Storage-User: [<account-name>:]<user-name></dt>
<dd><p class="first last">The [<account-name>:] is only optional here if the
/v1/<account-name>/auth path is used.</p>
</dd>
</dl>
</li>
<li><p class="first">X-Storage-Pass: <password></p>
</li>
</ul>
</dd>
</dl>
<p>The (currently) preferred method is to use /v1.0 path and the
X-Auth-User and X-Auth-Key headers.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>request</em> – A webob.Request instance.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.handle_token">
<tt class="descname">handle_token</tt><big>(</big><em>request</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.handle_token" title="Permalink to this definition">¶</a></dt>
<dd><p>Hanles ReST request from Swift to validate tokens</p>
<dl class="docutils">
<dt>Valid URL paths:</dt>
<dd><ul class="first last simple">
<li>GET /token/<account-hash>/<token></li>
</ul>
</dd>
</dl>
<p>If the HTTP equest returns with a 204, then the token is valid,
and the TTL of the token will be available in the X-Auth-Ttl header.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><em>request</em> – webob.Request object</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.purge_old_tokens">
<tt class="descname">purge_old_tokens</tt><big>(</big><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.purge_old_tokens" title="Permalink to this definition">¶</a></dt>
<dd>Removes tokens that have expired from the auth server’s database. This
is called by <a title="swift.auth.server.AuthController.validate_token" class="reference internal" href="#swift.auth.server.AuthController.validate_token"><tt class="xref docutils literal"><span class="pre">validate_token()</span></tt></a> and <tt class="xref docutils literal"><span class="pre">GET()</span></tt> to help keep the
database clean.</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.recreate_accounts">
<tt class="descname">recreate_accounts</tt><big>(</big><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.recreate_accounts" title="Permalink to this definition">¶</a></dt>
<dd><p>Recreates the accounts from the existing auth database in the Swift
cluster. This is useful on a development system when the drives are
reformatted quite often but the auth server’s database is retained.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A string indicating accounts and failures</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="swift.auth.server.AuthController.validate_token">
<tt class="descname">validate_token</tt><big>(</big><em>token</em>, <em>account_hash</em><big>)</big><a class="headerlink" href="#swift.auth.server.AuthController.validate_token" title="Permalink to this definition">¶</a></dt>
<dd><p>Tests if the given token is a valid token</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><em>token</em> – The token to validate</li>
<li><em>account_hash</em> – The account hash the token is being used with</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">TTL if valid, False otherwise</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference external" href="#">Developer’s Authorization</a><ul>
<li><a class="reference external" href="#module-swift.auth.server">Auth Server</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="object.html"
title="previous chapter">Object</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="misc.html"
title="next chapter">Misc</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/auth.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="modindex.html" title="Global Module Index"
>modules</a> |</li>
<li class="right" >
<a href="misc.html" title="Misc"
>next</a> |</li>
<li class="right" >
<a href="object.html" title="Object"
>previous</a> |</li>
<li><a href="index.html">Swift v1.0.2 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010, OpenStack, LLC..
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.6.
</div>
</body>
</html>
distrib
>
Fedora
>
13
>
i386
>
media
>
updates
>
by-pkgid
>
e2eef204a8562d4f753a051d0e998dc4
>
files
>
33
