Plug in API Auth

Plug-ins / [auth]

• type: required
• interface: plugins.abstract.auth.AbstractAuth
• client-side code: -
• purpose: user authentication, finding out user-available corpora

# AbstractAuth.anonymous_user()

returns a dict:

{'id': database_id, 'user': username, 'fullname': full_name}

# AbstractAuth.is_administrator(user_id)

arguments:

• user_id -- user database ID

returns True if the current user has administrator's privileges else False.

# AbstractAuth.validate_user(username, password)

returns a dict:

{'id': database_id, 'user': username, 'fullname': full_name}

Returns a dictionary containing core credentials (id, username, full name) of a user matching passed arguments. In case no valid user is found, then anonymous user credentials should be returned. Please note that anonymous user is recognized via config.xml's /kontext/global/anonymous_user_id which means you have to ensure that the id key is equal to that value in case of anonymous user.

# AbstractAuth.logout(session_id)

Changes current user's status to the anonymous user. Typically, this is done by writing new data into user's session. The method is not expected to return anything.

# AbstractAuth.canonical_corpname(corpname)

KonText introduces a convention that corpus_id can have a path-like prefix which represents a different Manatee registry file. This allows attaching a specially configured corpus to a user according to his access rights.

Example: let's say we have syn2010 and spec/syn2010 corpora where the latter has some limitations (e.g. user can explore only a small KWIC range). These two corpora are internally represented by two distinct Manatee registry files: (/path/to/registry/syn2010 and /path/to/registry/spec/syn2010). User cannot see the string spec/syn2010 anywhere in the interface (only in URL). By the term 'canonical' we mean the original id (= Manatee registry file name).

# AbstractAuth.permitted_corpora(user_id)

returns a dict canonical_corpus_id => actual_corpus_id

Provides corpora identifiers user can access.

# AbstractAuth.get_user_info(user_id)

Provides a dictionary containing all the data about a user. Sensitive information like password hashes, recovery questions etc. are not expected/required to be present there.

returns a dict user_info_key => value

# AbstractAuth.validate_new_password(password)

returns True if the password is OK else False

Tests whether provided password candidate matches required password properties (like length). If your implementation uses an external authentication page then you can skip this method.

# AbstractAuth.get_required_password_properties()

Returns a text describing what are the properties of a valid password (e.g. "min. 6 characters, at least one digit").

# AbstractAuth.update_user_password(user_id, password)

Updates user's password. The password is passed in a plain format which means that hashing/salting is expected to be performed by the plug-in itself.

# AbstractAuth.def get_login_url()

Returns a URL of the login action (because in general, it may be outside the application).

# AbstractAuth.get_logout_url()

Returns a URL of the logout action (because in general, it may be outside the application)

# AbstractAuth.revalidate(plugin_api)

arguments:

• plugin_api -- a controller.PluginApi instance

KonText calls this method (if it is provided by your plug-in) during session initialization. If an external service responds that remote session ticket is invalid (= outdated, incorrect), method revalidate should change user's session data to an "anonymous user".

Please note that in case this method raises an exception, KonText automatically sets the current user as 'anonymous' to prevent security issues.

# AbstractAuth.uses_internal_user_pages()

returns True if KonText is configured to use its own login/logout/user profile/etc. pages, else False must be returned.