Commit | Line | Data |
1763fe29 |
1 | NAME |
d5e430c2 |
2 | Catalyst::Plugin::RequireSSL - Force SSL mode on select pages |
1763fe29 |
3 | |
4 | SYNOPSIS |
eeefd598 |
5 | # in MyApp.pm |
6 | use Catalyst; |
7 | MyApp->setup( qw/RequireSSL/ ); |
1763fe29 |
8 | |
d5e430c2 |
9 | MyApp->config->{require_ssl} = { |
10 | https => 'secure.mydomain.com', |
11 | http => 'www.mydomain.com', |
12 | remain_in_ssl => 0, |
6406f7c2 |
13 | no_cache => 0, |
14 | detach_on_redirect => 1, |
1763fe29 |
15 | }; |
16 | |
eeefd598 |
17 | # in any controller methods that should be secured |
d5e430c2 |
18 | $c->require_ssl; |
1763fe29 |
19 | |
20 | DESCRIPTION |
d5e430c2 |
21 | Use this plugin if you wish to selectively force SSL mode on some of |
22 | your web pages, for example a user login form or shopping cart. |
1763fe29 |
23 | |
d5e430c2 |
24 | Simply place $c->require_ssl calls in any controller method you wish to |
25 | be secured. |
1763fe29 |
26 | |
d5e430c2 |
27 | This plugin will automatically disable itself if you are running under |
28 | the standalone HTTP::Daemon Catalyst server. A warning message will be |
29 | printed to the log file whenever an SSL redirect would have occurred. |
1763fe29 |
30 | |
d5e430c2 |
31 | WARNINGS |
32 | If you utilize different servers or hostnames for non-SSL and SSL |
33 | requests, and you rely on a session cookie to determine redirection (i.e |
34 | for a login page), your cookie must be visible to both servers. For more |
35 | information, see the documentation for the Session plugin you are using. |
1763fe29 |
36 | |
37 | CONFIGURATION |
38 | Configuration is optional. You may define the following configuration |
39 | values: |
40 | |
d5e430c2 |
41 | https => $ssl_host |
6406f7c2 |
42 | |
d5e430c2 |
43 | If your SSL domain name is different from your non-SSL domain, set this |
44 | value. |
1763fe29 |
45 | |
d5e430c2 |
46 | http => $non_ssl_host |
6406f7c2 |
47 | |
d5e430c2 |
48 | If you have set the https value above, you must also set the hostname of |
49 | your non-SSL server. |
1763fe29 |
50 | |
d5e430c2 |
51 | remain_in_ssl |
6406f7c2 |
52 | |
d5e430c2 |
53 | If you'd like your users to remain in SSL mode after visiting an |
eeefd598 |
54 | SSL-required page, you can set this option to 1. By default, this option |
55 | is disabled and users will be redirected back to non-SSL mode as soon as |
56 | possible. |
1763fe29 |
57 | |
6406f7c2 |
58 | no_cache |
59 | |
60 | If you have a wildcard certificate you will need to set this option if |
61 | you are using multiple domains on one instance of Catalyst. |
62 | |
63 | detach_on_redirect |
64 | |
65 | By default "$c->require_ssl" only calls "$c->response->redirect" but |
66 | does not stop request processing (so it returns and subsequent |
67 | statements are run). This is probably not what you want. If you set this |
68 | option to a true value "$c->require_ssl" will call "$c->detach" when it |
69 | redirects. |
70 | |
eeefd598 |
71 | METHODS |
72 | require_ssl |
73 | Call require_ssl in any controller method you wish to be secured. |
1763fe29 |
74 | |
eeefd598 |
75 | $c->require_ssl; |
1763fe29 |
76 | |
eeefd598 |
77 | The browser will be redirected to the same path on your SSL server. POST |
78 | requests are never redirected. |
1763fe29 |
79 | |
6406f7c2 |
80 | allow_ssl |
81 | Call allow_ssl in any controller method you wish to access both in SSL |
82 | and non-SSL mode. |
83 | |
84 | $c->allow_ssl; |
85 | |
86 | The browser will not be redirected, independently of whether the request |
87 | was made to the SSL or non-SSL server. |
88 | |
89 | setup |
90 | Disables this plugin if running under an engine which does not support |
91 | SSL. |
92 | |
93 | finalize |
94 | Performs the redirect to SSL url if required. |
95 | |
1763fe29 |
96 | KNOWN ISSUES |
d5e430c2 |
97 | When viewing an SSL-required page that uses static files served from the |
eeefd598 |
98 | Static plugin, the static files are redirected to the non-SSL path. |
1763fe29 |
99 | |
eeefd598 |
100 | In order to get the correct behaviour where static files are not |
101 | redirected, you should use the Static::Simple plugin or always serve |
102 | static files directly from your web server. |
1763fe29 |
103 | |
104 | SEE ALSO |
eeefd598 |
105 | Catalyst, Catalyst::Plugin::Static::Simple |
1763fe29 |
106 | |
107 | AUTHOR |
eeefd598 |
108 | Andy Grundman, <andy@hybridized.org> |
1763fe29 |
109 | |
6406f7c2 |
110 | CONTRIBUTORS |
111 | Simon Elliott <simon@browsing.co.uk> (support for wildcards) |
112 | |
1763fe29 |
113 | COPYRIGHT |
114 | This program is free software, you can redistribute it and/or modify it |
115 | under the same terms as Perl itself. |
116 | |