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