LDAP Authentication Design

I. Essentials

• TCL in packages/acs-ldap-authentication
• Requirements document
• SQL File

II. Introduction

It is very common to have separate, but similar ACS installations, such as www.arsdigita.com and acs.arsdigita.com. As it is now, in order to use these sites you need to create a separate account on each site. Then you must remember the e-mail address and password you used for each site. You may have used the same e-mail address and password for both to make it easier to remember, but then if you ever want to change your password on one site then they'll be out of sync again.

ArsDigita, as the administrator of these two sites can use the LDAP authentication package to create "canonical accounts" that are shared between the sites. The canonical accounts are the authoritative source for a user's primary information such as e-mail address, password, first names, and last name. Each ACS installation (www.arsdigita.com and acs.arsdigita.com in this example) still have their own users table, but they use the LDAP authentication to keep their local user information fresh.

With LDAP Authentication enabled, when Joe User registers on www.arsdigita.com, a local entry is created as well as a canonical entry on the LDAP server. Then, when Joe tries to log into acs.arsdigita.com, the LDAP server will be queried and Joe's information will be found. Additionally, a local entry will be created on acs.arsdigita.com with Joe's info. If Joe were to change his password on acs.arsdigita.com, the password on the LDAP server would also be updated, which implicitly propagates the change to www.arsdigita.com. Finally, ArsDigita could at a later point enable LDAP Authentication on wimpy.arsdigita.com, and everyone with an account on acs.arsdigita.com/www.arsdigita.com could then log into wimpy.

III. Historical Considerations

IV. Competitive Analysis

...

V. Design Tradeoffs

VIII. API

The API to the permissions system consists of a few well-known tables, plus a pair of PL/SQL procedures and a pair of tcl functions.

Tables

acs_methods, acs_privileges, and acs_privilege_method_rules manage the set of permissions in the system. A package will add to these three tables to introduce new permissions into the system at package installation time.

The main table for queries is acs_object_party_method_map, which contains (object, party, method) triples for all allowed operations in the system.

Also of interest for queries is acs_permissions, which lists directly granted privileges. Neither acs_object_party_method_map (which is a view) nor acs_permissions should be updated directly.

PL/SQL Procedures

acs_permissions.grant_permission introduces new permissions for an object. It should be given an (object, party, privilege) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure is:

procedure grant_permission (
  object_id    acs_permissions.object_id%TYPE,
  grantee_id   acs_permissions.grantee_id%TYPE,
  privilege    acs_permissions.privilege%TYPE
);

acs_permissions.revoke_permission removes a permission entry given a triple. It always succeeds--if a permission does not exist, nothing changes. The interface for this procedure is:

procedure revoke_permission (
  object_id    acs_permissions.object_id%TYPE,
  grantee_id   acs_permissions.grantee_id%TYPE,
  privilege    acs_permissions.privilege%TYPE
);

These procedures are defined in permissions-create.sql

Tcl Procedures

Two tcl procedures provide a simple call for the "can this user perform this method on this object" query. One returns true or false, the other presents an error page.

To receive a true or false value, tcl code should call:

ad_permission_p $object_id $object_type $method -user_id $user_id

If the user_id argument is left out, then the currently logged in user is checked. To create an error page, tcl code should call:

ad_require_permission $object_id $object_type $method

These procedures are defined in acs-permissions-procs.tcl.

VII. Data Model Discussion

The LDAP Authentication data model contains only one table - ldap_attributes. This table keeps a list of LDAP attributes for individual ACS objects. Currently there are just two columns - object_id and dn. With these columns, we can map a Distinguished Name (dn) to any ACS object in the database.

The bulk of the functionality of the LDAP data model comes from its PL/SQL functions. These functions are wrappers around Java functions that perform specific operations on the LDAP server. The functions are:

acs_ldap.authenticate

Given a DN and password, determines whether the password is valid for that DN.

acs_ldap.change_password

Given a DN and password, updates the password on the LDAP server of the entry designated by the DN.

acs_ldap.get_attribute

Given a DN and attribute name, query the entry on the LDAP server for its value of the specified attribute. This function only supports entries that return exactly one attribute value.

acs_ldap.get_dn_from_email

Given an email address, queries the LDAP server for an entry whose mail attribute matches the email address. If successul, returns the DN of the matched entry.

acs_ldap.add_user

Takes in a DN and first_names, last_name, email, and password values. It then creates an entry on the LDAP server with the given DN and other attribute values.

url

This is the url of the ldap server. e.g) ldap://yourldapserver.com:389

rootdn

This is the DN of a user on the LDAP server that has permissions to query, modify, and add entries on the server.

rootpw

The password for the user specified by the rootdn

basedn

The base object in the LDAP server where queries start. e.g.) o=arsdigita.com

security_method

The level of security to use. Valid values include 'none', 'simple', and 'strong'. However, many LDAP servers do not support 'strong' authentication.

VIII. User Interface

All users of the permissions system are the same at the user-interface level. If you have the administer_privileges method permission on an object, then you may edit privileges for that object with the user interface.

The user interface currently provides a list of all granted permissions on the object. If the user wishes to revoke privileges, she may select a set of grants, choose revoke, confirm their deletion, and be returned to the same page after those privileges have been revoked.

Granting currently works by providing a list of all possible permissions and a list of all parties in the system. In the future, of course, some search mechanism is necessary. After choosing privileges to grant, the user is returned to the edit privileges for one object screen.

If it makes sense, the system will also display a checkbox which the user may select to toggle whether permissions are inherited from the object's context.

There are a number of potential future enhancements for this UI.

IX. Configuration/Parameters

There are no configuration options for the permissions system.

X. Acceptance Tests

...

XI. Future Improvements/Areas of Likely Change

The most important future changes to the system are likely to be to the user interface. Here's a list of likely changes:

• There should probably be a page displaying a list of all objects for which the current user is allowed to administer privileges.
• Users should probably be able to view the permissions on any object, or perhaps on objects which they have the "read_permissions" method. This would allow them to see what grants are effecting their objects through inheritance.

XII. Authors

System creators

Lars Pind

Dennis Gregorovic

System owner

Dennis Gregorovic

Documentation author

Dennis Gregorovic

VII. Revision History