Auth plugin

The auth plugin provides a basic permissions system and user management system. Before I get into the plugin itself, let's explore what that actually means and why it's necessary.

Permissions are necessary

User management is hard. You've got to be able to ensure that only the people that need access to things have access to them. In past versions of the bot, when it was IRC-only, it used user ranks on IRC channels as well as an override password to decide whether someone can do something. This is no longer viable - Other protocols don't necessarily make it obvious who has what rank and sometimes you may want to avoid showing that on protocols that do.

As a result, we had to think of another solution, and this is it. A robust permissions system allows you to give users the ability to create accounts and login to them, and to assign accounts (as well as groups of accounts) the permission to do individual things. So far, our system is pretty basic, but it's growing!

A note about permissions handlers

Right now, this plugin provides the only known permissions and user handlers. There are plugins which will break if a permissions handler is not present (though we're working on changing this). Even if you don't need permissions, you should still enable the permissions handler - The defaults are fairly secure (we think) and this will stop plugins breaking.

We're looking forward to seeing people write their own permissions handlers too. The general community of the Internet never ceases to amaze.

How to use this plugin

We'll go over this plugin in two separate stages - Configuration and usage

Configuration

The auth plugin is one of the only plugins that you will need to modify the data files for. It also has one configuration file.

• config/plugins/auth.yml - The general configuration file. This is just for enabling and disabling certain features.

  • use-superuser (defaults to yes) - Whether to enable the superadmin feature, which lets you assign users as superadmin (meaning they have all permissions)
  • use-auth (defaults to yes) - Whether to enable user management (Handling of logins, registrations, passwords, etc)
  • user-permissions (defaults to yes) - Whether to enable the permissions handler

• data/plugins/auth/blacklist.yml - This is a password blacklist. It includes the most used passwords of 2013 by default (you can remove them if you really want), and it also keeps a record of the passwords a user has tried to register with from within a channel so that they can't then use that password.

  • all - Contains the most used passwords of 2013, plus whatever other passwords you feel like adding to it. The aforementioned passwords are as follows. They're also in order of popularity, if you're into that sort of thing.
    • password, 123456, 12345678, 1234, qwerty, 12345, dragon, pussy, baseball, football, letmein, monkey, 696969, abc123, mustang, michael, shadow, master, jennifer, 111111
  • users - Contains blacklisted passwords per-user, for when someone tries to register in a channel (which should be discouraged for obvious reasons)

• data/plugins/auth/passwords.yml - This contains salted and hashed passwords for every registered user, as well as the default superuser account (more on that in the usage section). You usually don't have to edit this, but you may want to remove accounts from here if people have forgotten their password.

• data/plugins/auth/permissions.yml - This file contains all of your permissions setup, and is itself divided into two sections.

  • groups - This contains your permissions groups. This should always contain a group named default, which is what is used when a user first registers or a user isn't registered at all. It has the following layout..
    • <group name>
      • options - Not currently used, a plugin can use this to store arbitrary data about a group.
      • permissions - This is a list of permissions that are assigned to the group.
        • Default: auth.login, auth.logout, auth.register, auth.passwd, bridge.relay, urls.shorten, urls.title,
  • users - This contains permissions information for individual users.
    • <username>
      • group (defaults to default) - Specifies what group the user is in.
      • options - Plugins can use this to store arbitrary data about a user. It also contains the following option..
        • superadmin (defaults to false) - If the superuser feature is enabled, this option will give the user all permissions.
      • permissions - You can assign additional permissions per-user here, but this is usually empty.

Now that we've covered the configuration, let's move on to the plugin usage.

Usage

As of right now, you'll have to restart the bot to apply any configuration changes. This will be changed soon, though - it's being worked on right now.

Commands and permissions

• login <username> <password> - Login with your registered account. This should only ever be used in a private message.
  • Permission: auth.login
• logout - If you're logged into an account, you can logout with this command.
  • Permission: auth.logout
• register <username> <password> - Register an account. This should only ever be used in a private message, using this in a channel will blacklist the password you picked as well.
  • Permission: auth.register
• passwd <old password> <new password> - Change your password. You have to be logged in to do this. You can't change your password to a blacklisted password.
  • Permission: auth.passwd

Back to plugins | Home