<!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" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Language" content="en-us" /> <meta name="ROBOTS" content="ALL" /> <meta http-equiv="imagetoolbar" content="no" /> <meta name="MSSmartTagsPreventParsing" content="true" /> <meta name="Keywords" content="cherokee web server httpd http" /> <meta name="Description" content="Cherokee is a flexible, very fast, lightweight Web server. It is implemented entirely in C, and has no dependencies beyond a standard C library. It is embeddable and extensible with plug-ins. It supports on-the-fly configuration by reading files or strings, TLS/SSL (via GNUTLS or OpenSSL), virtual hosts, authentication, cache friendly features, PHP, custom error management, and much more." /> <link href="media/css/cherokee_doc.css" rel="stylesheet" type="text/css" media="all" /> </head> <body> <h2 id="_a_href_index_html_index_a_8594_a_href_cookbook_html_cookbook_a"><a href="index.html">Index</a> → <a href="cookbook.html">Cookbook</a></h2> <div class="sectionbody"> </div> <h2 id="_cookbook_authentication">Cookbook: Authentication</h2> <div class="sectionbody"> <div class="paragraph"><p>In this section you will find information useful to set up authentication mechanisms with several of Cherokee’s validators.</p></div> <div class="paragraph"><p>You can find information and basic examples in each validator’s documentation. This is the list of validator modules provided by Cherokee:</p></div> <div class="ulist"><ul> <li> <p> <a href="modules_validators_htdigest.html">htdigest</a> </p> </li> <li> <p> <a href="modules_validators_htpasswd.html">htpasswd</a> </p> </li> <li> <p> <a href="modules_validators_ldap.html">LDAP</a> </p> </li> <li> <p> <a href="modules_validators_mysql.html">MySQL</a> </p> </li> <li> <p> <a href="modules_validators_pam.html">PAM</a> </p> </li> <li> <p> <a href="modules_validators_plain.html">Plain</a> </p> </li> <li> <p> <a href="modules_validators_authlist.html">Fixed List</a> </p> </li> </ul></div> <div class="paragraph"><p>You will also find interesting information in the <a href="modules_validators_plain.html">"Validator Modules Overview"</a> and step by step examples for Plain and PAM mechanisms in the <a href="config_walkthrough.html">"Quickstart"</a> section.</p></div> <div class="paragraph"><p>There are two types of authentication:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> <strong>basic</strong> </dt> <dd> <p> This method sends the username and password in clear text over the network. It is not the most secure method. If the connection to the web server is through HTTPS then this method is as secure as the encryption used. This method is very easy to implement, so most clients support it. </p> </dd> <dt class="hdlist1"> <strong>digest</strong> </dt> <dd> <p> This method is by far the most secure, but also more complex. Most modern web browsers support this method. </p> </dd> </dl></div> <div class="paragraph"><p>The details to set up the ‘htdigest` and <tt>htpasswd</tt> are exactly the same as for <tt>plain</tt> validation. The only difference is the tools used to create the passwords’ file.</p></div> <h3 id="htdigest">htdigest</h3><div style="clear:left"></div> <div class="paragraph"><p>To use this validator you will need a file created by the <tt>htdigest</tt> command. It is a tool to manage user files for digest (and basic) authentication.</p></div> <div class="sidebarblock"> <div class="sidebar-content"> <div class="dlist"><dl> <dt class="hdlist1"> Syntax </dt> <dd> <p> htdigest [ -c ] passwdfile realm username </p> </dd> </dl></div> <div class="paragraph"><p>The only optional parameter is <tt>-c</tt>, used to create the passwdfile or overwrite it if it is present.</p></div> </div></div> <div class="paragraph"><p>To create a file for a <tt>testuser</tt> with <tt>testpassword</tt> you would have to issue:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ htdigest -c passwords.digest secret testuser Adding password for testuser in realm secret. New password: Re-type new password: $ cat pass testuser:secret:f24f76261bcd65780b33edde00855897</tt></pre> </div></div> <h3 id="htpasswd">htpasswd</h3><div style="clear:left"></div> <div class="paragraph"><p>For this validator, the tool <tt>htpasswd</tt> is needed to create the files. The basic usage information is this:</p></div> <div class="sidebarblock"> <div class="sidebar-content"> <div class="dlist"><dl> <dt class="hdlist1"> Usage </dt> <dd> <p> htpasswd [-cmdpsD] passwordfile username </p> <div class="literalblock"> <div class="content"> <pre><tt>htpasswd -b[cmdpsD] passwordfile username password</tt></pre> </div></div> <div class="literalblock"> <div class="content"> <pre><tt>htpasswd -n[mdps] username</tt></pre> </div></div> <div class="literalblock"> <div class="content"> <pre><tt>htpasswd -nb[mdps] username password</tt></pre> </div></div> </dd> </dl></div> </div></div> <div class="paragraph"><p>Refer to its documentation for details about the parameters. For our example, this will suffice:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ htpasswd -c /var/www/.htpasswd testuser New password: Re-type new password: Adding password for user testuser $ cat /var/www/.htpasswd testuser:iqLGh2g/7bX7M</tt></pre> </div></div> <div class="paragraph"><p>Remember that it is never recommended to place the file with the passwords in a location fetchable from the webserver. This is true for plain validation, htdigest, htpasswd and whatever file based system you cross paths with.</p></div> <h3 id="mysql">MySQL</h3><div style="clear:left"></div> <div class="paragraph"><p>Lets set up a simple server requiring authentication against a MySQL database to fetch any content.</p></div> <div class="paragraph"><p>First, lets define a unique rule in our virtual server managed by the <tt>List and Send</tt> handler. Through the <tt>Security</tt> tab we can configure it to use MySQL as authentication mechanism. Filling up just the essential fields will be enough. Those are realm, database name, user, password, and an SQL query that must return one row with one column as password.</p></div> <div class="imageblock"> <div class="content"> <img src="media/images/cookbook_mysql_validator.png" alt="media/images/cookbook_mysql_validator.png" /> </div> </div> <div class="paragraph"><p>In this case, we have used:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>SELECT password FROM auth_users WHERE username = '${user}'</tt></pre> </div></div> <div class="paragraph"><p>And that is about it. In this example you will need a MySQL server running (localhost in this case, as it takes the default value), a database called <tt>cherokee</tt> with <tt>cherokee</tt> as user and password, and a table that suits the shown query.</p></div> <div class="paragraph"><p>Assuming you have a MySQL user with privileges granted to create databases, a MySQL session similar to this one would suffice:</p></div> <div class="listingblock"> <div class="content"> <pre><tt>$ mysql -u cherokee -D cherokee -p mysql> CREATE DATABASE cherokee; Query OK, 1 row affected (0.00 sec) mysql> CREATE TABLE auth_users( username varchar(32), password varchar(32), PRIMARY KEY (username)); Query OK, 0 rows affected (0.00 sec) mysql> INSERT INTO auth_users VALUES('cherokee','cherokee'); Query OK, 1 row affected (0.00 sec) mysql> quit</tt></pre> </div></div> <div class="paragraph"><p>When we are done, our simple virtual server should only have a <tt>Default</tt> rule, managed by the <tt>List & Send</tt> hander, and with <tt>MySQL</tt> authentication set.</p></div> <div class="imageblock"> <div class="content"> <img src="media/images/cookbook_mysql_rule.png" alt="media/images/cookbook_mysql_rule.png" /> </div> </div> <div class="paragraph"><p>And any content requested to Cherokee will require prior authentication against the database.</p></div> <h3 id="example">Another usage example</h3><div style="clear:left"></div> <div class="paragraph"><p>As you can see, getting the hang of how authentication works is pretty easy. Let’s illustrate another easy example. How to serve PHP files, both from a protected location and an unprotected one?</p></div> <div class="paragraph"><p>Let’s assume our locations are targets are: - /unprotected/<strong>.php - /protected/</strong>.php</p></div> <div class="paragraph"><p>Well… this would be really easy. You just have to remember that rules are evaluated from top to bottom, and the evaluation proceeds until a final rule is matched.</p></div> <div class="paragraph"><p>This means that we would only have to be careful with the order of our rules, and it would be as simple as setting a couple of rules:</p></div> <div class="ulist"><ul> <li> <p> The first one, of type <tt>Directory</tt> applied to the path <tt>/protected</tt>. This would be the top rule, should use one of the authentication mechanisms mentioned above and should not be set as <em>FINAL</em>. </p> </li> <li> <p> The second one, of type <tt>Extension</tt> would apply to <tt>php</tt> files and should be configured as according to the <a href="cookbook_php.html">PHP recipe</a>. This one should be a <em>FINAL</em> rule. </p> </li> </ul></div> <div class="paragraph"><p>And this would be more than enough. The files from the secure location would match the first rule and the authentication would be required. In case it was successful, not being a final rule, the request would proceed to the second rule. Once there, the regular processing of PHP files would take place. This one is a <em>FINAL</em> rule, so the rule evaluation would stop.</p></div> <div class="paragraph"><p>In case the PHP files were not being requested from the secured directory, just the second rule would apply.</p></div> <h3 id="fixed_list">Fixed list</h3><div style="clear:left"></div> <div class="paragraph"><p>For this validator you will only need to add user-password pairs, and the mandatory <tt>realm</tt> field.</p></div> <div class="imageblock"> <div class="content"> <img src="media/images/admin_validators_authlist.png" alt="media/images/admin_validators_authlist.png" /> </div> </div> <h3 id="ldap">LDAP</h3><div style="clear:left"></div> <div class="paragraph"><p>Here is a basic example of the LDAP validator in action. It assumes you have a working LDAP service running at your localhost, and it uses no TLS of CA files.</p></div> <div class="tableblock"> <table rules="all" width="100%" frame="border" cellspacing="0" cellpadding="4"> <col width="50%" /> <col width="50%" /> <thead> <tr> <th align="left" valign="top">Field </th> <th align="left" valign="top"> Value</th> </tr> </thead> <tbody> <tr> <td align="left" valign="top"><p class="table">Validation Mechanism</p></td> <td align="left" valign="top"><p class="table"><tt>LDAP Server</tt></p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Methods</p></td> <td align="left" valign="top"><p class="table"><tt>Basic</tt></p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Realm</p></td> <td align="left" valign="top"><p class="table">secret</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Server</p></td> <td align="left" valign="top"><p class="table">localhost</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Port</p></td> <td align="left" valign="top"><p class="table">389</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Bind Domain</p></td> <td align="left" valign="top"><p class="table">my_domain</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Bind Password</p></td> <td align="left" valign="top"><p class="table">my_password</p></td> </tr> <tr> <td align="left" valign="top"><p class="table">Base Domain</p></td> <td align="left" valign="top"><p class="table">example.com</p></td> </tr> </tbody> </table> </div> <div class="imageblock"> <div class="content"> <img src="media/images/admin_validators_ldap.png" alt="media/images/admin_validators_ldap.png" /> </div> </div> </div> <div id="footer"> <div id="footer-text"> </div> </div> </body> </html>