The Decomate Authentication Broker Contents 1. Background 1.1 The Authentication Broker model 1.2 How the AuthBroker works 2. Requirements for setting up an Authbroker 3. Configuring an AuthBroker 3.1 Planning configuration 3.2 The Authbroker authrc file 3.3 The Authbroker configuration file - general configuration parameters 3.4 The Authbroker configuration file - authentication service parameters 3.5 The Authbroker configuration file - group definitions 3.6 The Authbroker configuration file - directory service parameters 3.7 The Authbroker configuration file - directory field calculations 3.8 Example Authbroker configuration 4. Technical information 4.1 logonRequest message format 4.2 logonResponse message format 4.3 Directory information fields 4.4 Writing new libraries 1. Background 1.1 The Authentication Broker model The Decomate Authentication Broker (AuthBroker) is an extensible modular component of the Decomate system which queries one or more institutional services to obtain user verification and directory data, presenting it in a unified format and allowing the main Decomate software to treat any local user information in the same way, disguising all the technical and organisational idiosyncrasies. Each Decomate system is intended to be run as a service to users of a particular library, itself providing the benefits of interconnection to the collections of other libraries and suppliers at a lower level. For Decomate, the AuthBroker enables easier portability to further libraries that wish to adopt it as a solution. The main advantage to end-users of this approach is that a new service (such as Decomate) can request from them a username and password combination that they already know, such as the one they use to login to the campus network, or their library card number and the password or PIN-number that they use with it. They don't have to learn (or write down, insecurely) yet another password for each new service that the university or library creates. 1.2 How the AuthBroker works Figure 1 shows the four independent actors in a typical AuthBroker transaction, and the sequence of messages that pass between them. In this example the application is the central Broker component of a Decomate system, which runs as a HTTP-daemon (i.e. a sort of special-purpose Webserver), communicating directly with the Web-browser of the end-user. The end-user is a LSE student, in this case using the same name and password that she uses to login to PCs on the campus network. Decomate has defined an XML DTD1, named "Xrep", for all internal messages between system components. The Decomate Broker sends an Xrep logonRequest message to the AuthBroker, containing the submitted username and password. Figure 1: messages between actors in a typical AuthBroker transaction ----------- -------- ----------- ------------- |Web browser| |Decomate| |AuthBroker | |External auth| | | |Broker | | | |& dir | | | |Broker | | | |services | ----------- -------- ----------- -------------- |User enters|-------->| | | | | | |username & |HTTP POST| | | | | | |password | | | | | | | ----------- -------- ----------- ------------- | | |CGI |------------>|(Go through| | | | | |parsing | Xrep |services in| | | | | | |logonRequest |order) | | | | | | | message | | | | ----------- -------- ----------- ------------- | | | | |SQL select |------>|SQL | | | | | |statement | |auth. target | ----------- -------- ----------- ------------- | | | | |(Next |<------|0 rows match | | | | | |service) | | | ----------- -------- ----------- ------------- | | | | |Auth. |------>|NT network | | | | | |request | SMB | | ----------- -------- ----------- ------------- | | | | |(Approp. |<------|Affirmative | | | | | |directory | SMB |response | | | | | |service) | | | ----------- -------- ----------- ------------- | | | | |Directory |------>|LDAP | | | | | |request | LDAP |directory | | | | | | | |target | ----------- -------- ----------- ------------- | | | |<------------|Field and |<------| | | | | | Xrep |group | LDAP | | | | | |logonResponse|calculation| | | | | | | message | | | | ----------- -------- ----------- ------------- |Page |<--------|Create | | | | | |displayed | HTTP |Web page| | | | | | |text/HTML| | | | | | ----------- -------- ----------- ------------- The AuthBroker in this example is installed at LSE, to service the LSE Decomate system and other library services for LSE users. AuthBroker recognises two types of external service: authentication services (such as SMB) which check the credentials of a user, and directory services (such as LDAP, or any SQL-compliant relational database system) which return information about a user. Each authentication service has a corresponding directory service, which contains further information about the users that the authentication service trusts. AuthBroker 'knows' about the authentication and directory services it can use from a configuration file which specifies where and how to communicate with them. Multiple authentication regimes may be available, so they are checked in sequence (in the order specified by the configuration file) until one returns a positive match. The configuration for the example AuthBroker tells it to look first in an SQL database (containing records for some non-LSE users), and then in the LSE NT network login table. It fails to find the student in the SQL database, but finds her name and a matching password for her NT network login. When this happens, the directory service which corresponds to this authentication service is queried for the information it has about the user, using the appropriate protocol (specified in the configuration file). The results which come from this directory service are parsed, based on the configuration file entries for the directory service, to complete the list of fields that Decomate uses (which are based on one of the standard LDAP schemas). The configuration can specify for each service how the 'native' data fields it returns should be mapped into standard elements, and if necessary Perl-like regular expressions to be applied to non-standard field contents to transform them. This collection of fields is then parsed using the configuration parameters of the authentication service, to make a list of groups to which the user is to be assigned, thus determining the rights a user has from their directory information held by the institution. The collection of fields and the list of groups are returned to the socket in an Xrep logonResponse message, indicating either a successful login and containing standard-form directory information and a list of rights-groups to which the user is entitled; or a failed login which was not matched by any available service. In addition to interactive user logins, AuthBroker can support 'batch' access to user directory information, for example by the Decomate Current Awareness Service robot when it is performing searches on behalf of users, and needing directory information such as their email addresses for notification. Currently, the backend service types that AuthBroker will connect to are SQL databases, LDAP servers, and NT network authentication (via SMB). New backend service handlers can be created when needed, provided that enough information is available about an API to the service. Since an institution might want to use different services for different users (for example, different LDAP servers for staff and students, SQL databases containing privileged users or external library users), the AuthBroker will go through the list of services in its configuration file until one accepts the user. Thus multiple sources can be supported (at an expense of overall response speed). An identified user is given a collection of rights-groups, derived from the authentication method through which they successfully accessed the system and on the directory information retrieved. These groups can then be used to determine the access rights granted to the user. A Perl library has been written to handle the application program end of Xrep transactions with the AuthBroker, to facilitate the implementation support for new service types. AuthBrokers are run as Unix 'socket' services, with those under test currently exchanging request and response messages with applications in plain text. This is not as insecure as it might sound, because this transmission will normally occur between two processes on the same physical server, or at least within an institutional network (and so can be firewall protected). Transmission of passwords between the end-user and the application (i.e. potentially over open Internet connections) can be easily secured by the application of SSL to the Webserver running the application. 2. Requirements for setting up an Authbroker The SQL parts of the authentication broker and action logger require the DBI perl library and the appropriate DBD driver for the database being used with the system to be installed. The LDAP parts of the authentication broker require the NET::LDAP and Convert::BER (must be recent version) to be installed. The SMB parts of the authentication broker require the Authen::Smb module. These can be retrieved from CPAN (http://www.cpan.org) and its mirrors. 3. Configuring an Authbroker The major task involved in setting up an Authentication Broker is configuration. It is, unfortunately, necessary to have a complex configuration in order to deal with the many different ways in which institutions have set up existing authentication/directory services. 3.1 Planning configuration It is important to plan the configuration before you start. To do this, you need to think about two things: what services are available and how you want to use them for authentication. The more you understand about your institution's services, the easier it will be to configure the Authbroker. For example, you will need to know what fields are returned by an LDAP server, and how they are formatted. The script test-sql.pl which comes with the authentication broker can be used to test connections to SQL databases. The way in which you want to use your local services for authentication affects Authbroker configuration is because the Authbroker works through the authentication services it knows about in the order given in the configuration file. This means that a slow service which is listed early in the configuration can make the whole system unusably slow, and many services are far slower to time out or reject an authentication request than they are to accept one. In general, this means that the services which will authenticate large numbers of users should be listed first, as this will minimise the time it takes to respond affirmatively to their attempted logins. If, however, you want to set up a separate service for privileged users (e.g. a small database), this should probably come first, so that it authenticates the special users rather than the generic service. 3.2 The Authbroker authrc file This is run by the Authbroker on startup to determine basic parameters such as the location of the config file. It should not be renamed, and should be in the same directory as the main executable auth.pl. You should edit the values in this file with care. This file requires the parameters to be set as valid perl code. The parameters are: $debug - whether debugging output is generated. This may be useful for finding errors. Set to 0 for no debugging, 1 for debugging. 2 runs as a command line script, taking input from a text file, rather than running as a daemon and taking input from the Decomate broker. $configfile - the location of the config file. This should be a full Unix pathname. It should be set correctly by the Decomate configuration process. @libdirs - directories containing library files. These should be set correctly by the Decomate configuration process. $buzz - location of file containing extra passwords for test accounts. This only needs to be set if you wish to use this tester. 3.3 The Authbroker configuration file - general configuration parameters The main configuration file for the Authbroker is in an XML style format. Comments can be placed in the configuration file in the form of lines starting with #. (They come in very useful as reminders of the purpose of each of multiple authentication services.) The general configuration parameters are likely to be at the top of the configuration file (though they can occur anywhere). Valid tags and their meanings are: port - port number bound to by authentication broker when operating as a daemon errlog - error log file name (full Unix path) defaultgroup - group to put all users into whatever authentication service permits them access, may be repeated as often as required (this is useful for groups like 'allusers' etc.) timeout - default timeout period for successful authentication. 3.4 The Authbroker configuration file - authentication service parameters The chunks of configuration data relating to individual authentication services are subtags of the repeatable authservice tag. These tags are: name - name of service. This field is used to identify which authentication service authenticated a user. It is needed for batch access (because the batch process will not know the password for the users it needs to obtain directory information about). It is mandatory, and must be unique. type - type of service, used to work out which module to call. Supported values are buzz,ldap,smb,sql. For a new service module, it should match the name of the appropriate file in the library directory. Mandatory. dirmethod - name of corresponding directory service to use to get directory information. Note that more than one authentication service can use the same directory service. Mandatory. timeout - how long to wait for this service to time out. Patchily implemented. location - place at which authentication service can be accessed, usually a machine name and port number. For SMB services, the network machine name is used rather than the Internet domain name. Mandatory. authname - user name used by the Authbroker to connect to authentication service, where necessary. authpassword - password used by the Authbroker to connect to authentication service, where necessary. usernamefield - fieldname in authentication service to match username against, where appropriate. This should include the table name in the case of an SQL target (in the form table.field). passwordfield - fieldname in authentication service to match password against, where appropriate. For a SQL target, this is assumed to be in the same table as the username. passwordcase - how to transform password case to match value accepted by authentication service. Accepted values lc (lower case), uc (upper case) and mc (mixed case - no transformation). group - name of group to put any user authenticated by this method into. Repeatable. usertimeout - how many seconds a user authenticated by this method can leave Decomate unused without being challenged to authenticate again. If omitted, defaults to the generic timeout period. groupdef - structured group of tags which define how to put a user into groups. See 3.5 for details. Repeatable. 3.5 The Authbroker configuration file - group definitions A user who successfully authenticates is assigned a set of groups, which are then used by the Decomate broker to decide on the rights that user has (i.e. which services and which operations the user is allowed to access/perform). The operation of working out which group to put a user into is carried out via the groupdef tags for each authservice. field - fieldname returned by directory service to be used as the basis for the group name. Mandatory. matches - A perl regular expression which means that the group is only given to the user if the field value matches the expression. Use of brackets to define $(integer) expressions is allowed. Mandatory. group - name of group to put user into. The use of perl $(integer) expressions is allowed. Mandatory. 3.6 The Authbroker configuration file - directory service parameters The chunks of configuration data relating to individual directory services are subtags of the repeatable dirservice tag. These tags are: name - used to match directory services to authentication services. Mandatory. type - type of service, used to work out which module to call. Supported values are buzz,ldap,smb,sql (note that smb always returns empty directory information). For a new service module, it should match the name of the appropriate file in the library directory. Note that more than one authentication service can use the same directory service. Mandatory. timeout - how long to wait for this service to time out. Patchily implemented. location - place at which directory service can be accessed, usually a machine name and port number. Mandatory. dirauthname - user name used by the Authbroker to connect to directory service, where necessary. authpassword - password used by the Authbroker to connect to directory service, where necessary. base - for LDAP directory services, the base filter to apply to searches. usernamefield - fieldname in directory service to match username against. This should include the table name in the case of an SQL target (in the form table.field). Mandatory. fieldcalc - Group of tags which make directory information field calculations. See 3.7 for details. Repeatable. 3.7 The Authbroker configuration file - directory field calculations Decomate uses a fixed list of field names for the transfer of directory information between the Authbroker and the Decomate broker (see 4.3 for the list). Information from the directory service needs to be transformed to be put into these fields before it is passed back to the broker, and this is done through the information in the structured fieldcalc group of tags. Any field name, regardless of whether it is on the list or not, can be used; this can come in useful if you want to pass information back to the Authbroker for group calculations which is not part of the usual information returned. (This has been used, for example, to service a guest registration scheme, where the service registered for is stored in a SQL database, and this is returned as part of the group information to the Decomate broker.) decofield - fieldname for the Decomate broker. Multiple calculations can be included for the same decofield, in which case they are performed in the order in which they are placed in the configuration file, overwriting earlier values. (This can be used to deal with special cases, which should be placed after the general case.) servicefield - fieldname returned by the directory service. This is case sensitive. transformation - perl regular expression (as used by tr) to transform the value of the service field into the value to be returned to the broker. $(number) expressions are permitted. The right hand side expression is evaluated to make this possible, and so literal strings should be enclosed in double quotes. No transformation is made if this field is omitted. value - value to send back to the broker as the value of the field. Mandatory if servicefield is omitted. 3.8 Example Authbroker configuration The example shows how to create a simple SQL table for authenticating special users, and then gives an authbroker configuration file for accessing it. You'll need to install DBI and the DBD driver for whichever SQL database you have. Some configuration also needs to be done in the authrc file (so it knows where to find its configuration file and so on). To create the table use the command create table directory ( cn varchar(30) not null, personaltitle varchar(5), initials varchar(5), middlename varchar(10), givenname varchar(10), sn varchar(10), o varchar(30), l varchar(10), c varchar(10), ou varchar(20), postaladdress varchar(100), postcode varchar(9), status varchar(10), mail varchar(30), userid varchar(10) not null, password varchar(10) ); You may want to change some of the column sizes to fit in with your local environment. You'll need to plug in details of the location of your SQL server and the authentication used to access it (check the DBI documentation for details to work out what this should be if necessary), and you'll need to change some of the details of the institution and so on in the sample configuration file but you should be able to do this from what's already there. -------------------------------------------------------------------------------- # Configuration file for authentication broker - with comments # # port - port number bound to by authentication broker when operating as a daemo n 1252 # errlog - error log file name /usr/users/simon/decomate/dev/autherror.log # defaultgroup - group to put all users into, may be repeated People # authservice - contains details about an authentication service, and may be # repeated; contains further structure: # - name - name of service # - type - type of service, used to work out which module to call # - dirmethod - corresponding directory service to gain directory info about # successfully authenticated users # - group - group to put all users authenticated by this method into, may be # repeated # - location - generally either server:port or filepath; for sql type should # be of form dbtype:location # for an sql service, we want the fieldnames to include the table name. However, # the username and password should be taken from the same table, since we need # to be sure that they go together! LSEoracle sql LSEoracle # for an oracle database, the timeout is specified in the tnsnames.ora file # used on connection 120 Oracle:orcl London School of Economics directory.usesrid directory.password mc 600 decotest allin1 O LSE LSEusers # dirservice - contains details about an directory service, and may be repeated; # contains further structure: # - name - name of service # - type - type of service, used to work out which module to call # - groupdef - definition of group information for this directory service, # may be repeated; contains further structure: # - field - fieldname containing information # - matches - regular expression to match value of field against # - groupname - group to put user in if field matches the regular # expression LSEoracle sql # for an oracle database, the timeout is specified in the tnsnames.ora file # used on connection 120 Oracle:orcl # dirauthname is used to authenticate to directory service decotest # dirauthpassword is used to authenticate to directory service allin1 # field containing user's id directory.usersrid CN cn INITIALS initials SN sn L l C c STATUS status MAIL SN sn L l C c STATUS status MAIL mail -------------------------------------------------------------------------------- 4. Technical information This section contains the information required to interoperate with the Authbroker and to write new authentication/directory libraries. 4.1 logonRequest message format LogonRequest XML format message sent by Decomate broker to Authbroker. Inside the Xrep tag which marks out all Decomate messages, the logonRequest tag contains the following elements. userid - Username of user. Mandatory. password - Password of user. Optional, but mandatory for user requests. authmethod - Authentication method which knows about this user. For use in batch requests. Should not be part of user requests, but mandatory otherwise. ipAddress - Location of user. Optional. domain - NT network domain for user. Optional; for use in SMB authentication. 4.2 logonResponse message format XML format message sent by Decomate broker to Authbroker. Inside the Xrep tag which marks out all Decomate messages, the logonResponse tag contains the following elements. group - list of groups of which user is a member. Repeatable. userinfo - Contains directory information about the user structured as described in 4.3. Mandatory where no diagnostic. diagnostic - Gives reason why logon fails. timeout - user time out in seconds. 0 means never timeout. 4.3 Directory information fields Note: the Decomate broker does not insist that these fields be defined. However, certain functions will require these pieces of information to work properly (e.g. billing for document delivery services). cn - Full name. Mandatory. personaltitle - title. initials - initials. middlename - middle name. givenname - given name. sn - Last name. Mandatory. o - Organisation (institution). Mandatory. l - City location. c - country. ou - Organisational department. Mandatory. postalAddress - street address. Mandatory. postcode - post code. Mandatory. status - status (e.g. staff, postgraduate, undergraduate). Mandatory. mail - E-mail address. Mandatory. dirsource - Source of directory information. authsource - Source of authentication. Mandatory. 4.4 Writing new libraries Libraries are written in perl, and should contain at least two subroutines. Where the library is name.pl, the subroutines should by name_auth, name_authdir and name_dir. The middle one of these is used when it is possible to carry out authentication and directory access with the same operation (as is the case with SQL and LDAP); this is called when the names of the authentication and directory services match. Parameters for the three subroutines are passed as a hashref, with the following keys: name_auth: location, timeout, username, usernamefield, password, passwordfield, authname (to authenticate to service), authpassword (to authenticate to service), domain (for SMB). name_authdir: location, timeout, username, usernamefield, password, passwordfield, base (for LDAP), authname (to authenticate to service), authpassword (to authenticate to service), domain (for SMB). name_dir: location, timeout, username, usernamefield, base (for LDAP), authname (to authenticate to service), authpassword (to authenticate to service). name_auth returns 0 for success, 1 for failure. name_authdir returns a two element arrayref, the first element being a name_auth response and the second a name_dir response. name_dir returns a hashref with the keys being the fieldnames for the directory service.