Button Button

Sputnik handles user authentication through swappable modules.

Authentication Configuration

The authentication module is specified by the 'AUTH_MODULE' parameter. It defaults to "sputnik.authentication.simple". Some modules may need additional configuration parameters. Those are set through 'AUTH_MODULE_PARAMS'. For instance, to use the "mysql" authentication module, we need to set:

AUTH_MODULE = 'sputnik.auth.mysql',
AUTH_MODULE_PARAMS = {"database_name", "db_user", "password", "localhost"},

Available Authentication Modules

"Simple" (sputnik.auth.simple)

Uses a Sputnik node to store the user data. No configuration is required, since this module is the default.

SQLite3 (sputnik.auth.sqlite3)

Uses SQLite3 to store the user data.

Install sputnik-auth-sqlite3 rock:

./bin/luarocks install --only-from=http://sputnik.freewisdom.org/rocks/earth sputnik-auth-sqlite3

Then add set

AUTH_MODULE = 'sputnik.auth.sqlite3',
AUTH_MODULE_PARAMS = {"/home/yuri/sputnik/users.db"},

users.db file does not need to exist, but your server should have permissions to create it.

MySQL (sputnik.auth.mysql)

Uses a MySQL database to store the user data.

Install sputnik-auth-mysql rock:

./bin/luarocks install --only-from=http://sputnik.freewisdom.org/rocks/earth sputnik-auth-mysql

Then add set

AUTH_MODULE = 'sputnik.auth.mysql',
AUTH_MODULE_PARAMS = {"sputnik_users", "sputnik", "letmein", "localhost"},

The parameters here specify: (1) the name of the database, (2) the user name for the database, (3) the password, (4) the host, (5) optionally the port number.

You will also need to make sure that the database exists on the host and is accessible to this user with this password.

Authentication API

An authentication module must implement a single public function "new()" which takes two arguments: an instance of Sputnik and a table of parameters (the value of AUTH_MODULE\_PARAMS). It returns an object, which must then offer the following methods:


Returns whether or not a given username exists in the authentication system, without any further information.


Returns a cryptographic token for the specified timestamp. This is provided for use outside the authentication system.

Auth:authenticate(username, password)

Attempt to authenticate a given user with a given password. Returns the user name of the authenticated user or nil and an error message.

Auth:validate_token(username, token)

Validate an existing authentication token. This is used for allowing authentication via cookies. Returns user the name of the authenticated user.


Returns whether or not a given user is a new user, defined by the "recent" configuration parameter.

Auth:add_user(username, password, metadata)

Adds a user/password pair to the password file. Metadata is a table of additional values to be stored. Returns a boolean value indicating if the add was successful and also an error message if the add was not successful.

Auth:get_metadata(username, key)

Retrieves a piece of metadata for a specific user. (The key argument specifies what information we want about the user. For instance:

if auth:get_metadata(user, "IsAdmin") then ...