user supplied access restrictions on community servers

This article describes an XML-RPC API for the Python Community Server to allow users to set up access restrictions on their blogs. The reason to do so are for example to protect your backup directory from unauthorized access or to set up some restricted categories.

Changes to the API

0.2b: fixed too short underline

0.2a: fixed typo in getUserListForGroup prototype

0.2: changed location combination

0.1: initial release

Some conventions of this API

All functions that can be called need the user number as the first parameter and the MD5 hash of the password as the second parameter. All functions return a structure with at least the flError and message members. Those are defined in the same way as with the xmlStorageSystem: if flError is true, message carries a human readable description of the error.

The namespace for this functions is accessRestrictions.

How access restrictions work

You define a list of users and a list of locations. Additionally you define a list of groups, add users to those groups and add those groups to locations. So you have a hierarchy of location, group and user.

If a visitor accesses an URL, the community server checks the path element of that URL (with the common prefix for that users path removed!) against all defined locations regexp. For every matching location, it checks all groups. For every group attached to a matching location, it checks all attached users.

So the user needs to give a user and password that can be looked up in the user database and is attached to a group that itself is attached to one of the matching locations. For all matching locations at least one group needs to be found that includes the logged in user.

An example: you have set up the location backup with the regexp /backup/. You have defined the group admin (and have attached that to location backup) and that includes the user owner with password blah. If you now access http://community.server.com/user/1234567/backup/, the server checks the path element /backup/ (since it removes the common prefix of /user/1234567 from the URL) against the location list. Since the location backup matches, the visitor must provide a user that's attached to group admin, and this is owner with password blah.

If there are several locations matching, the visitor must provide a user/password combination that satifies all of the matching locations (locations are combined by logical AND).

The API functions

The following API functions are available. Every function has documentation of a prototype, a short description and the result structure members that are special to this function.

setUser(blogid, blogpwd, username, password)

This function defines a user or sets the password for an already defined user. The password is never stored in clear, it's stored as the md5 hash. The function returns just the flError and message elements.

delUser(blogid, blogpwd, username)

This function deletes a user from the user database. A user can only be deleted if it isn't referenced in any group. The function returns flError and message.

getUserList(blogid, blogpwd)

This function returns a list of usernames that are currently defined. The list is returned as structure member userlist. The list is a list of structures whose only member currently is name with the user name.

setGroup(blogid, blogpwd, groupname)

This function defines a group. A group is used to group users together to connect them with locations. This function returns flError and message.

addUserToGroup(blogid, blogpwd, groupname, username)

This function attaches an user to a group. This function returns flError and message.

delUserFromGroup(blogid, blogpwd, groupname, username)

This function detaches a user from a group. It returns flError and message.

delGroup(blogid, blogpwd, groupname)

This function deletes a group. A group can only be deleted if it is not attached to any location. This function returns flError and message.

getGroupList(blogid, blogpwd)

This function returns the group list as member grouplist (beside the standard flError and message). The grouplist is a list of structures. Each structure has the members name and userlist. The userlist member has the same format as with getUserList.

getUserListForGroup(blogid, blogpwd, groupname)

This function returns the same values as getUserList, only that the users are filtered so that only users attached to the given group are returned.

setLocation(blogid, blogpwd, locationname, regexp)

This function defines a restricted location. The regexp is a regular expression that is matched against URL path elements. What exactly a regular expression is depends on the community server. The Python Community Server uses the re module. This function returns flError and message.