White dot for spacing only
The Dice Project


iFriend for its close friends

This document provides a quick guide to the mechanics of the iFriend system, and is targetted at those responsible for its care and feeding. Other users may be interested in the other iFriend documentation

Background

iFriend is implemented on top of our existing Cosign service. It uses the Cosign Friend PHP application produced by the University of Michigan to control the creation, and management of additional guest users. Both the Cosign, and Cosign Friend, code bases have been modified to support the creation of these guest accounts in a Kerberos realm - FRIEND.INF.ED.AC.UK. Accounts are given Kerberos principals determined by the user'ss email address with the @ sign replaced with a %.

Architecture

Users interact with the service through a set of PHP 5 scripts as provided by the cosign-friend RPM, and served by a standard Apache web server. These scripts perform the basic account creation, password modification and password reset actions, as well as providing an interface for local users to send invites, and an XMLRPC interface to allow programatic account creation by other services. The creation and reset interfaces are authenticated via an email handshake, the password change and invite interfaces are protected by cosign itself, and the XMLRPC interface is protected by SSL client certifcates in order to allow unattend use.

As in the standard Cosign Friend installation details of accounts created are stored in a local mysql database. However, the iFriend system does not store, or validate, passwords against this database. Instead, accounts are also created in the FRIEND.INF.ED.AC.UK KDC. KDC account creation is performed using the standard kadmin RPCs, using the Authen::Kerberos::Admin perl interface. kadmin authenticates these perl scripts using the friendserver principal which is stored in a keytab accessible only to the webserver. ACLs prevent this principal performing tasks other than those mentioned above.

Code

A number of pieces of code and other packages have been produced to support the iFriend service, and a number of changes have been made to the original University of Michigan code. This section details the code iFriend uses, and what considerations will be required when rebuilding it.

cosign

cosign-friend

All of these changes are in our local RPM. At the time of writing, none of them have been offered upstream.

dice-ifriend

This is a local package (stored in the DICE CVS repository) which contains all of the template pages for the iFriend system. If new cosign-friend releases are installed, it will be necessary to update the templates in this package. In addition, the package also provides three scripts which perform account management operations on the KDC, when called from within the cosign friend system.

lcfg-friend

This LCFG component configures the friend system. Using the mysql component, it creates the friend database and user. Through kadmin.local, it populates the keytab (/etc/friend.keytab) that the account management scripts use to talk to the KDC. It populates both the /etc/friend.conf configuration file used by the cosign friend web application, and provides a fragment of Apache configuration that can be used by the apacheconf component to produce a web server for the application.

Installation

Initial service installation is performed through the LCFG configuration, which will create all of the required databases. If the system is being rebuilt from scratch, then it will be necessary to establish a cross-realm link between INF.ED.AC.UK and FRIEND.INF.ED.AC.UK by creating krbtgt principals in both databases in the usual way.

Operation

As noted, iFriend is a PHP web application. The primary means of interaction is through a web server supporting PHP5. iFriend uses a mysql backend database to store details of newly created accounts, and a KDC to store the passwords for all of these accounts. It sends account creation emails through the sendmail running on the local host - these emails are sent from ifriend-noreply@inf.ed.ac.uk. There is no operational replication of either the web service, or the mysql database.

The iFriend service uses the FRIEND.INF.ED.AC.UK Kerberos realm - there are currently two KDCs for this service. The master KDC is held on the iFriend web server, with the slave on the other cosign machine. The KDC configuration is managed entirely through the standard lcfg-kerberos component, although it is a little different from our standard KDC configuration, as the realm (INF.ED.AC.UK) of these machines doesn't match the realm of the KDC running on them.

In order to minimise the code changes to the cosign-friend PHP application, KDC account creation, password change, and password reset are performed using external scripts. These scripts use the friendserver principal, stored in the /etc/friend.keytab keytab file, to authenticate to the KDC, and perform their operations using the standard kadmin interface.

Backups and Restoration

Backing up the service requires dumping the mysql database onto disk. This dump is then copied to a mirror server, from where the services-unit take care of spooling to tape. For security reasons, the KDC database is not backed up to tape, instead it is regularly syncronised with a remote slave server. The KDC stash file is not backed up, however paper copies of the KDC master key are held seperately in a secure location.

Restoring the KDC from the backup can be accomplished in the usual way, either restoring from a dump file, or bringing up a new slave KDC and promoting that to master. Before starting the restored KDC, the /etc/friend.keytab file should be either copied across, or deleted, whereupon it will be recreated by the friend component.

Restoring the MySQL service is a little more complicated, as it is important that the stashed database passwords match those in the restored database. If the service is being moved to a different host, the mysql backup file should be edited to replace instances of the previous hostname with the new one. The mysql service should be started, and the backup replayed into it using om mysql runcommand < backupfile. mysql should then be stopped, and the friend stashed password file (given by the friend.passwdstash resource) removed. The mysql root password (given by the file rootpwd in the directory mysql.datadir) should be replaced with the root password from the original database (paper copies of this are kept in secure locations). Starting the mysql and then the friend components will replace the friend password file with one containing the correct password.

User Management

User management should take care of itself. Bear in mind that the mysql database is only used for account creation and management operations - the cosign CGI just uses the KDC. Any manual deletion operations must be performed both on the KDC and on the mysql database. It is important to realise that deleting an account will not be enough to deny that user access - they can simply apply for another account from the same email address. If you want to deny access to a particular address, do not delete their account, but instead set it to "no tickets" on the KDC using the kadmin utility.


 : Units : Infrastructure : Documentation : IFriend 

Mini Informatics Logo - Link to Main Informatics Page
Please contact us with any comments or corrections.
Unless explicitly stated otherwise, all material is copyright The University of Edinburgh
Spacing Line