Documentation

Cookbook: Authentication

In this section you will find information useful to set up authentication mechanisms with several of Cherokee’s validators.

You can find information and basic examples in each validator’s documentation. This is the list of validator modules provided by Cherokee:

You will also find interesting information in the "Validator Modules Overview" and step by step examples for Plain and PAM mechanisms in the "Quickstart" section.

There are two types of authentication:

basic

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.

digest

This method is by far the most secure, but also more complex. Most modern web browsers support this method.

The details to set up the ‘htdigest` and htpasswd are exactly the same as for plain validation. The only difference is the tools used to create the passwords’ file.

htdigest

To use this validator you will need a file created by the htdigest command. It is a tool to manage user files for digest (and basic) authentication.

Syntax

htdigest [ -c ] passwdfile realm username

The only optional parameter is -c, used to create the passwdfile or overwrite it if it is present.

To create a file for a testuser with testpassword you would have to issue:

$ htdigest -c passwords.digest secret testuser
Adding password for testuser in realm secret.
New password:
Re-type new password:

$ cat pass
testuser:secret:f24f76261bcd65780b33edde00855897

htpasswd

For this validator, the tool htpasswd is needed to create the files. The basic usage information is this:

Usage

htpasswd [-cmdpsD] passwordfile username 

htpasswd -b[cmdpsD] passwordfile username password
htpasswd -n[mdps] username
htpasswd -nb[mdps] username password

Refer to its documentation for details about the parameters. For our example, this will suffice:

$ htpasswd -c /var/www/.htpasswd testuser
New password:
Re-type new password:
Adding password for user testuser

$ cat /var/www/.htpasswd
testuser:iqLGh2g/7bX7M

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.

MySQL

Lets set up a simple server requiring authentication against a MySQL database to fetch any content.

First, lets define a unique rule in our virtual server managed by the List and Send handler. Through the Security 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.

media/images/cookbook_mysql_validator.png

In this case, we have used:

SELECT password FROM auth_users WHERE username = '${user}'

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 cherokee with cherokee as user and password, and a table that suits the shown query.

Assuming you have a MySQL user with privileges granted to create databases, a MySQL session similar to this one would suffice:

$ 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

When we are done, our simple virtual server should only have a Default rule, managed by the List & Send hander, and with MySQL authentication set.

media/images/cookbook_mysql_rule.png

And any content requested to Cherokee will require prior authentication against the database.

Another usage example

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?

Let’s assume our locations are targets are: - /unprotected/.php - /protected/.php

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.

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:

  • The first one, of type Directory applied to the path /protected. This would be the top rule, should use one of the authentication mechanisms mentioned above and should not be set as FINAL.

  • The second one, of type Extension would apply to php files and should be configured as according to the PHP recipe. This one should be a FINAL rule.

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 FINAL rule, so the rule evaluation would stop.

In case the PHP files were not being requested from the secured directory, just the second rule would apply.

Fixed list

For this validator you will only need to add user-password pairs, and the mandatory realm field.

media/images/admin_validators_authlist.png

LDAP

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.

Field Value

Validation Mechanism

LDAP Server

Methods

Basic

Realm

secret

Server

localhost

Port

389

Bind Domain

my_domain

Bind Password

my_password

Base Domain

example.com
media/images/admin_validators_ldap.png