Catalyst::Plugin::Session::State::URI(3pm)

1Catalyst::Plugin::SessiUosne:r:SCtoantter:i:bUuRtIe(d3C)PaetrallyDsotc:u:mPelnutgaitni:o:nSession::State::URI(3)
2
3
4

NAME

6       Catalyst::Plugin::Session::State::URI - Use URIs to pass the session id
7       between requests
8

SYNOPSIS

10           use Catalyst qw/Session Session::State::URI Session::Store::Foo/;
11
12           # If you want the param style rewriting, set the parameter
13           MyApp->config('Plugin::Session' => {
14               param   => 'sessionid', # or whatever you like
15           });
16

DESCRIPTION

18       In order for Catalyst::Plugin::Session to work the session ID needs to
19       be available on each request, and the session data needs to be stored
20       on the server.
21
22       This plugin puts the session id into URIs instead of something like a
23       cookie.
24
25       By default, it rewrites all outgoing URIs, both redirects and in
26       outgoing HTML, but you can exercise control over exactly which URIs are
27       rewritten.
28

METHODS

30       session_should_rewrite
31           This method is consulted by "finalize", and URIs will be rewritten
32           only if it returns a true value.
33
34           Rewriting is controlled by the "$c->config('Plugin::Session' => {
35           rewrite_body => $val })" and "$c->config('Plugin::Session' => {
36           rewrite_redirect => $val })" config settings, both of which default
37           to true.
38
39           To globally disable rewriting simply set these parameters to false.
40
41           If "$c->config('Plugin::Session' => { no_rewrite_if_cookie => 1
42           })", Catalyst::Plugin::Session::State::Cookie is also in use, and
43           the user agent sent a cookie for the sesion then this method will
44           return false. This parameter also defaults to true.
45
46       session_should_rewrite_body
47           This method checks "$c->config('Plugin::Session' => {rewrite_body
48           => $val})" first. If this is true, it then calls
49           "session_should_rewrite_type".
50
51       session_should_rewrite_type
52           This method determines whether or not the body should be rewritten,
53           based on its content type.
54
55           For compatibility this method will not test the response's content
56           type without configuration. If you want to do that you must provide
57           a list of valid content types in
58           "$c->config->{'Plugin::Session'}{rewrite_types}", or subclass this
59           method.
60
61       session_should_rewrite_redirect
62           This method determines whether or not to rewrite the "Location"
63           header of the response.
64
65           This method checks "$c->config->{session}{rewrite_redirect}" first.
66           If this is true, it then checks if the status code is a number in
67           the 3xx range.
68
69       session_should_rewrite_uri $uri_text
70           This method is to determine whether a URI should be rewritten.
71
72           It will return true for URIs under "$c->req->base", and it will
73           also use MIME::Types to filter the links which point to png, pdf
74           and etc with the file extension.
75
76           You are encouraged to override this method if it's logic doesn't
77           suit your setup.
78
79       session_should_rewrite_uri_mime_type $uri_obj
80           A sub test of session_should_rewrite_uri, that checks if the file
81           name's guessed mime type is of a kind we should rewrite URIs to.
82
83           Files which are typically static (images, etc) will thus not be
84           rewritten in order to not get 404s or pass bogus parameters to the
85           server.
86
87           If $uri_obj's path causes MIME::Types to return true for the
88           "isBinary" test then then the URI will not be rewritten.
89
90       uri_with_sessionid $uri_text, [ $sid ]
91           When using path style rewriting (the default), it will append
92           "/-/$sessionid" to the uri path.
93
94           http://myapp/link -> http://myapp/link/-/$sessionid
95
96           When using param style rewriting, it will add a parameter key/value
97           pair after the uri path.
98
99           http://myapp/link -> http://myapp/link?$param=$sessionid
100
101           If $sid is not provided it will default to "$c->sessionid".
102
103       session_rewrite_if_needed
104           Rewrite the response if necessary.
105
106       rewrite_body_with_session_id $sid
107           Calls either "rewrite_html_with_session_id" or
108           "rewrite_text_with_session_id" depending on the content type.
109
110       rewrite_html_with_session_id $sid
111           Rewrites the body using HTML::TokePaser::Simple.
112
113           This method of rewriting also matches relative URIs, and is thus
114           more robust.
115
116       rewrite_text_with_session_id $sid
117           Rewrites the body using URI::Find.
118
119           This method is used when the content does not appear to be HTML.
120
121       rewrite_redirect_with_session_id $sid
122           Rewrites the "Location" header.
123
124       uri_with_param_sessionid
125       uri_with_path_sessionid
126

EXTENDED METHODS

128       prepare_path
129           Will restore the session if the request URI is formatted
130           accordingly, and rewrite the URI to remove the additional part.
131
132       finalize
133           Rewrite a redirect or the body HTML as appropriate.
134
135       delete_session_id
136       get_session_id
137       set_session_id
138       setup_session
139       uri_for
140

CAVEATS

142   Session Hijacking
143       URI sessions are very prone to session hijacking problems.
144
145       Make sure your users know not to copy and paste URIs to prevent these
146       problems, and always provide a way to safely link to public resources.
147
148       Also make sure to never link to external sites without going through a
149       gateway page that does not have session data in it's URI, so that the
150       external site doesn't get any session IDs in the http referrer header.
151
152       Due to these issues this plugin should be used as a last resort, as
153       Catalyst::Plugin::Session::State::Cookie is more appropriate 99% of the
154       time.
155
156       Take a look at the IP address limiting features in
157       Catalyst::Plugin::Session to see make some of these problems less
158       dangerous.
159
160       Goodbye page recipe
161
162       To exclude some sections of your application, like a goodbye page (see
163       "CAVEATS") you should make extend the "session_should_rewrite_uri"
164       method to return true if the URI does not point to the goodbye page,
165       extend "prepare_path" to not rewrite URIs that match "/-/" (so that
166       external URIs with that in their path as a parameter to the goodbye
167       page will not be destroyed) and finally extend "uri_with_sessionid" to
168       rewrite URIs with the following logic:
169
170       ·   URIs that match "/^$base/" are appended with session data (
171           "$c->maybe::next::method").
172
173       ·   External URIs (everything else) should be prepended by the goodbye
174           page. (e.g.
175           "http://myapp/link/http://the_url_of_whatever/foo.html").
176
177       But note that this behavior will be problematic when you are e.g.
178       submitting POSTs to forms on external sites.
179

AUTHORS

185       This module is derived from Catalyst::Plugin::Session::FastMmap code,
186       and has been heavily modified since.
187
188       Andrew Ford
189       Andy Grundman
190       Christian Hansen
191       Dave Rolsky
192       Yuval Kogman, "nothingmuch@woobling.org"
193       Marcus Ramberg
194       Sebastian Riedel
195       Hu Hailin
196       Tomas Doran, "bobtfish@bobtfish.net" (Current maintainer)
197       Florian Ragwitz "rafl@debian.org"
198

COPYRIGHT

200       This program is free software, you can redistribute it and/or modify it
201       under the same terms as Perl itself.
202
203
204
205perl v5.32.0                      2020-C0a7t-a2l8yst::Plugin::Session::State::URI(3)