docs/source/pluginwriter/authhooks.rst

   1 ======================
   2  Authentication Hooks
   3 ======================
   4
   5 This documents the hooks that are currently available for authentication
   6 plugins. If you need new hooks for your plugin, go ahead a submit a patch.
   7
   8 What hooks are available?
   9 =========================
  10
  11 'authentication'
  12 ----------------
  13
  14 This hook just needs to return ``True`` as this is how
  15 the MediaGoblin app knows that an authentication plugin is enabled.
  16
  17
  18 'auth_extra_validation'
  19 -----------------------
  20
  21 This hook is used to provide any additional validation of the registration
  22 form when using ``mediagoblin.auth.tools.register_user()``. This hook runs
  23 through all enabled auth plugins.
  24
  25
  26 'auth_create_user'
  27 ------------------
  28
  29 This hook is used by ``mediagoblin.auth.tools.register_user()`` so plugins can
  30 store the necessary information when creating a user. This hook runs through
  31 all enabled auth plugins.
  32
  33 'auth_get_user'
  34 ---------------
  35
  36 This hook is used by ``mediagoblin.auth.tools.check_login_simple()``. Your
  37 plugin should return a ``User`` object given a username.
  38
  39 'auth_no_pass_redirect'
  40 -----------------------
  41
  42 This hook is called in ``mediagoblin.auth.views`` in both the ``login`` and
  43 ``register`` views. This hook should return the name of your plugin, so that
  44 if :ref:`basic_auth-chapter` is not enabled, the user will be redirected to the
  45 correct login and registration views for your plugin.
  46
  47 The code assumes that it can generate a valid URL given
  48 ``mediagoblin.plugins.{{ your_plugin_here }}.login`` and
  49 ``mediagoblin.plugins.{{ your_plugin_here }}.register``. This is only needed if
  50 you will not be using the ``login`` and ``register`` views in
  51 ``mediagoblin.auth.views``.
  52
  53 'auth_get_login_form'
  54 ---------------------
  55
  56 This hook is called in ``mediagoblin.auth.views.login()``. If you are not using
  57 that view, then you do not need this hook. This hook should take a ``request``
  58 object and return the ``LoginForm`` for your plugin.
  59
  60 'auth_get_registration_form'
  61 ----------------------------
  62
  63 This hook is called in ``mediagoblin.auth.views.register()``. If you are not
  64 using that view, then you do not need this hook. This hook should take a
  65 ``request`` object and return the ``RegisterForm`` for your plugin.
  66
  67 'auth_gen_password_hash'
  68 ------------------------
  69
  70 This hook should accept a ``raw_pass`` and an ``extra_salt`` and return a
  71 hashed password to be stored in ``User.pw_hash``.
  72
  73 'auth_check_password'
  74 ---------------------
  75
  76 This hook should accept a ``raw_pass``, a ``stored_hash``, and an ``extra_salt``.
  77 Your plugin should then check that the ``raw_pass`` hashes to the same thing as
  78 the ``stored_hash`` and return either ``True`` or ``False``.
  79
  80 'auth_fake_login_attempt'
  81 -------------------------
  82
  83 This hook is called in ``mediagoblin.auth.tools.check_login_simple``. It is
  84 called if a user is not found and should do something that takes the same amount
  85 of time as your ``check_password`` function. This is to help prevent timing
  86 attacks.