# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.controllers.admin.auth_settings

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

pluggable authentication controller for RhodeCode

:created_on: Nov 26, 2010

:author: akesterson

"""

import pprint

import logging

import formencode.htmlfill

import traceback

from pylons import request, response, session, tmpl_context as c, url

from pylons.controllers.util import abort, redirect

from pylons.i18n.translation import _

from sqlalchemy.exc import DatabaseError

from kallithea.lib import helpers as h

from kallithea.lib.compat import json, formatted_json

from kallithea.lib.base import BaseController, render

from kallithea.lib.auth import LoginRequired, HasPermissionAllDecorator

from kallithea.lib import auth_modules

from kallithea.model.forms import AuthSettingsForm

from kallithea.model.db import Setting

from kallithea.model.meta import Session

log = logging.getLogger(__name__)

class AuthSettingsController(BaseController):

    @LoginRequired()

    @HasPermissionAllDecorator('hg.admin')

    def __before__(self):

        super(AuthSettingsController, self).__before__()

    def __load_defaults(self):

        c.available_plugins = [

            'kallithea.lib.auth_modules.auth_container',

            'kallithea.lib.auth_modules.auth_ldap',

            'kallithea.lib.auth_modules.auth_crowd',

        ]

        c.enabled_plugins = Setting.get_auth_plugins()

    def index(self, defaults=None, errors=None, prefix_error=False):

        self.__load_defaults()

        _defaults = {}

        # default plugins loaded

        formglobals = {

        }

        formglobals.update(Setting.get_auth_settings())

        formglobals["plugin_settings"] = {}

        formglobals["auth_plugins_shortnames"] = {}

        _defaults["auth_plugins"] = formglobals["auth_plugins"]

        for module in formglobals["auth_plugins"]:

            plugin = auth_modules.loadplugin(module)

            plugin_name = plugin.name

            formglobals["auth_plugins_shortnames"][module] = plugin_name

            formglobals["plugin_settings"][module] = plugin.plugin_settings()

            for v in formglobals["plugin_settings"][module]:

                fullname = ("auth_" + plugin_name + "_" + v["name"])

                if "default" in v:

                    _defaults[fullname] = v["default"]

                # Current values will be the default on the form, if there are any

                setting = Setting.get_by_name(fullname)

                if setting:

                    _defaults[fullname] = setting.app_settings_value

        # we want to show , seperated list of enabled plugins

        _defaults['auth_plugins'] = ','.join(_defaults['auth_plugins'])

        if defaults:

            _defaults.update(defaults)

        formglobals["defaults"] = _defaults

        # set template context variables

        for k, v in formglobals.iteritems():

            setattr(c, k, v)

        log.debug(pprint.pformat(formglobals, indent=4))

        log.debug(formatted_json(defaults))

        return formencode.htmlfill.render(

            render('admin/auth/auth_settings.html'),

            defaults=_defaults,

            errors=errors,

            prefix_error=prefix_error,

            encoding="UTF-8",

            force_defaults=True,

        )

    def auth_settings(self):

        """POST create and store auth settings"""

        self.__load_defaults()

        _form = AuthSettingsForm(c.enabled_plugins)()

        log.debug("POST Result: %s" % formatted_json(dict(request.POST)))

        try:

            form_result = _form.to_python(dict(request.POST))

            for k, v in form_result.items():

                if k == 'auth_plugins':

                    # we want to store it comma separated inside our settings

                    v = ','.join(v)

                log.debug("%s = %s" % (k, str(v)))

                setting = Setting.create_or_update(k, v)

                Session().add(setting)

            Session().commit()

            h.flash(_('Auth settings updated successfully'),

                       category='success')

        except formencode.Invalid, errors:

            log.error(traceback.format_exc())

            e = errors.error_dict or {}

            return self.index(

                defaults=errors.value,

                errors=e,

                prefix_error=False)

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('error occurred during update of auth settings'),

                    category='error')

        return redirect(url('auth_home'))

:license: GPLv3, see LICENSE.md for more details.

"""

import time

import logging

import traceback

import formencode

from sqlalchemy import func, or_

from formencode import htmlfill

from pylons import request, tmpl_context as c, url

from pylons.controllers.util import redirect

from pylons.i18n.translation import _

from kallithea.lib import helpers as h

from kallithea.lib.auth import LoginRequired, NotAnonymous, AuthUser

from kallithea.lib.base import BaseController, render

from kallithea.lib.utils2 import generate_api_key, safe_int

from kallithea.lib.compat import json

from kallithea.model.db import Repository, PullRequest, PullRequestReviewers, \

    UserEmailMap, UserApiKeys, User, UserFollowing

from kallithea.model.forms import UserForm, PasswordChangeForm

from kallithea.model.user import UserModel

from kallithea.model.repo import RepoModel

from kallithea.model.api_key import ApiKeyModel

from kallithea.model.meta import Session

log = logging.getLogger(__name__)

class MyAccountController(BaseController):

    """REST Controller styled on the Atom Publishing Protocol"""

    # To properly map this controller, ensure your config/routing.py

    # file has a resource setup:

    #     map.resource('setting', 'settings', controller='admin/settings',

    #         path_prefix='/admin', name_prefix='admin_')

    @LoginRequired()

    @NotAnonymous()

    def __before__(self):

        super(MyAccountController, self).__before__()

    def __load_data(self):

        c.user = User.get(self.authuser.user_id)

        if c.user.username == User.DEFAULT_USER:

            h.flash(_("You can't edit this user since it's"

                      " crucial for entire application"), category='warning')

            return redirect(url('users'))

    def _load_my_repos_data(self, watched=False):

        if watched:

            admin = False

            repos_list = [x.follows_repository for x in

                          Session().query(UserFollowing).filter(

                              UserFollowing.user_id ==

                              self.authuser.user_id).all()]

        else:

            admin = True

            repos_list = Session().query(Repository)\

                         .filter(Repository.user_id ==

                                 self.authuser.user_id)\

                         .order_by(func.lower(Repository.repo_name)).all()

        repos_data = RepoModel().get_repos_as_dict(repos_list=repos_list,

                                                   admin=admin)

        #json used to render the grid

        return json.dumps(repos_data)

    def my_account(self):

        """

        GET /_admin/my_account Displays info about my account

        """

        # url('my_account')

        c.active = 'profile'

        self.__load_data()

        c.perm_user = AuthUser(user_id=self.authuser.user_id,

                               ip_addr=self.ip_addr)

        c.extern_type = c.user.extern_type

        c.extern_name = c.user.extern_name

        defaults = c.user.get_dict()

        update = False

        if request.POST:

            _form = UserForm(edit=True,

                             old_data={'user_id': self.authuser.user_id,

                                       'email': self.authuser.email})()

            form_result = {}

            try:

                post_data = dict(request.POST)

                post_data['new_password'] = ''

                post_data['password_confirmation'] = ''

                form_result = _form.to_python(post_data)

                # skip updating those attrs for my account

                skip_attrs = ['admin', 'active', 'extern_type', 'extern_name',

                              'new_password', 'password_confirmation']

                #TODO: plugin should define if username can be updated

                    # forbid updating username for external accounts

                    skip_attrs.append('username')

                UserModel().update(self.authuser.user_id, form_result,

                                   skip_attrs=skip_attrs)

                h.flash(_('Your account was updated successfully'),

                        category='success')

                Session().commit()

                update = True

            except formencode.Invalid, errors:

                return htmlfill.render(

                    render('admin/my_account/my_account.html'),

                    defaults=errors.value,

                    errors=errors.error_dict or {},

                    prefix_error=False,

                    encoding="UTF-8")

            except Exception:

                log.error(traceback.format_exc())

                h.flash(_('Error occurred during update of user %s') \

                        % form_result.get('username'), category='error')

        if update:

            return redirect('my_account')

        return htmlfill.render(

            render('admin/my_account/my_account.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False

        )

    def my_account_password(self):

        c.active = 'password'

        self.__load_data()

        if request.POST:

            _form = PasswordChangeForm(self.authuser.username)()

            try:

                form_result = _form.to_python(request.POST)

                UserModel().update(self.authuser.user_id, form_result)

                Session().commit()

                h.flash(_("Successfully updated password"), category='success')

            except formencode.Invalid as errors:

                return htmlfill.render(

                    render('admin/my_account/my_account.html'),

                    defaults=errors.value,

                    errors=errors.error_dict or {},

                    prefix_error=False,

                    encoding="UTF-8")

            except Exception:

                log.error(traceback.format_exc())

                h.flash(_('Error occurred during update of user password'),

                        category='error')

        return render('admin/my_account/my_account.html')

    def my_account_repos(self):

        c.active = 'repos'

        self.__load_data()

        #json used to render the grid

        c.data = self._load_my_repos_data()

        return render('admin/my_account/my_account.html')

    def my_account_watched(self):

        c.active = 'watched'

        self.__load_data()

        #json used to render the grid

        c.data = self._load_my_repos_data(watched=True)

        return render('admin/my_account/my_account.html')

    def my_account_perms(self):

        c.active = 'perms'

        self.__load_data()

        c.perm_user = AuthUser(user_id=self.authuser.user_id,

                               ip_addr=self.ip_addr)

        return render('admin/my_account/my_account.html')

    def my_account_emails(self):

        c.active = 'emails'

        self.__load_data()

        c.user_email_map = UserEmailMap.query()\

            .filter(UserEmailMap.user == c.user).all()

        return render('admin/my_account/my_account.html')

    def my_account_emails_add(self):

        email = request.POST.get('new_email')

        try:

            UserModel().add_extra_email(self.authuser.user_id, email)

            Session().commit()

            h.flash(_("Added email %s to user") % email, category='success')

        except formencode.Invalid, error:

            msg = error.error_dict['email']

            h.flash(msg, category='error')

        except Exception:

# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.controllers.admin.users

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Users crud controller for pylons

:created_on: Apr 4, 2010

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH.

:license: GPLv3, see LICENSE.md for more details.

"""

import logging

import traceback

import formencode

from pylons import response

from formencode import htmlfill

from pylons import request, session, tmpl_context as c, url, config

from pylons.controllers.util import redirect

from pylons.i18n.translation import _

from sqlalchemy.sql.expression import func

import kallithea

from kallithea.lib.exceptions import DefaultUserException, \

    UserOwnsReposException, UserCreationError

from kallithea.lib import helpers as h

from kallithea.lib.auth import LoginRequired, HasPermissionAllDecorator, \

    AuthUser, generate_api_key

from kallithea.lib import auth_modules

from kallithea.lib.base import BaseController, render

from kallithea.model.api_key import ApiKeyModel

from kallithea.model.db import User, UserEmailMap, UserIpMap, UserToPerm

from kallithea.model.forms import UserForm, CustomDefaultPermissionsForm

from kallithea.model.user import UserModel

from kallithea.model.meta import Session

from kallithea.lib.utils import action_logger

from kallithea.lib.compat import json

from kallithea.lib.utils2 import datetime_to_time, str2bool, safe_int

log = logging.getLogger(__name__)

class UsersController(BaseController):

    """REST Controller styled on the Atom Publishing Protocol"""

    @LoginRequired()

    @HasPermissionAllDecorator('hg.admin')

    def __before__(self):

        super(UsersController, self).__before__()

        c.available_permissions = config['available_permissions']

    def index(self, format='html'):

        """GET /users: All items in the collection"""

        # url('users')

        c.users_list = User.query().order_by(User.username)\

                        .filter(User.username != User.DEFAULT_USER)\

                        .order_by(func.lower(User.username))\

                        .all()

        users_data = []

        total_records = len(c.users_list)

        _tmpl_lookup = kallithea.CONFIG['pylons.app_globals'].mako_lookup

        template = _tmpl_lookup.get_template('data_table/_dt_elements.html')

        grav_tmpl = lambda user_email, size: (

                template.get_def("user_gravatar")

                .render(user_email, size, _=_, h=h, c=c))

        username = lambda user_id, username: (

                template.get_def("user_name")

                .render(user_id, username, _=_, h=h, c=c))

        user_actions = lambda user_id, username: (

                template.get_def("user_actions")

                .render(user_id, username, _=_, h=h, c=c))

        for user in c.users_list:

            users_data.append({

                "gravatar": grav_tmpl(user. email, 20),

                "raw_name": user.username,

                "username": username(user.user_id, user.username),

                "firstname": user.name,

                "lastname": user.lastname,

                "last_login": h.fmt_date(user.last_login),

                "last_login_raw": datetime_to_time(user.last_login),

                "active": h.boolicon(user.active),

                "admin": h.boolicon(user.admin),

                "extern_type": user.extern_type,

                "extern_name": user.extern_name,

                "action": user_actions(user.user_id, user.username),

            })

        c.data = json.dumps({

            "totalRecords": total_records,

            "startIndex": 0,

            "sort": None,

            "dir": "asc",

            "records": users_data

        })

        return render('admin/users/users.html')

    def create(self):

        """POST /users: Create a new item"""

        # url('users')

        user_model = UserModel()

        user_form = UserForm()()

        try:

            form_result = user_form.to_python(dict(request.POST))

            user_model.create(form_result)

            usr = form_result['username']

            action_logger(self.authuser, 'admin_created_user:%s' % usr,

                          None, self.ip_addr, self.sa)

            h.flash(_('Created user %s') % usr,

                    category='success')

            Session().commit()

        except formencode.Invalid, errors:

            return htmlfill.render(

                render('admin/users/user_add.html'),

                defaults=errors.value,

                errors=errors.error_dict or {},

                prefix_error=False,

                encoding="UTF-8")

        except UserCreationError, e:

            h.flash(e, 'error')

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during creation of user %s') \

                    % request.POST.get('username'), category='error')

        return redirect(url('users'))

    def new(self, format='html'):

        """GET /users/new: Form to create a new item"""

        # url('new_user')

        return render('admin/users/user_add.html')

    def update(self, id):

        """PUT /users/id: Update an existing item"""

        # Forms posted to this method should contain a hidden field:

        #    <input type="hidden" name="_method" value="PUT" />

        # Or using helpers:

        #    h.form(url('update_user', id=ID),

        #           method='put')

        # url('user', id=ID)

        c.active = 'profile'

        user_model = UserModel()

        c.user = user_model.get(id)

        c.extern_type = c.user.extern_type

        c.extern_name = c.user.extern_name

        c.perm_user = AuthUser(user_id=id, ip_addr=self.ip_addr)

        _form = UserForm(edit=True, old_data={'user_id': id,

                                              'email': c.user.email})()

        form_result = {}

        try:

            form_result = _form.to_python(dict(request.POST))

            skip_attrs = ['extern_type', 'extern_name']

            #TODO: plugin should define if username can be updated

                # forbid updating username for external accounts

                skip_attrs.append('username')

            user_model.update(id, form_result, skip_attrs=skip_attrs)

            usr = form_result['username']

            action_logger(self.authuser, 'admin_updated_user:%s' % usr,

                          None, self.ip_addr, self.sa)

            h.flash(_('User updated successfully'), category='success')

            Session().commit()

        except formencode.Invalid, errors:

            defaults = errors.value

            e = errors.error_dict or {}

            defaults.update({

                'create_repo_perm': user_model.has_perm(id,

                                                        'hg.create.repository'),

                'fork_repo_perm': user_model.has_perm(id, 'hg.fork.repository'),

                '_method': 'put'

            })

            return htmlfill.render(

                render('admin/users/user_edit.html'),

                defaults=defaults,

                errors=e,

                prefix_error=False,

                encoding="UTF-8")

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during update of user %s') \

                    % form_result.get('username'), category='error')

        return redirect(url('edit_user', id=id))

    def delete(self, id):

        """DELETE /users/id: Delete an existing item"""

        # Forms posted to this method should contain a hidden field:

        #    <input type="hidden" name="_method" value="DELETE" />

        # Or using helpers:

        #    h.form(url('delete_user', id=ID),

        #           method='delete')

        # url('user', id=ID)

        usr = User.get_or_404(id)

        try:

            UserModel().delete(usr)

            Session().commit()

            h.flash(_('Successfully deleted user'), category='success')

        except (UserOwnsReposException, DefaultUserException), e:

            h.flash(e, category='warning')

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('An error occurred during deletion of user'),

                    category='error')

        return redirect(url('users'))

    def show(self, id, format='html'):

        """GET /users/id: Show a specific item"""

        # url('user', id=ID)

        User.get_or_404(-1)

    def edit(self, id, format='html'):

        """GET /users/id/edit: Form to edit an existing item"""

        # url('edit_user', id=ID)

        c.user = User.get_or_404(id)

        if c.user.username == User.DEFAULT_USER:

            h.flash(_("You can't edit this user"), category='warning')

            return redirect(url('users'))

        c.active = 'profile'

        c.extern_type = c.user.extern_type

        c.extern_name = c.user.extern_name

        c.perm_user = AuthUser(user_id=id, ip_addr=self.ip_addr)

        defaults = c.user.get_dict()

        return htmlfill.render(

            render('admin/users/user_edit.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False)

    def edit_advanced(self, id):

        c.user = User.get_or_404(id)

        if c.user.username == User.DEFAULT_USER:

            h.flash(_("You can't edit this user"), category='warning')

            return redirect(url('users'))

        c.active = 'advanced'

        c.perm_user = AuthUser(user_id=id, ip_addr=self.ip_addr)

        umodel = UserModel()

        defaults = c.user.get_dict()

        defaults.update({

            'create_repo_perm': umodel.has_perm(c.user, 'hg.create.repository'),

            'create_user_group_perm': umodel.has_perm(c.user,

                                                      'hg.usergroup.create.true'),

            'fork_repo_perm': umodel.has_perm(c.user, 'hg.fork.repository'),

        })

        return htmlfill.render(

            render('admin/users/user_edit.html'),

            defaults=defaults,

            'py_version': <python version>,

            'platform': <platform type>,

            'kallithea_version': <rhodecode version>

          }

          error :  null

        """

        return Setting.get_server_info()

    def get_user(self, apiuser, userid=Optional(OAttr('apiuser'))):

        """

        Get's an user by username or user_id, Returns empty result if user is

        not found. If userid param is skipped it is set to id of user who is

        calling this method. This command can be executed only using api_key

        belonging to user with admin rights, or regular users that cannot

        specify different userid than theirs

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: user to get data for

        :type userid: Optional(str or int)

        OUTPUT::

            id : <id_given_in_input>

            result: None if user does not exist or

                    {

                        "user_id" :     "<user_id>",

                        "api_key" :     "<api_key>",

                        "api_keys":     "[<list of all api keys including additional ones>]"

                        "username" :    "<username>",

                        "firstname":    "<firstname>",

                        "lastname" :    "<lastname>",

                        "email" :       "<email>",

                        "emails":       "[<list of all emails including additional ones>]",

                        "ip_addresses": "[<ip_addresse_for_user>,...]",

                        "active" :      "<bool: user active>",

                        "admin" :       "<bool: user is admin>",

                        "extern_name" : "<extern_name>",

                        "extern_type" : "<extern type>

                        "last_login":   "<last_login>",

                        "permissions": {

                            "global": ["hg.create.repository",

                                       "repository.read",

                                       "hg.register.manual_activate"],

                            "repositories": {"repo1": "repository.none"},

                            "repositories_groups": {"Group1": "group.read"}

                         },

                    }

            error:  null

        """

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # make sure normal user does not pass someone else userid,

            # he is not allowed to do that

            if not isinstance(userid, Optional) and userid != apiuser.user_id:

                raise JSONRPCError(

                    'userid is not the same as your user'

                )

        if isinstance(userid, Optional):

            userid = apiuser.user_id

        user = get_user_or_error(userid)

        data = user.get_api_data()

        data['permissions'] = AuthUser(user_id=user.user_id).permissions

        return data

    @HasPermissionAllDecorator('hg.admin')

    def get_users(self, apiuser):

        """

        Lists all existing users. This command can be executed only using api_key

        belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        OUTPUT::

            id : <id_given_in_input>

            result: [<user_object>, ...]

            error:  null

        """

        result = []

        users_list = User.query().order_by(User.username) \

            .filter(User.username != User.DEFAULT_USER) \

            .all()

        for user in users_list:

            result.append(user.get_api_data())

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_user(self, apiuser, username, email, password=Optional(''),

                    firstname=Optional(''), lastname=Optional(''),

                    active=Optional(True), admin=Optional(False),

        """

        Creates new user. Returns new user object. This command can

        be executed only using api_key belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param username: new username

        :type username: str or int

        :param email: email

        :type email: str

        :param password: password

        :type password: Optional(str)

        :param firstname: firstname

        :type firstname: Optional(str)

        :param lastname: lastname

        :type lastname: Optional(str)

        :param active: active

        :type active: Optional(bool)

        :param admin: admin

        :type admin: Optional(bool)

        :param extern_name: name of extern

        :type extern_name: Optional(str)

        :param extern_type: extern_type

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "created new user `<username>`",

                      "user": <user_obj>

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "user `<username>` already exist"

            or

            "email `<email>` already exist"

            or

            "failed to create user `<username>`"

          }

        """

        if UserModel().get_by_username(username):

            raise JSONRPCError("user `%s` already exist" % (username,))

        if UserModel().get_by_email(email, case_insensitive=True):

            raise JSONRPCError("email `%s` already exist" % (email,))

        if Optional.extract(extern_name):

            # generate temporary password if user is external

            password = PasswordGenerator().gen_password(length=8)

        try:

            user = UserModel().create_or_update(

                username=Optional.extract(username),

                password=Optional.extract(password),

                email=Optional.extract(email),

                firstname=Optional.extract(firstname),

                lastname=Optional.extract(lastname),

                active=Optional.extract(active),

                admin=Optional.extract(admin),

                extern_type=Optional.extract(extern_type),

                extern_name=Optional.extract(extern_name)

            )

            Session().commit()

            return dict(

                msg='created new user `%s`' % username,

                user=user.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user `%s`' % (username,))

    @HasPermissionAllDecorator('hg.admin')

    def update_user(self, apiuser, userid, username=Optional(None),

                    email=Optional(None),password=Optional(None),

                    firstname=Optional(None), lastname=Optional(None),

                    active=Optional(None), admin=Optional(None),

                    extern_type=Optional(None), extern_name=Optional(None),):

        """

        updates given user if such user exists. This command can

        be executed only using api_key belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: userid to update

        :type userid: str or int

        :param username: new username

        :type username: str or int

        """

        Given a user object (which may be null), username, a plaintext password,

        and a settings object (containing all the keys needed as listed in settings()),

        authenticate this user's login attempt.

        Return None on failure. On success, return a dictionary of the form:

            see: RhodeCodeAuthPluginBase.auth_func_attrs

        This is later validated for correctness

        """

        raise NotImplementedError("not implemented in base class")

    def _authenticate(self, userobj, username, passwd, settings, **kwargs):

        """

        Wrapper to call self.auth() that validates call on it

        :param userobj: userobj

        :param username: username

        :param passwd: plaintext password

        :param settings: plugin settings

        """

        auth = self.auth(userobj, username, passwd, settings, **kwargs)

        if auth:

            return self._validate_auth_return(auth)

        return auth

    def _validate_auth_return(self, ret):

        if not isinstance(ret, dict):

            raise Exception('returned value from auth must be a dict')

        for k in self.auth_func_attrs:

            if k not in ret:

                raise Exception('Missing %s attribute from returned data' % k)

        return ret

class RhodeCodeExternalAuthPlugin(RhodeCodeAuthPluginBase):

    def use_fake_password(self):

        """