'validator' is an lazy instantiated form field validator object, ala

        formencode. You need to *call* this object to init the validators.

        All calls to Kallithea validators should be used through self.validators

        which is a lazy loading proxy of formencode module.

        """

        raise NotImplementedError("Not implemented in base class")

    def plugin_settings(self):

        """

        This method is called by the authentication framework, not the .settings()

        method. This method adds a few default settings (e.g., "enabled"), so that

        plugin authors don't have to maintain a bunch of boilerplate.

        OVERRIDING THIS METHOD WILL CAUSE YOUR PLUGIN TO FAIL.

        """

        rcsettings = self.settings()

        rcsettings.insert(0, {

            "name": "enabled",

            "validator": self.validators.StringBoolean(if_missing=False),

            "type": "bool",

            "description": "Enable or Disable this Authentication Plugin",

            "formname": "Enabled"

            }

        )

        return rcsettings

    def user_activation_state(self):

        """

        Defines user activation state when creating new users

        :returns: boolean

        """

        raise NotImplementedError("Not implemented in base class")

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

        """

        Given a user object (which may be None), 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 with keys from

        KallitheaAuthPluginBase.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

        """

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

        if user_data is not None:

            return self._validate_auth_return(user_data)

        return None

    def _validate_auth_return(self, user_data):

        if not isinstance(user_data, dict):

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

        for k in self.auth_func_attrs:

            if k not in user_data:

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

        return user_data

class KallitheaExternalAuthPlugin(KallitheaAuthPluginBase):

    def use_fake_password(self):

        """

        Return a boolean that indicates whether or not we should set the user's

        password to a random value when it is authenticated by this plugin.

        If your plugin provides authentication, then you will generally want this.

        :returns: boolean

        """

        raise NotImplementedError("Not implemented in base class")

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

        user_data = super(KallitheaExternalAuthPlugin, self)._authenticate(

            userobj, username, passwd, settings, **kwargs)

        if user_data is not None:

            # maybe plugin will clean the username ?

            # we should use the return value

            username = user_data['username']

            # if user is not active from our extern type we should fail to auth

            # this can prevent from creating users in Kallithea when using

            # external authentication, but if it's inactive user we shouldn't

            # create that user anyway

            if user_data['active_from_extern'] is False:

                log.warning("User %s authenticated against %s, but is inactive",

                            username, self.__module__)

                return None

            if self.use_fake_password():

                # Randomize the PW because we don't need it, but don't want

                # them blank either

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

            log.debug('Updating or creating user info from %s plugin',

                      self.name)

            user = UserModel().create_or_update(

                username=username,

                password=passwd,

                email=user_data["email"],

                firstname=user_data["firstname"],

                lastname=user_data["lastname"],

                active=user_data["active"],

                admin=user_data["admin"],

                extern_name=user_data["extern_name"],

                extern_type=self.name

            )

            # enforce user is just in given groups, all of them has to be ones

            # created from plugins. We store this info in _group_data JSON field

            groups = user_data['groups'] or []

            UserGroupModel().enforce_groups(user, groups, self.name)

            Session().commit()

        return user_data

def importplugin(plugin):

    """

    Imports and returns the authentication plugin in the module named by plugin

    (e.g., plugin='kallithea.lib.auth_modules.auth_internal'). Returns the

    KallitheaAuthPluginBase subclass on success, raises exceptions on failure.

    raises:

        AttributeError -- no KallitheaAuthPlugin class in the module

        TypeError -- if the KallitheaAuthPlugin is not a subclass of ours KallitheaAuthPluginBase

        ImportError -- if we couldn't import the plugin at all

    """

    log.debug("Importing %s", plugin)

    if not plugin.startswith(u'kallithea.lib.auth_modules.auth_'):

        parts = plugin.split(u'.lib.auth_modules.auth_', 1)

        if len(parts) == 2:

            _module, pn = parts

            plugin = u'kallithea.lib.auth_modules.auth_' + pn

    PLUGIN_CLASS_NAME = "KallitheaAuthPlugin"

    try:

        module = importlib.import_module(plugin)

    except (ImportError, TypeError):

        log.error(traceback.format_exc())

        # TODO: make this more error prone, if by some accident we screw up

        # the plugin name, the crash is pretty bad and hard to recover

        raise

    log.debug("Loaded auth plugin from %s (module:%s, file:%s)",

              plugin, module.__name__, module.__file__)

    pluginclass = getattr(module, PLUGIN_CLASS_NAME)

    if not issubclass(pluginclass, KallitheaAuthPluginBase):

        raise TypeError("Authentication class %s.KallitheaAuthPlugin is not "

                        "a subclass of %s" % (plugin, KallitheaAuthPluginBase))

    return pluginclass

def loadplugin(plugin):

    """

    Loads and returns an instantiated authentication plugin.

        see: importplugin

    """

    plugin = importplugin(plugin)()

    if plugin.plugin_settings.im_func != KallitheaAuthPluginBase.plugin_settings.im_func:

        raise TypeError("Authentication class %s.KallitheaAuthPluginBase "

                        "has overridden the plugin_settings method, which is "

                        "forbidden." % plugin)

    return plugin

def authenticate(username, password, environ=None):

    """

    Authentication function used for access control,

    It tries to authenticate based on enabled authentication modules.

    :param username: username can be empty for container auth

    :param password: password can be empty for container auth

    :param environ: environ headers passed for container auth

    :returns: None if auth failed, user_data dict if auth is correct

    """

    auth_plugins = Setting.get_auth_plugins()

    log.debug('Authentication against %s plugins', auth_plugins)

    for module in auth_plugins:

        try:

            plugin = loadplugin(module)

        except (ImportError, AttributeError, TypeError) as e:

        log.debug('Trying authentication using ** %s **', module)

        # load plugin settings from Kallithea database

        plugin_name = plugin.name

        plugin_settings = {}

        for v in plugin.plugin_settings():

            conf_key = "auth_%s_%s" % (plugin_name, v["name"])

            setting = Setting.get_by_name(conf_key)

            plugin_settings[v["name"]] = setting.app_settings_value if setting else None

        log.debug('Plugin settings \n%s', formatted_json(plugin_settings))

        if not str2bool(plugin_settings["enabled"]):

            log.info("Authentication plugin %s is disabled, skipping for %s",

                     module, username)

            continue

        # use plugin's method of user extraction.

        user = plugin.get_user(username, environ=environ,

                               settings=plugin_settings)

        log.debug('Plugin %s extracted user is `%s`', module, user)

        if not plugin.accepts(user):

            log.debug('Plugin %s does not accept user `%s` for authentication',

                      module, user)

            continue

        else:

            log.debug('Plugin %s accepted user `%s` for authentication',

                      module, user)

            # The user might have tried to authenticate using their email address,

            # then the username variable wouldn't contain a valid username.

            # But as the plugin has accepted the user, .username field should

            # have a valid username, so use it for authentication purposes.

            if user is not None:

                username = user.username

        log.info('Authenticating user using %s plugin', plugin.__module__)

        # _authenticate is a wrapper for .auth() method of plugin.

        # it checks if .auth() sends proper data. For KallitheaExternalAuthPlugin

        # it also maps users to Database and maps the attributes returned

        # from .auth() to Kallithea database. If this function returns data

        # then auth is correct.

        user_data = plugin._authenticate(user, username, password,

                                           plugin_settings,

                                           environ=environ or {})

        log.debug('PLUGIN USER DATA: %s', user_data)

        if user_data is not None:

            log.debug('Plugin returned proper authentication data')

            return user_data

        # we failed to Auth because .auth() method didn't return the user

        if username:

            log.warning("User `%s` failed to authenticate against %s",

                        username, plugin.__module__)

    return None

def get_managed_fields(user):

    """return list of fields that are managed by the user's auth source, usually some of

    'username', 'firstname', 'lastname', 'email', 'active', 'password'

    """

    auth_plugins = Setting.get_auth_plugins()

    for module in auth_plugins:

        log.debug('testing %s (%s) with auth plugin %s', user, user.extern_type, module)

        plugin = loadplugin(module)

        if plugin.name == user.extern_type:

            return plugin.get_managed_fields()

    log.error('no auth plugin %s found for %s', user.extern_type, user)

    return [] # TODO: Fail badly instead of allowing everything to be edited?