allura.lib.plugin

Allura plugins for authentication and project registration

class allura.lib.plugin.AdminExtension

A base class for extending the admin areas in Allura.

After extending this, expose the app by adding an entry point in your setup.py:

[allura.admin]
myadmin = foo.bar.baz:MyCustomAdmin
Variables:project_admin_controllers (dict) – Mapping of str (url component) to Controllers. Can be implemented as a @property function. The str url components will be mounted at /p/someproject/admin/ext/STR/ and will invoke the Controller.
update_project_sidebar_menu(sidebar_links)

Implement this function to modify the project sidebar. Check c.project if you want to limit when this displays (e.g. nbhd project, subproject, etc)

Parameters:sidebar_links (list of allura.app.SitemapEntry) – project admin side bar links
Return type:None
class allura.lib.plugin.AuthenticationProvider(request)

An interface to provide authentication services for Allura.

To use a new provider, expose an entry point in setup.py:

[allura.auth]
myprovider = foo.bar:MyAuthProvider

Then in your .ini file, set auth.method=myprovider

activate_user(user, **kw)

Activate user after registration

after_login(user, request)

This is a hook so that custom AuthenticationProviders can do things after a successful login.

by_username(username)

Find a user by username.

Return type:User or None
deactivate_user(user, **kw)

Deactivate user (== registation not confirmed)

Return list of pairs (url, label) with details about the user. Links will show up at admin user search page.

disable_user(user, **kw)

Disable user account

enable_user(user, **kw)

Enable user account

classmethod get(request)

returns the AuthenticationProvider instance for this request :rtype: AuthenticationProvider

get_last_password_updated(user)

Returns the date when the user updated password for a last time.

Parameters:user – a User
Return type:datetime
index_user(user)

Put here additional fields for user index in SOLR.

register_user(user_doc)

Register a user.

Parameters:user_doc – a dict with ‘username’ and ‘display_name’. Optionally ‘password’ and others
Return type:User
set_password(user, old_password, new_password)

Set a user’s password.

A provider implementing this method should store the timestamp of this change, either on user.last_password_updated or somewhere else that a custom get_last_password_updated method uses.

Parameters:user – a User
Return type:None
Raises:HTTPUnauthorized if old_password is not valid
upload_sshkey(username, pubkey)

Upload an SSH Key. Providers do not necessarily need to implement this.

Return type:None
Raises:AssertionError with user message, upon any error
user_by_project_shortname(shortname)
Parameters:str – shortname
Return type:user: a User
user_details(user)

Returns detailed information about user.

Parameters:user – a User
user_project_shortname(user)
Parameters:user – a User
Return type:str
user_registration_date(user)

Returns the date in which a user registered himself/herself on the forge.

Parameters:user – a User
Return type:datetime
validate_password(user, password)

Check that provided password matches actual user password

Return type:bool
class allura.lib.plugin.ImportIdConverter

An interface to convert to and from import_id values for indexing, searching, or displaying.

To provide a new converter, expose an entry point in setup.py:

[allura.import_id_converter] mysource = foo.bar:SourceIdConverter

Then in your .ini file, set import_id_converter=mysource

classmethod get()
Return type:ImportIdConverter
class allura.lib.plugin.LdapUserPreferencesProvider

Store preferences in LDAP, falling back to LocalUserPreferencesProvider

class allura.lib.plugin.LocalAuthenticationProvider(request)

Stores user passwords on the User model, in mongo. Uses per-user salt and SHA-256 encryption.

class allura.lib.plugin.LocalUserPreferencesProvider

The default UserPreferencesProvider, storing preferences on the User object in mongo.

class allura.lib.plugin.ProjectRegistrationProvider

Project registration services for Allura. This is a full implementation and the default. Extend this class with your own if you need to add more functionality.

To use a new provider, expose an entry point in setup.py:

[allura.project_registration]
myprovider = foo.bar:MyAuthProvider

Then in your .ini file, set registration.method=myprovider

The provider should expose an attribute, shortname_validator which is an instance of a FormEncode validator that validates project shortnames. The to_python() method of the validator should accept a check_allowed argument to indicate whether additional checks beyond correctness of the name should be done, such as whether the name is already in use.

best_download_url(project)

This is the url needed to render a download button. It should be overridden for your specific envirnoment

Return list of pairs (url, label) with details about the project. Links will show up at admin project search page

classmethod get()
Return type:ProjectRegistrationProvider
index_project(project)

Put here additional fields given project should be indexed by SOLR.

phone_verified(user, neighborhood)

Check if user has completed phone verification.

Returns True if one of the following is true:
  • phone verification is disabled

  • param user:has ‘admin’ access to :param neighborhood:
  • param user:is has ‘admin’ access for some project, which belongs

    to :param neighborhood:

  • phone is already verified for a :param user:

Otherwise returns False.

project_from_url(url)

Returns a tuple (project, error).

Where project is the Project instane parsed from url or None if project can’t be parsed. In that case error will be a string describing the error.

rate_limit(user, neighborhood)

Check the various config-defined project registration rate limits, and if any are exceeded, raise ProjectRatelimitError.

register_project(neighborhood, shortname, project_name, user, user_project, private_project, apps=None)

Register a new project in the neighborhood. The given user will become the project’s superuser.

registration_date(project)

Return the datetime the project was created.

validate_project(neighborhood, shortname, project_name, user, user_project, private_project)

Validate that a project can be registered, before it is

class allura.lib.plugin.SiteAdminExtension

A base class for extending the site admin area in Allura.

After extending this, expose the extension by adding an entry point in your setup.py:

[allura.site_admin]
myext = foo.bar.baz:MySiteAdminExtension
Variables:controllers (dict) – Mapping of str (url component) to Controllers. Can be implemented as a @property function. The str url components will be mounted at /nf/admin/STR/ and will invoke the Controller.
update_sidebar_menu(sidebar_links)

Change the site admin sidebar by modifying sidebar_links.

Parameters:sidebar_links (list of allura.app.SitemapEntry) – site admin side bar links
Return type:None
class allura.lib.plugin.ThemeProvider

Theme information for Allura. This is a full implementation and the default. Extend this class with your own if you need to add more functionality.

To use a new provider, expose an entry point in setup.py:

[allura.theme]
myprovider = foo.bar:MyThemeProvider

Then in your .ini file, set theme=mytheme

The variables referencing jinja template files can be changed to point at your own jinja templates. Use the standard templates as a reference, you should provide matching macros and block names.

For more information, see https://forge-allura.apache.org/p/allura/wiki/Themes%20in%20Allura/

Variables:icons – a dictionary of sized icons for each tool
app_icon_url(app, size)

returns the default icon for the given app (or non-app thing like ‘subproject’). Takes an instance of class Application, or else a string. Expected to be overriden by derived Themes.

classmethod get()
Return type:ThemeProvider
href(href, theme_name=None)

Build a full URL for a given resource path :param href: a path like css/site_style.css :param theme_name: defaults to current theme :return: a full URL

class allura.lib.plugin.UserPreferencesProvider

An interface for user preferences, like display_name and email_address

To use a new provider, expose an entry point in setup.py:

[allura.user_prefs]
myprefs = foo.bar:MyUserPrefProvider

Then in your .ini file, set user_prefs_storage.method=myprefs

additional_urls()

Returns a mapping of additional routes for AuthProvider.

By default, scans the provider for @expose()ed methods, which are added as pages with the same name as the method. Note that if you want the new pages to show up in the menu on the various auth pages, you will also need to add it to the list returned by AuthenticationProvider.account_navigation.

If you want to override this behavior, you can override this method and manually return a mapping of {page_name: handler, ...}. Note, however, that this could break future subclasses of your providers’ ability to extend the list.

For example: {‘newroute’, newroute_handler} will add ‘newroute’ attribute to the auth controller, which will be set to newroute_handler. newroute_handler can either be an @expose()ed method, or a controller that can dispatch further sub-pages.

newroute_handler must be decorated with @expose(), but does not have to live on the provider.

classmethod get()
Return type:UserPreferencesProvider
get_pref(user, pref_name)
Parameters:
  • user – a User
  • pref_name (str) –
Returns:

pref_value

Raises:

AttributeError if pref_name not found

set_pref(user, pref_name, pref_value)
Parameters:
  • user – a User
  • pref_name (str) –
  • pref_value
allura.lib.plugin.ldap_conn(who=None, cred=None)

Init & bind a connection with the given creds, or the admin creds if not specified. Remember to unbind the connection when done.

allura.lib.plugin.ldap_user_dn(username)

return a Distinguished Name for a given username