| commit | author | age | ||
| 359fe8 | 1 | :mod:`repoze.who` Use Cases |
| TS | 2 | =========================== |
| 3 | ||
| 4 | How should an application interact with :mod:`repoze.who`? There are three | |
| 5 | main scenarios: | |
| 6 | ||
| 7 | Middleware-Only Use Cases | |
| 8 | ------------------------- | |
| 9 | ||
| 10 | Examples of using the :mod:`repoze.who` middleware, without explicitly | |
| 11 | using its API. | |
| 12 | ||
| 13 | ||
| 14 | Simple: Bug Tracker with ``REMOTE_USER`` | |
| 15 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 16 | ||
| 17 | This application expects the ``REMOTE_USER`` variable to be set by | |
| 18 | the middleware for authenticated requests. It allows the middleware to | |
| 19 | handle challenging the user when needed. | |
| 20 | ||
| 21 | In protected views, such as those which allow creating or following up | |
| 22 | to bug reports: | |
| 23 | ||
| 24 | - Check ``environ['REMOTE_USER']`` to get the authenticated user, and apply | |
| 25 | any application-specific policy (who is allowed to edit). | |
| 26 | ||
| 27 | - If the access check fails because the user is not yet authenticated, | |
| 28 | return an 401 Unauthorized response. | |
| 29 | ||
| 30 | - If the access check fails for authenticated users, return a | |
| 31 | 403 Forbidden response. | |
| 32 | ||
| 33 | Note that the application here doesn't depend on :mod:`repoze.who` at | |
| 34 | all: it would work identically if run behind Apache's ``mod_auth``. The | |
| 35 | ``Trac`` application works exactly this way. | |
| 36 | ||
| 37 | The middleware can be configured to suit the policy required for the | |
| 38 | site, e.g.: | |
| 39 | ||
| 40 | - challenge / identify using HTTP basic authentication | |
| 41 | ||
| 42 | - authorize via an ``.htaccces``-style file. | |
| 43 | ||
| 44 | ||
| 45 | More complex: Wiki with ``repoze.who.identity`` | |
| 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 47 | ||
| 48 | This application use the ``repoze.who.identity`` variable set in the | |
| 49 | WSGI environment by the middleware for authenticated requests. The application | |
| 50 | still allows the middleware to handle challenging the user when needed. | |
| 51 | ||
| 52 | The only difference from the previous example is that protected views, | |
| 53 | such as those which allow adding or editing wiki pages, can use the extra | |
| 54 | metadata stored inside ``environ['repoze.who.identity']`` (a mapping) to | |
| 55 | make authorization decisions: such metadata might include groups or roles | |
| 56 | mapped by the middleware onto the user. | |
| 57 | ||
| 58 | ||
| 59 | API-Only Use Cases | |
| 60 | ------------------ | |
| 61 | ||
| 62 | Examples of using the :mod:`repoze.who` API without its middleware. | |
| 63 | ||
| 64 | ||
| 65 | Simple: Wiki with its own login and logout views. | |
| 66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 67 | ||
| 68 | This application uses the :mod:`repoze.who` API to compute the authenticated | |
| 69 | user, as well as using its ``remember`` API to set headers for cookie-based | |
| 70 | authentication. | |
| 71 | ||
| 72 | In each view: | |
| 73 | ||
| 74 | - Call ``api.authenticate`` to get the authenticated user. | |
| 75 | ||
| 76 | - Show a ``login`` link for non-authenticated requests. | |
| 77 | ||
| 78 | - Show a ``logout`` link for authenticated requests. | |
| 79 | ||
| 80 | - Don't show "protected" links for non-authenticated requests. | |
| 81 | ||
| 82 | In protected views, such as those which allow adding or editing | |
| 83 | wiki pages: | |
| 84 | ||
| 85 | - Call ``api.authenticate`` to get the authenticated user; check | |
| 86 | the metadata about the user (e.g., any appropriate roles or groups) | |
| 87 | to verify access. | |
| 88 | ||
| 89 | - If the access check fails because the user is not yet authenticated, | |
| 90 | redirect to the ``login`` view, with a ``came_from`` value of the | |
| 91 | current URL. | |
| 92 | ||
| 93 | - If the access check fails for authenticated users, return a | |
| 94 | 403 Forbidden response. | |
| 95 | ||
| 96 | In the login view: | |
| 97 | ||
| 98 | - For ``GET`` requests, show the login form. | |
| 99 | ||
| 100 | - For ``POST`` requests, validate the login and password from the form. | |
| 101 | If successful, call ``api.remember``, and append the returned headers to | |
| 102 | your response, which may also contain, e.g., a ``Location`` header for | |
| 103 | a redirect to the ``came_from`` URL. In this case, there will be | |
| 104 | no authenticator plugin which knows about the login / password at all. | |
| 105 | ||
| 106 | In the logout view: | |
| 107 | ||
| 108 | - Call ``api.forget`` and append the headers to your response, which may | |
| 109 | also contain, e.g., a ``Location`` header for a redirect to the | |
| 110 | ``came_from`` URL after logging out. | |
| 111 | ||
| 112 | ||
| 113 | More complex: multiple applications with "single sign-on" | |
| 114 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 115 | ||
| 116 | In this scenario, authentication is "federated" across multiple applications, | |
| 117 | which delegate to a central "login application." This application verifies | |
| 118 | credentials from the user, and then uses headers or other tokens to | |
| 119 | communicate the verified identity to the delegating application. | |
| 120 | ||
| 121 | In the login application: | |
| 122 | ||
| 123 | - The SSO login application works just like the login view described above: | |
| 124 | the difference is that the configured identifier plugins must emit | |
| 125 | headers from ``remember`` which can be recognized by their counterparts | |
| 126 | in the other apps. | |
| 127 | ||
| 128 | In the non-login applications: | |
| 129 | ||
| 130 | - Challenge plugins here must be configured to implement the specific | |
| 131 | SSO protocol, e.g. redirect to the login app with information in the | |
| 132 | query string (other protocols might differ). | |
| 133 | ||
| 134 | - Identifer plugins must be able to "crack" / consume whatever tokens are | |
| 135 | returned by the SSO login app. | |
| 136 | ||
| 137 | - Authenticators will normally be no-ops (e.g., the ``auth_tkt`` plugin | |
| 138 | used as an authenticator). | |
| 139 | ||
| 140 | Hybrid Use Cases | |
| 141 | ---------------- | |
| 142 | ||
| 143 | Examples of using the :mod:`repoze.who` API in conjuntion with its middleware. | |
| 144 | ||
| 145 | Most complex: integrate Trac and the wiki behind SSO | |
| 146 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 147 | ||
| 148 | This example extends the previous one, but adds into the mix the | |
| 149 | requirement that one or more of the non-login applications (e.g., Trac) | |
| 150 | be used "off the shelf," without modifying them. Such applications can | |
| 151 | be plugged into the same SSO regime, with the addition of the | |
| 152 | :mod:``repoze.who`` middleware as an adapter to bridge the gap (e.g., | |
| 153 | to turn the SSO tokens into the ``REMOTE_USER`` required by Trac). | |
| 154 | ||
| 155 | In this scenario, the middleware would be configured identically to the | |
| 156 | API used in applications which do not need the middleware shim. | |
