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
- The Cosign CGI has been modified to support checking an incoming user
against multiple KDC databases. User verification relies upon there
being cross-realm trust defined between these KDCs. The patches to implement
this are currently in our local cosign RPM, they have been accepted
upstream, but are yet to appear in either the cosign CVS tree, or any
release.
- The cosign login page template has been modified to provide a link to
the iFriend service. This page is in the locally mainted dice-cosign-html
package.
cosign-friend
- As distributed the cosign friend code contains a number of bugs which we
have fixed in our local copy. These appear to have also been fixed in the
upstream CVS repository.
- It also contains references to University of
Michigan specific paths, and realm names, which have been replaced by
new configuration variables.
- Support for requiring a check box which must be ticked in order to create
an account has been added to the account creation script. (This box is used,
in our local templates, to require that the user accepts the Computing
Regulations).
- Finally, in order to support accounts on a KDC, support for calling
external scripts for each account management operation (create acccount,
reset password, change password) has been added.
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.
|
|
Please contact us with any
comments or corrections.
Unless explicitly stated otherwise, all material is
copyright The University of Edinburgh
|
|
