Interfaces

The PluggableAuthService plugins in this package implement interfaces defined in the PluggableAuthService package.

interface Products.PluggableAuthService.interfaces.plugins.IAuthenticationPlugin

Map credentials to a user ID.

authenticateCredentials(credentials)

credentials -> (userid, login)

o ‘credentials’ will be a mapping, as returned by IExtractionPlugin.

o Return a tuple consisting of user ID (which may be different

from the login name) and login

o If the credentials cannot be authenticated, return None.

interface Products.PluggableAuthService.interfaces.plugins.ICredentialsResetPlugin

Callback: user has logged out.

resetCredentials(request, response)

Scribble as appropriate.

interface Products.PluggableAuthService.interfaces.plugins.IGroupEnumerationPlugin

Allow querying groups by ID, and searching for groups.

o ???: can these be done by a single plugin?

enumerateGroups(id=None, exact_match=False, sort_by=None, max_results=None, **kw)

-> (group_info_1, … group_info_N)

o Return mappings for groups matching the given criteria.

o ‘id’ in combination with ‘exact_match’ true, will

return at most one mapping per supplied ID (‘id’ may be a sequence).

o If ‘exact_match’ is False, then ‘id’ may be treated by

the plugin as “contains” searches (more complicated searches may be supported by some plugins using other keyword arguments).

o If ‘sort_by’ is passed, the results will be sorted accordingly.

known valid values are ‘id’ (some plugins may support others).

o If ‘max_results’ is specified, it must be a positive integer,

limiting the number of returned mappings. If unspecified, the plugin should return mappings for all groups satisfying the criteria.

o Minimal keys in the returned mappings:

‘id’ – (required) the group ID

‘pluginid’ – (required) the plugin ID (as returned by getId())

‘properties_url’ – (optional) the URL to a page for updating the

group’s properties.

‘members_url’ – (optional) the URL to a page for updating the

principals who belong to the group.

o Plugin must ignore unknown criteria.

o Plugin may raise ValueError for invalid critera.

o Insufficiently-specified criteria may have catastrophic

scaling issues for some implementations.

interface Products.PluggableAuthService.interfaces.plugins.IGroupsPlugin

Determine the groups to which a user belongs.

getGroupsForPrincipal(principal, request=None)

principal -> (group_1, … group_N)

o Return a sequence of group names to which the principal

(either a user or another group) belongs.

o May assign groups based on values in the REQUEST object, if present

interface Products.PluggableAuthService.interfaces.plugins.IPropertiesPlugin

Return a property set for a user.

getPropertiesForUser(user, request=None)

user -> empty dict

o User will implement IPropertiedUser.

o Plugin should return a dictionary or an object providing

IPropertySheet.

o Plugin may scribble on the user, if needed (but must still

return a mapping, even if empty).

o May assign properties based on values in the REQUEST object, if

present

interface Products.PluggableAuthService.interfaces.plugins.IRoleAssignerPlugin

Assign a role to an identified principal

doAssignRoleToPrincipal(principal_id, role)

Create a principal/role association in a Role Manager

o Return a Boolean indicating whether the role was assigned or not

doRemoveRoleFromPrincipal(principal_id, role)

Remove a principal/role association from a Role Manager

o Return a Boolean indicating whether the role was removed or not

interface Products.PluggableAuthService.interfaces.plugins.IRoleEnumerationPlugin

Allow querying roles by ID, and searching for roles.

enumerateRoles(id=None, exact_match=False, sort_by=None, max_results=None, **kw)

-> (role_info_1, … role_info_N)

o Return mappings for roles matching the given criteria.

o ‘id’ in combination with ‘exact_match’ true, will

return at most one mapping per supplied ID (‘id’ may be a sequence).

o If ‘exact_match’ is False, then ‘id’ may be treated by

the plugin as “contains” searches (more complicated searches may be supported by some plugins using other keyword arguments).

o If ‘sort_by’ is passed, the results will be sorted accordingly.

known valid values are ‘id’ (some plugins may support others).

o If ‘max_results’ is specified, it must be a positive integer,

limiting the number of returned mappings. If unspecified, the plugin should return mappings for all roles satisfying the criteria.

o Minimal keys in the returned mappings:

‘id’ – (required) the role ID

‘pluginid’ – (required) the plugin ID (as returned by getId())

‘properties_url’ – (optional) the URL to a page for updating the

role’s properties.

‘members_url’ – (optional) the URL to a page for updating the

principals to whom the role is assigned.

o Plugin must ignore unknown criteria.

o Plugin may raise ValueError for invalid critera.

o Insufficiently-specified criteria may have catastrophic

scaling issues for some implementations.

interface Products.PluggableAuthService.interfaces.plugins.IRolesPlugin

Determine the (global) roles which a user has.

getRolesForPrincipal(principal, request=None)

principal -> (role_1, … role_N)

o Return a sequence of role names which the principal has.

o May assign roles based on values in the REQUEST object, if present.

interface Products.PluggableAuthService.interfaces.plugins.IUpdatePlugin

Allow the user or the application to update the user’s properties.

updateUserInfo(user, set_id, set_info)

Update backing store for ‘set_id’ using ‘set_info’.

interface Products.PluggableAuthService.interfaces.plugins.IUserAdderPlugin

Create a new user record in a User Manager

doAddUser(login, password)

Add a user record to a User Manager, with the given login

and password. It is up to the implementation to determine if the login is used as user id as well.

o Return a Boolean indicating whether a user was added or not

interface Products.PluggableAuthService.interfaces.plugins.IUserEnumerationPlugin

Allow querying users by ID, and searching for users.

o ???: can these be done by a single plugin?

enumerateUsers(id=None, login=None, exact_match=False, sort_by=None, max_results=None, **kw)

-> (user_info_1, … user_info_N)

o Return mappings for users matching the given criteria.

o ‘id’ or ‘login’, in combination with ‘exact_match’ true, will

return at most one mapping per supplied ID (‘id’ and ‘login’ may be sequences).

o If ‘exact_match’ is False, then ‘id’ and / or login may be

treated by the plugin as “contains” searches (more complicated searches may be supported by some plugins using other keyword arguments).

o If ‘sort_by’ is passed, the results will be sorted accordingly.

known valid values are ‘id’ and ‘login’ (some plugins may support others).

o If ‘max_results’ is specified, it must be a positive integer,

limiting the number of returned mappings. If unspecified, the plugin should return mappings for all users satisfying the criteria.

o Minimal keys in the returned mappings:

‘id’ – (required) the user ID, which may be different than

the login name

‘login’ – (required) the login name

‘pluginid’ – (required) the plugin ID (as returned by getId())

‘editurl’ – (optional) the URL to a page for updating the

mapping’s user

o Plugin must ignore unknown criteria.

o Plugin may raise ValueError for invalid criteria.

o Insufficiently-specified criteria may have catastrophic

scaling issues for some implementations.

updateEveryLoginName(quit_on_first_error=True)

Update login names of all users to their canonical value.

This should be done after changing the login_transform property of PAS.

You can set quit_on_first_error to False to report all errors before quitting with an error. This can be useful if you want to know how many problems there are, if any.

updateUser(user_id, login_name)

Update the login name of the user with id user_id.

The plugin must return True (or any truth value) to indicate a successful update, also when no update was needed.

When updating a login name makes no sense for a plugin (most likely because it does not actually store login names) and it does not do anything, it must return None or False.