Commit | Line | Data |
---|---|---|
d194770d RE |
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 | ||
9650aa39 | 47 | The code assumes that it can generate a valid URL given |
d194770d RE |
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 | |
9650aa39 | 85 | of time as your ``check_password`` function. This is to help prevent timing |
d194770d | 86 | attacks. |