doc/plugins/contrib/signinview.mdwn

   1 [[!template id=plugin name=signinview core=0 author="[[jcflack]]"]]
   2 [[!tag type/special-purpose]]
   3
   4 This plugin is one implementation approach to a [[todo/zoned ikiwiki]]. It is named
   5 like [[plugins/signinedit]], which requires users to sign in before editing pages.
   6 Similarly, this plugin requires users to sign in before _viewing_ certain pages.
   7 Unlike [[plugins/signinedit]], which _only_ checks that any user is signed in,
   8 this plugin is also similar to [[plugins/lockedit]] in that it checks the user's
   9 identity and a [[ikiwiki/PageSpec]] to determine _which_ pages may be viewed.
  10 It works with any auth methods ikiwiki supports, not only those the `http` server
  11 also understands.
  12
  13 ## How to configure
  14
  15 This plugin adds a new function, `do=view`, to ikiwiki's CGI wrapper. It is intended
  16 to be called by the `http` server as an `ErrorDocument` for the `403` (forbidden) error response.
  17
  18 In order to be usable even in shared-hosting situations without full access to
  19 the `http` server configuration files, this plugin requires nothing more than
  20 `.htaccess` files, as long as the server is configured to honor `ErrorDocument` and
  21 `Deny` or `Require` directives in them.
  22
  23 To divide the wiki into a public zone and one or more private zone(s), simply place
  24 `Require all denied` (Apache 2.4), `Deny from All` (Apache 2.2), or the equivalent
  25 directive for the server and version in use, on the topmost directory of any private
  26 zone, either in an `.htaccess` file, or in the server configuration file if possible.
  27 Any location outside of these will continue to be served as normal public static
  28 ikiwiki content.
  29
  30 Then, if the `{$cgiurl}` is, for example, `/cgi-bin/ikiwiki.cgi`, add the directive
  31
  32     ErrorDocument 403 /cgi-bin/ikiwiki.cgi?do=view
  33
  34 at the private locations or any ancestor up to the documentroot itself, again either
  35 in a `.htaccess` file or in the server configuration file.
  36
  37 That's it for the server configuration. The server will now punt every request for
  38 private content to the ikiwiki wrapper. Everything else about the authorization
  39 decision--what auth method to use, whether there is just one private zone or different
  40 zones for different users--is handled by ikiwiki using a [[ikiwiki/PageSpec]].
  41
  42 ### viewable_pages config option
  43
  44 This option in `ikiwiki.setup` is a [[ikiwiki/PageSpec]] defining which pages can be viewed.
  45 Because one predicate that can be used in a [[ikiwiki/PageSpec]] is `user`, this is enough
  46 to define interesting access rules. For example:
  47
  48     viewable_pages: >
  49       ((user(astolfo) or user(basilio)) and team1/*)
  50       or
  51       ((user(clotaldo) or user(estrella)) and team2/*)
  52
  53 Note that this defines the conditions to _allow_ viewing, which is opposite the
  54 sense of the [[plugins/lockedit]] plugin, where you define the conditions
  55 to _deny_ editing.
  56
  57 If there are more than a few users in a group, or the specification for accessible
  58 pages is more complex, the [[plugins/contrib/pagespec_alias]] plugin
  59 can be useful to factor things out. Note it currently must [[be patched|plugins/contrib/pagespec_alias/discussion]]
  60 for this to work:
  61
  62     pagespec_aliases:
  63       team1: >
  64         user(astolfo)
  65         or user(basilio)
  66       team2: >
  67         user(clotaldo)
  68         or user(estrella)
  69       team1stuff: team1/* or common/*
  70       team2stuff: team2/* or common/*
  71     viewable_pages: >
  72       (team1() and team1stuff())
  73       or (team2() and team2stuff())
  74
  75 ### mime_types config option
  76
  77 Normally, when serving the static pages of an ordinary public site,
  78 the `http` server itself is responsible for identifying the `Content-Type`
  79 of each file. However, for any page that is served by this plugin instead
  80 of directly, the CGI specification makes it [plugin's job](http://tools.ietf.org/html/rfc3875#section-6.3.1),
  81 not the server's, to identify the `Content-Type`.
  82
  83 In the current version, this plugin does that in a dead-simple way. For any page that ikiwiki htmlized
  84 (that is, for which the `pagetype` [[plugin API function|plugins/write]] returns a value),
  85 the type `text/html` is assigned. For anything else, a simple collection of content types and `PageSpec`s
  86 must be configured in the `ikiwiki.setup` file:
  87
  88     mime_types:
  89       image/png: '*.png'
  90       application/pdf: '*.pdf'
  91       text/css: '*.css'
  92
  93 Anything without a matching rule gets served as `application/octet-stream`, which is
  94 probably not what you want, but a clear sign of what rule needs to be added.
  95
  96 ## Other considerations
  97
  98 ### Leakage of non-content files
  99
 100 Any CGI code that does what this plugin does, and can serve requested files under the
 101 document root, needs to be careful not to allow viewing of certain sensitive files
 102 that may also be found there, such as `.htaccess`, `.htpasswd`, etc. Instead of trying
 103 to think of all the possible files that should not be served, this plugin takes an
 104 absolutely strict approach: every requested file is looked up in the `%destsources` hash,
 105 containing all the files ikiwiki has generated or placed in the web root.
 106 Any file that _ikiwiki didn't put there_, this plugin _won't touch_. Otherwise, its page
 107 name is now known, and must satisfy the `viewable_pages` `PageSpec`.
 108
 109 This policy is also what allows this plugin to work back through `%pagesources` to
 110 the original source name, needed for the content-type rules described above.
 111
 112 ### Cache control
 113
 114 The purpose of a non-public zone can be defeated if there are caching proxies or
 115 other non-private caches that might retain the content this plugin returns.
 116
 117 Caching of the response is automatically forbidden by the HTTP specification
 118 [if there was an `Authorization` header in the request](http://tools.ietf.org/html/rfc7234#section-3.2).
 119 However, this plugin works with any auth method ikiwiki supports, not all of which require
 120 that header, so this plugin always emits response headers to explicitly forbid caching.
 121
 122 Note that nothing precludes an evil caching agent that ignores the rules.
 123
 124 ### Other ways to handle `Content-Type`
 125
 126 While it is simple enough to supply a `mime_types` map in `ikiwiki.setup`, it also
 127 duplicates logic that has already been done to death in other places. Another approach
 128 would be to use `File::MimeInfo::Magic`, which is already present if the `filecheck`
 129 plugin is in use.
 130
 131 In a wiki _compiler_, it would be natural to do that content-type determination
 132 at compile time and save it in page state, so this plugin would simply output
 133 the stored type. On the other hand, saving the type for every (non-htmlized?) page
 134 would enlarge the state `Storable` that has to be loaded, and so might not be
 135 faster than typing the file on the fly.
 136
 137 ## Obtaining and installing
 138
 139 The `signinview` plugin is [not in github yet](https://github.com/jcflack/ikiwiki/tree/plug-signinview)
 140 (horroars! vaporware!). What _is_ in github at the moment is a preliminary patch I have
 141 [proposed](https://github.com/joeyh/ikiwiki/pull/14),
 142 giving plugins some control over the environment variables that a generated wrapper will preserve.
 143
 144 Depending on the ultimate fate of that patch, I will adjust/rebase and then push the `signinview`
 145 branch itself.