Merge 'module-install' into 'trunk'

[catagits/Catalyst-Plugin-RequireSSL.git] / README

NAME
    Catalyst::Plugin::RequireSSL - Force SSL mode on select pages

SYNOPSIS
        # in MyApp.pm
        use Catalyst;
        MyApp->setup( qw/RequireSSL/ );
    
        MyApp->config->{require_ssl} = {
            https => 'secure.mydomain.com',
            http => 'www.mydomain.com',
            remain_in_ssl => 0,
            no_cache => 0,
            detach_on_redirect => 1,
        };

        # in any controller methods that should be secured
        $c->require_ssl;

DESCRIPTION
    Use this plugin if you wish to selectively force SSL mode on some of
    your web pages, for example a user login form or shopping cart.

    Simply place $c->require_ssl calls in any controller method you wish to
    be secured.

    This plugin will automatically disable itself if you are running under
    the standalone HTTP::Daemon Catalyst server. A warning message will be
    printed to the log file whenever an SSL redirect would have occurred.

WARNINGS
    If you utilize different servers or hostnames for non-SSL and SSL
    requests, and you rely on a session cookie to determine redirection (i.e
    for a login page), your cookie must be visible to both servers. For more
    information, see the documentation for the Session plugin you are using.

CONFIGURATION
    Configuration is optional. You may define the following configuration
    values:

        https => $ssl_host

    If your SSL domain name is different from your non-SSL domain, set this
    value.

        http => $non_ssl_host

    If you have set the https value above, you must also set the hostname of
    your non-SSL server.

        remain_in_ssl

    If you'd like your users to remain in SSL mode after visiting an
    SSL-required page, you can set this option to 1. By default, this option
    is disabled and users will be redirected back to non-SSL mode as soon as
    possible.

        no_cache

    If you have a wildcard certificate you will need to set this option if
    you are using multiple domains on one instance of Catalyst.

        detach_on_redirect

    By default "$c->require_ssl" only calls "$c->response->redirect" but
    does not stop request processing (so it returns and subsequent
    statements are run). This is probably not what you want. If you set this
    option to a true value "$c->require_ssl" will call "$c->detach" when it
    redirects.

METHODS
  require_ssl
    Call require_ssl in any controller method you wish to be secured.

        $c->require_ssl;

    The browser will be redirected to the same path on your SSL server. POST
    requests are never redirected.

  allow_ssl
    Call allow_ssl in any controller method you wish to access both in SSL
    and non-SSL mode.

        $c->allow_ssl;

    The browser will not be redirected, independently of whether the request
    was made to the SSL or non-SSL server.

  setup
    Disables this plugin if running under an engine which does not support
    SSL.

  finalize
    Performs the redirect to SSL url if required.

KNOWN ISSUES
    When viewing an SSL-required page that uses static files served from the
    Static plugin, the static files are redirected to the non-SSL path.

    In order to get the correct behaviour where static files are not
    redirected, you should use the Static::Simple plugin or always serve
    static files directly from your web server.

SEE ALSO
    Catalyst, Catalyst::Plugin::Static::Simple

AUTHOR
    Andy Grundman, <andy@hybridized.org>

CONTRIBUTORS
    Simon Elliott <simon@browsing.co.uk> (support for wildcards)

COPYRIGHT
    This program is free software, you can redistribute it and/or modify it
    under the same terms as Perl itself.