Merge pull request #23 from mike42/20-install-process

Update install process, README

.travis.yml

@@ -0,0 +1,22 @@
+---
+# Use Ubuntu 'trusty' distribution
+sudo: required
+dist: trusty
+
+language: php
+
+php:
+  - 5.6
+  - 7.0
+
+addons:
+  apt:
+    sources:
+    - sourceline: 'ppa:ansible/ansible'
+    packages:
+    - ansible
+
+script:
+  - (cd maintenance/demo-install && ansible-playbook -i inventory.local site.yml)
+...
+

README.md

@@ -1,119 +1,52 @@
-Auth
-====
-'Auth' is a scriptable Single Sign On (SSO) solution for organisations which have user accounts in lots of different places. It provides an interface to manage any number of user account databases centrally.
+# Auth Web [![Build Status](https://travis-ci.org/mike42/Auth.svg?branch=master)](https://travis-ci.org/mike42/Auth)
 
-Users can log in via a web portal to reset their password for all services, and view group membership.
+Auth Web is a system to manage complex user account management setups through a simple web interface.
 
-The administrative interface lets you modify accounts, groups, and organizational units via the web, and will create a queue of actions which are processed in the background.
+The aim of this project is to give every user the impression that they have exactly one user account in the organisation, no matter how complex the underlying infrastructure is. It does this by allowing administrators to link user accounts on different systems that are controlled by the same person, so that the person's access can be managed from one place. Each time an action is performed, Auth Web will interact with the relevant systems asynchronously to bring them up to speed.
 
-Requirements
-------------
-This code is designed to run on Debian GNU/Linux 7.0 (wheezy) and 8.0 (jessie).
+The use cases for this sort of web application include:
 
-Account databases supported:
+- manage access to systems that don't/can't authenticate centrally
+- set a user's password, display name, or group membership on all accounts at once
+- set up accounts according to updates to the staff database
+- add a web interface so that admins can reset passwords and unlock accounts on the go
 
-- OpenLDAP
-- Active Directory (all versions)
-- Google Apps, via the Directory API.
+The system ships with plugins for:
 
-Dependencies, and which component they are used with (useful for troubleshooting):
-- php5-ldap, for logging in via an LDAP or active directory server.
-- php5-cli for processing the Action Queue
+- LDAP (intended for UNIX or RADIUS accounts)
+- Microsoft Active Directory 
+- Google Apps, via the Google Data REST API
 
-Optional dependencies:
-- phpmyadmin, for managing the database and installing.
-- php5-curl, for the Google Apps service
-- php5-odbc and FreeTDS, for plugins which interact with Microsoft SQL Server
-
-Installation
-------------
-The installation steps here cover installing Auth as a standalone LDAP front-end.
-
-Install dependencies:
-
-        apt-get install git apache2 slapd mysql-server phpmyadmin php5-ldap php5-cli php5-curl libapache2-mod-php5 openssl ldap-utils
-
-Clone the repo into /usr/share/auth:
-
-        su
-        cd /usr/share
-        git clone --recursive https://github.com/mike42/Auth auth
-
-Configure apache! You need an ssl virtual host, with AllowOverride All set, mod_rewrite enabled, and its DocumentRoot at /var/www.
-
-These commands will link up your webserver:
-
-        cd /var/www
-        ln -s /usr/share/auth/www/a/ a
-        ln -s /usr/share/phpmyadmin/ phpmyadmin
-
-The above directories work with the following .htaccess file:
+## Requirements
 
-        # Rewrite rules for auth
-        RewriteEngine On
-        RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
-        RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-d
+This code is intended to run on the following platforms:
 
-        # Handle stylesheets and scripts
-        RewriteRule ^/?admin/css/(.*)$ /a/public/admin/css/$1 [PT,L,QSA]
-        RewriteRule ^/?admin/img/(.*)$ /a/public/admin/img/$1 [PT,L,QSA]
-        RewriteRule ^/?admin/js/(.*)$ /a/public/admin/js/$1 [PT,L,QSA]
+- The most recent stable release of Debian GNU/Linux
+- The most recent LTS release of Ubuntu GNU/Linux
 
-        # Handle everything else
-        RewriteRule ^/?admin/(.*)$ /a/admin.php?p=$1 [PT,L,QSA]
-        RewriteRule ^/?account/(.*)$ /a/account.php?p=$1 [PT,L,QSA]
-        RewriteRule ^/?assistant/(.*)$ /a/assistant.php?p=$1 [PT,L,QSA]
+Required software:
 
-If Auth is the only program that runs here, you might want to also make an index.php with this:
+- MySQL or MariaDB server
+- Apache webserver
+- PHP 5.6, with plugins: php5-ldap php5-cli
 
-        <?php
-        header('location: /account/');
+Optional software:
 
-Now import the schema into phpmyadmin, from maintenance/schema/auth.sql, and the default data from maintenance/schema/data/defaults.sql
-
-Now cd /usr/share/auth.
-
-Copy site.example/ to site/, and replace bg.jpg and logo.png with some company artwork, and config.php. Remembering database and LDAP settings, enter these in config.php.
-
-(Note for lock files: Debian 6 Uses /var/lock, not /var/run/lock)
-
-Open the database up and look at the 'service' table. If you are administering LDAP on localhost (this is the default set-up), then correct the domain name and password to make it work. 
-
-To prepare authqueue (a background processs that does all the heavy lifting), you should create its log file, with the right permissions. You could also get super crafty with rotating logs, if you are expecting to generate a lot of data:
-
-        touch /var/log/meta-auth.log
-        chown www-data /var/log/meta-auth.log
-
-To test the authqueue, run this, and pay close attention to any errors you see:
-
-        sudo -u www-data bash
-        cd /usr/share/auth/maintenance/bin
-        ./authqueue.php -x -v
-
-Apache/PHP/MySQL setup on Debian
---------------------------------
-The next steps are
-- Set up a SSL virtual host
-- Change MySQL timezone settings.
-
-Auth must run over SSL, for obvious security reasons. On an internal network, you can simply follow [these instructions](https://wiki.debian.org/Self-Signed_Certificate) to set up a Self-Signed Certificate.
+- phpmyadmin, may be used to perform the database setup through the web
+- php5-curl, for the Google Apps service
+- php5-odbc and FreeTDS, for plugins which interact with Microsoft SQL Server
 
-To use the .htaccess file above, you need to set "AllowOverride All" in apache2.conf, and then enable mod_rewrite:
+## Installation
 
-        a2enmod rewrite
-        service apache2 reload
+A standalone example setup is used for testing. Ansible will configure the app and database to manage an empty OpenLDAP domain. For notes on how to install this on a spare Debian-based machine, see the notes under `maintenance/demo-install/README.md`.
 
-Make MySQL timezone-aware with the [mysql_tzinfo_to_sql](http://dev.mysql.com/doc/refman/5.5/en/mysql-tzinfo-to-sql.html) tool.
+## Gotchas
 
-        mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql -p
+Web Auth does not know your LDAP schema, so by default it uses very basic data structures for groups and users. If you want to take advantage of extra LDAP features, then you should modify `ldap_service.php` to use the features in your schema.
 
-Caveats
--------
-Auth does not know your LDAP schema, so by default it uses very basic data structures for groups and users. If you want to take advantage of extra LDAP features, then you should modify ldap_service.php to suit your organization.
+Auth will attempt to align users' group membership and account locations. If it is asked to synchronise two services that are very different, the results are currently quite messy. Ensure that you have done a trial run against a fake system 
 
-Auth will attempt to bring different services "into line" with eachother in terms of group membership and account locations. This process will be annoying, and you should screen-capture your group membership so that you can fix it.
+## Credits
 
-Credits
--------
 - The default login background is modified from [this image](http://commons.wikimedia.org/wiki/File:Great_Barrier_Reef_105_%285383117759%29.jpg) on Wikimedia Commons, CC2.
 - The Google API [PHP client](https://code.google.com/p/google-api-php-client/) is included, and is under the Apache License.

maintenance/demo-install/README.md

@@ -0,0 +1,41 @@
+Auth demo install
+-------------------
+
+This directory contains an Ansible playbook for installing MariaDB, OpenLDAP and
+the Auth web stack on a single machine for demonstrating & testing Auth.
+
+The demo setup uses TLS with a self-signed certificate.
+
+## Customise
+
+Before you begin, you will need:
+
+- Root access to a target machine over SSH (Debian Jessie or Ubuntu Trusty)
+- A copy of Ansible installed on your local workstation
+
+## Customise
+
+Copy `inventory.example` to a new file called `inventory`, and update some
+values:
+
+- The hostname of the target box
+- The three install-time passwords
+
+If you have not used ansible before, then simply run `ssh-copy-id root@target.example`
+to avoid configuring password prompts.
+
+## Install
+
+```
+ansible-playbook -i inventory site.yml
+```
+
+## Use
+
+Access the application over HTTPS in a web browser.
+
+Log in as user `admin`, using the `ldap_password` that you set in the inventory.
+
+To get started quickly, locate "Utilities" -> "Directory Cleanup Tools" ->
+"Create dummy data".
+

maintenance/demo-install/inventory.example

@@ -0,0 +1,21 @@
+[auth-server]
+# The server to installl Auth on.
+auth.local ansible_connection=ssh ansible_user=root
+
+[all:vars]
+# Use something like `openssl rand -base64 15` to generate your own passwords
+# prior to deployment.
+
+# OpenLDAP server
+ldap_password = cNiZabG6BjRhaYTXnXbI
+ldap_domain = example.com
+ldap_domain_ldif = dc=example,dc=com
+ldap_admin = cn=admin,dc=example,dc=com
+
+# MySQL server
+mysql_host = localhost
+mysql_root_password = 0LxvzBIVcVTXaaQxorFN
+auth_db_name = auth
+auth_db_user = auth
+auth_db_pass = vuKWRbx5T9LJKb32s2Yb
+

maintenance/demo-install/inventory.local

@@ -0,0 +1,21 @@
+[auth-server]
+# The server to installl Auth on.
+localhost ansible_connection=local ansible_become=true ansible_become_user=root
+
+[all:vars]
+# Use something like `openssl rand -base64 15` to generate your own passwords
+# prior to deployment.
+
+# OpenLDAP server
+ldap_password = cNiZabG6BjRhaYTXnXbI
+ldap_domain = example.com
+ldap_domain_ldif = dc=example,dc=com
+ldap_admin = cn=admin,dc=example,dc=com
+
+# MySQL server
+mysql_host = localhost
+mysql_root_password = 0LxvzBIVcVTXaaQxorFN
+auth_db_name = auth
+auth_db_user = auth
+auth_db_pass = vuKWRbx5T9LJKb32s2Yb
+

maintenance/demo-install/roles/common/handlers/main.yml

@@ -0,0 +1,10 @@
+---
+- name: restart ntp
+  service: name=ntp state=restarted
+
+- name: restart iptables
+  service: name=iptables state=restarted
+
+- name: restart iptables
+  service: name=iptables state=restarted
+

maintenance/demo-install/roles/common/tasks/main.yml

@@ -0,0 +1,9 @@
+---
+- name: ntp is installed
+  apt: package=ntp state=present update_cache=yes
+  tags: ntp
+
+- name: ntp is running and enabled
+  service: name=ntp state=running enabled=yes
+  tags: ntp
+

maintenance/demo-install/roles/db/handlers/main.yml

@@ -0,0 +1,2 @@
+---
+

maintenance/demo-install/roles/db/tasks/main.yml

@@ -0,0 +1,45 @@
+---
+# MySQL install, based partly on http://stackoverflow.com/questions/16444306/ansible-idempotent-mysql-installation-playbook
+- name: mysql server is installed
+  apt: package=mariadb-server state=present update_cache=yes
+  tags: mysql
+
+- name: python-mysqldb is installed
+  apt: package=python-mysqldb state=present update_cache=yes
+  tags: mysql
+
+- name: mysql server is enabled
+  service: name=mysql enabled=yes state=started
+  tags: mysql
+
+- name: mysql root password is set for all root accounts
+  mysql_user: name=root host={{ item }} password={{ mysql_root_password }} priv=*.*:ALL,GRANT
+  with_items:
+    - "{{ ansible_hostname }}"
+    - 127.0.0.1
+    - ::1
+    - localhost
+  tags: mysql
+
+- name: copy .my.cnf file with root password credentials
+  template: src=my.cnf.j2 dest=/root/.my.cnf owner=root mode=0600
+  tags: mysql
+
+- name: delete anonymous mysql server user for localhost
+  action: mysql_user user="" state=absent
+  tags: mysql
+
+- name: remove the mysql test database
+  action: mysql_db db=test state=absent
+  tags: mysql
+
+- name: Create Application Database
+  mysql_db: name={{ auth_db_name }} state=present
+  tags: mysql
+
+- name: Create Application DB User
+  mysql_user: name={{ auth_db_user }} password={{ auth_db_pass }} priv=*.*:ALL host="localhost" state=present
+  tags: mysql
+
+# TODO ?? Probably not necessary
+# mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql -p

maintenance/demo-install/roles/db/templates/my.cnf.j2

@@ -0,0 +1,3 @@
+[client]
+user=root
+password={{ mysql_root_password }}

maintenance/demo-install/roles/ldap/tasks/main.yml

@@ -0,0 +1,45 @@
+---
+- name: OpenLDAP domain is set in debconf
+  debconf:
+    name: 'slapd'
+    question: '{{ item }}'
+    vtype: 'string'
+    value: '{{ ldap_domain }}'
+  with_items: [ 'slapd/domain', 'shared/organization' ]
+
+- name: openldap is installed
+  apt: package={{ item }} state=present
+  with_items:
+  - ldap-utils
+  - slapd
+
+- name: find current and expected account details
+  command: "{{ item }}"
+  changed_when: false
+  no_log: true
+  register: result
+  ignore_errors: True
+  with_items:
+  - slappasswd -s "{{ ldap_password }}"
+  - ldapsearch -H ldapi:// -LLL -Q -Y EXTERNAL -b "cn=config" "(olcRootDN={{ ldap_admin }})" dn olcRootPW
+  - ldapwhoami -vvv -H ldapi:// -D {{ ldap_admin }} -x -w "{{ ldap_password }}"
+
+- command: slapcat
+
+- name: expected account details setup applied to temp file
+  copy:
+    content: |
+      {{ result.results[1].stdout_lines[0] }}
+      changetype: modify
+      replace: olcRootPW
+      olcRootPW: {{ result.results[0].stdout_lines[0] }}
+    dest: ~/.ldap_set
+  when: result|failed
+
+- name: admin account details are up to date
+  shell: ldapmodify -H ldapi:// -Q -Y EXTERNAL < ~/.ldap_set
+  when: result|failed
+
+- name: temp file is cleaned up
+  file: dest="~/.ldap_set" state=absent
+

maintenance/demo-install/roles/web/handlers/main.yml

@@ -0,0 +1,10 @@
+---
+- name: restart iptables
+  service: name=iptables state=restarted
+
+- name: restart apache
+  service: name=apache2 state=restarted
+
+- name: reload apache
+  service: name=apache2 state=reloaded
+