/ 
Mojolicious-Plugin-ClosedRedirect-0.15
River stage zero No dependents
/ Mojolicious::Plugin::ClosedRedirect

NAME

Mojolicious::Plugin::ClosedRedirect - Defend Open Redirect Attacks

SYNOPSIS

plugin ClosedRedirect => {
  secrets => [123, 'abz']
};

get '/login' => sub {
  my $c = shift;
  my $v = $c->validation;

  # Check for a redirection parameter
  $v->required('fwd')->closed_redirect;

  # ...

  # Redirect to redirection URL
  return $c->redirect_to($v->param('fwd')) unless $v->has_error;

  # Redirect to home page on failed validation
  return $c->redirect_to('/');
};

DESCRIPTION

This plugin helps you to avoid OpenRedirect vulnerabilities in your application by limiting redirections to either local paths or signed URLs.

This module is an early release! There may be significant changes in the future.

ATTRIBUTES

secrets

$plugin->secrets([123, 'abz']);
print $plugin->secrets->[0];

Set secrets to be used to sign URLs. Defaults to the application secrets.

CHECKS

closed_redirect

# Check for a redirection parameter
$c->validation->required('fwd')->closed_redirect;

Check the parameter in scope for being a valid URL to redirect to.

If no parameter is passed to the check, local paths or signed URLs are accepted. If the parameter signed is passed, only signed URLs are accepted. If the parameter local is passed, only local paths are accepted.

If the parameter was signed, the signature with the URI parameter crto will be removed on success (even if the URL was local).

HELPERS

close_redirect_to

my $url = $c->url_for('/login')->query([
  fwd => $c->close_redirect_to('http://example.com/path')
]);

Sign a redirection URL with the defined secret.

relative_redirect_to

$c->relative_redirect_to('/my/app/home');

Redirects to a given path after removing prefix parts that are given as the request's base path. Expects the same parameters as "redirect_to" in Mojolicious::Controller. This comes in handy if your application is not running under a root path and you modify relative URL creation by changing the request's base path.

HOOKS

on_open_redirect_attack

$app->hook(on_open_redirect_attack => sub {
  my ($name, $url, $msg) = @_;
  ...
});

Emitted when an open redirect attack was detected. Passes the parameter name, the first failing URL, and the error message of the check.

METHODS

register

# Mojolicious
$app->plugin('ClosedRedirect');

# Mojolicious::Lite
plugin 'ClosedRedirect';

Called when registering the plugin. Accepts attributes as parameters.

All parameters can be set either on registration or as part of the configuration file with the key ClosedRedirect (with the configuration file having the higher precedence).

BUGS and CAVEATS

The URLs are currently signed using HMAC-SHA-1 and a secret. There are known attacks to SHA-1.

Local redirects need to be paths - URLs with host information are not supported yet.

DEPENDENCIES

Mojolicious.

AVAILABILITY

https://github.com/Akron/Mojolicious-Plugin-ClosedRedirect

COPYRIGHT AND LICENSE

Copyright (C) 2016-2020, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.