/ 
PlugAuth-0.23
River stage zero No dependents
/ PlugAuth::Guide::Server

NAME

PlugAuth::Guide::Server - Guide for setting up a PlugAuth server.

VERSION

version 0.23

DESCRIPTION

This document provides a quickstart guide for setting up a PlugAuth server using the default authentication and authorization plugins. In addition to installing PlugAuth you will need to have PlugAuth::Client installed which comes as a separate distribution.

Default

Here is a quick start for setting up PlugAuth with the default plugins.

  • create directory

    You will need to create directories for the server configuration as well as the authentication and authorization database. You can use the per-user configuration (~/etc/PlugAuth.conf) or the system-wide configuration (/etc/PlugAuth.conf). In this guide, we will use the per-user configuration.

    % mkdir ~/etc
% mkdir -p ~/var/plugauth

  • create configuration

    Create the configuration file ~/etc/PlugAuth.conf using your favorite editor.

    ---
% use File::HomeDir;
% my $home = File::HomeDir->my_home;
url: http://localhost:3000
user_file: <%= $home %>/var/plugauth/user.txt
group_file: <%= $home %>/var/plugauth/group.txt
resource_file: <%= $home %>/var/plugauth/resource.txt
host_file: <%= $home %>/var/plugauth/host.txt

    Note this configuration is a template using Mojo::Template and is in YAML format. In this example, I'm using File::HomeDir to dynamically find the user's home directory, so that if the user's home directory is moved, or a different user is used later the configuration does not need to be changed.

  • create database files

    Create empty database files for the users, groups, resources and hosts. To start out with they only need to be empty files:

    % touch ~/var/plugauth/{user,group,resource,host}.txt

  • run server

    Run the PlugAuth server using the built in Mojolicious web server. Note that the server will be running without authentication or authorization running so be sure it is listening only to localhost:

    % plugauth daemon -l http://localhost:3000

  • create admin user

    Create an admin user, and give that user permission to change passwords, and administrate users, groups and permissions:

    % plugauthclient create_user --user admin --password secret
--- ok
% plugauthclient grant admin change_password /user
--- ok
% plugauthclient grant admin accounts /
--- ok

    Make sure that the password is correct using the plugauthclient auth command.

    % plugauthclient auth
Username for  at localhost :  [default bob] admin
Password: ********
--- ok

  • stop server

    In the window you are running the PlugAuth daemon type Ctrl-C.

    % plugauth daemon -l http://localhost:3000
^C
%

  • configure

    Make PlugAuth authenticate and authorize against itself using the plug_auth configuration. Your PlugAuth.conf should look like this:

    ---
% use File::HomeDir;  my $home = File::HomeDir->my_home;
url: http://localhost:3000
user_file: <%= $home %>/var/plugauth/user.txt
group_file: <%= $home %>/var/plugauth/group.txt
resource_file: <%= $home %>/var/plugauth/resource.txt
host_file: <%= $home %>/var/plugauth/host.txt
plug_auth:
  url: http://localhost:3000

    (the last two lines having been added).

  • restart server

    Restart the PlugAuth server, this time optionally listening to multiple addresses now that it has been locked down and only the admin user can modify the authentication and authorization for the PlugAuth server.

    % plugauth daemon -l http://\*:3000

  • create user

    Create a regular user. This time PlugAuth should ask you for a username and password.

    % plugauthclient create_user --user foo --password bar
Username for "PlugAuth" at localhost :	[default bob] admin
Password: --- ok
% plugauthclient user
---
- admin
- foo

More Secure

Instead of creating the admin account using plugauthclient, you can use the Apache htpasswd command and a basic text editor.

  • create configuration

    Do as above, but create your configuration initially with plug_auth set in your PlugAuth.conf file:

    ---
% use File::HomeDir;  my $home = File::HomeDir->my_home;
url: http://localhost:3000
user_file: <%= $home %>/var/plugauth/user.txt
group_file: <%= $home %>/var/plugauth/group.txt
resource_file: <%= $home %>/var/plugauth/resource.txt
host_file: <%= $home %>/var/plugauth/host.txt
plug_auth:
  url: http://localhost:3000

  • create admin user

    Use htpasswd to create the admin user:

    % htpasswd -m ~/var/plugauth/user.txt admin
New password: 
Re-type new password: 
Adding password for user admin

    Note: If you have access to the user.txt file you can use this mechanism for creating users and changing passwords as an alternative to plugauthclient.

    Using your favorite text editor, add these lines to the ~/var/plugauth/resource.txt file:

    /user (change_password) : admin
/user (accounts) : admin
/group (accounts) : admin
/grant (accounts) : admin

LDAP

You can use an LDAP server for authentication instead of or in addition to the flat files provided by the default plugin. This requires PlugAuth::Plugin::LDAP, which is NOT included with the PlugAuth distribution.

  • create configuration

    Just like the default configuration, but add a ldap stanza to the configuration.

    ---
% use File::HomeDir;  my $home = File::HomeDir->my_home;
url: http://localhost:3000
user_file: <%= $home %>/var/plugauth/user.txt
group_file: <%= $home %>/var/plugauth/group.txt
resource_file: <%= $home %>/var/plugauth/resource.txt
host_file: <%= $home %>/var/plugauth/host.txt
plug_auth:
  url: http://localhost:3000
ldap:
  server: ldap://1.2.3.4:389
  dn: uid=%s, ou=people, dc=users, dc=foo, dc=com
  authoritative: 1

    Set authoritative to 1 to ignore the user.txt file for authentication (though it will still be used as a list of users), and set it to 0 to use both user.txt and LDAP for authentication.

Others

There are other plugins for details on how they work, see the plugin documentation.

PlugAuth::Plugin::DBIAuth, PlugAuth::Plugin::AuthenSimple. PlugAuth::Plugin::LDAP

SEE ALSO

PlugAuth

AUTHOR

Graham Ollis <gollis@sesda3.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by NASA GSFC.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.