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