Documentation

Referer attribute

Table of Contents 

Presentation

This attribute is used to protect access to a controller or action based on the value of the HTTP REFERER header.

Parameters

The attribute offers several parameters:

  • $domain: (bool|string|array) Indicates the referer's domain (if true, the domain must be identical to the current domain), or a list of domains (the referer must be equal to one of them).
  • $domainSuffix: (string|array) Referrer's domain suffix, or list of suffixes.
  • $domainRegex: (string) Regular expression to be validated by the referer's domain.
  • $domainVar: (string) Name of the template variable containing the domain to which the referer's domain must correspond.
  • $domainConfig: (bool) Set to true to use the refererDomain key from the x-security extended configuration (in the temma.json file).
  • $https: (bool|string) The effect of this parameter depends on its value:
    • null: (default value) The referer can be in HTTP or HTTPS.
    • true: The referer must be HTTPS.
    • false: The referer must be HTTP.
    • 'same': The referer must use the same protocol (HTTP/HTTPS) as the current site.
  • $path: (string|array) Path or path list of the referer.
  • $pathPrefix: (string|array) Path prefix of the referer, or list of prefixes.
  • $pathSuffix: (string|array) Path suffix of the referer, or list of suffixes.
  • $pathRegex: (string) Regular expression that the referer's path must validate.
  • $pathVar: (string) Name of the template variable containing the referer's path.
  • $pathConfig: (bool) Set to true to use the refererPath key from the x-security extended configuration (in the temma.json file).
  • $url: (string|array) URL or list of URLs of the referer.
  • $urlRegex: (string) Regular expression to be validated by the referer's URL.
  • $urlVar: (string) Name of template variable containing referrer URL.
  • $urlConfig: (bool) Set to true to use the refererUrl key from the x-security extended configuration (in the temma.json file).
  • $redirect: (string) URL to redirect users to if they don't have the right to access the controller or action (instead of displaying an error page).
  • $redirectVar: (string) Name of template variable containing URL to redirect user to.
  • $redirectConfig: (bool) Set to true to use the refererRedirect key in the x-security extended configuration (in the temma.json file).

Redirection priority

If access is denied, the user can be redirected. To determine the redirection URL, the attribute applies the following order of priority:

  1. If the $redirect parameter is set, it is used.
  2. If the $redirectVar parameter is defined, and it contains the name of an existing, non-empty template variable, its content is used.
  3. If the temma.json file contains an x-security extended configuration, and this contains a refererRedirect key, its content is used.
  4. If the temma.json file contains an x-security extended configuration, and this contains a redirect key, its content is used.

Configuration

To ensure that all Referer attributes redirect to the same URL, simply set the refererRedirect key in the x-security extended configuration of the temma.json file:

{
    "x-security": {
        "refererRedirect": "/failure"
    }   
}

To ensure that the redirect URL is the same for the Auth, Method, Referer and Redirect attributes, simply define the redirect key in the x-security extended configuration in the temma.json file:

{
    "x-security": {
        "redirect": "/login"
    }   
}

Examples

use \Temma\Attributes\Referer as TµReferer;

class Admin extends \Temma\Web\Controller {
    // access forbidden for requests without referer
    #[TµReferer]
    public function action1() { }

    // authorized for requests from the same domain only
    #[TµReferer(true)]
    public function action2() { }

    // allowed for 'fubar.com' domain
    #[TµReferer('fubar.com')]
    public function action3() { }

    // same as previous
    #[TµReferer(domain: 'fubar.com')]
    public function action3bis() { }

    // allowed for 'fubar.com' and 'www.fubar.com' domains
    #[TµReferer(['fubar.com', 'www.fubar.com'])]
    public function action4() { }

    // same as previous
    #[TµReferer(domains: ['fubar.com', 'www.fubar.com'])]
    public function action4bis() { }

    // allowed for domains ending in '.fubar.com'.
    #[TµReferer(domainSuffix: '.fubar.com')]
    public function action5() { }

    // allowed for domains ending in '.fubar.com' or '.foobar.com'.
    #[TµReferer(domainSuffix: ['.fubar.com', '.foobar.com'])]
    public function action6() { }

    // allowed for domains that validate the provided regular expression
    #[TµReferer(domainRegex: '^test\d?.fubar.(com|net)$')]
    public function action7() { }

    // authorized for the domain whose name is stored in
    // the 'okDomain' template variable
    #[TµReferer(domainVar: 'okDomain')]
    public function action8() { }

    // authorized for the domain defined in the 'refererDomain' key of
    // the 'x-security' extended configuration (in the 'temma.json' file)
    #[TµReferer(domainConfig: true)]
    public function action9() { }

    // authorized for an HTTP referer
    #[TµReferer(https: false)]
    public function action10() { }

    // authorized for an HTTPS referer
    #[TµReferer(https: true)]
    public function action11() { }

    // authorized for a referer whose protocol (HTTP/HTTPS)
    // is the same as that of the current site
    #[TµReferer(https: 'same')]
    public function action12() { }

    // authorized for a referer with path '/fu/bar.html'.
    #[TµReferer(path: '/fu/var.html')]
    public function action13() { }

    // allowed for a referer with path '/fu.html' or '/bar.html
    #[TµReferer(path: ['/fu.html', '/bar.html'])]
    public function action14() { }

    // allowed for a referer whose path starts with '/fu/'
    #[TµReferer(pathPrefix: '/fu/')]
    public function action15() { }

    // authorized for a referer whose path starts with '/fu/' or '/bar/'
    #[TµReferer(pathPrefix: ['/fu/', '/bar/'])]
    public function action16() { }

    // allowed for a referer whose path ends with '/api.xml'
    #[TµReferer(pathSuffix: '/api.xml')]
    public function action17() { }

    // authorized for a referer whose path ends with '/api.xml' or '/api.json
    #[TµReferer(pathSuffix: ['/api.xml', '/api.json'])]
    public function action18() { }

    // authorized for a referer whose path validates the provided regular expression
    #[TµReferer(pathRegex: '/^\/.*testApi.*\.xml$/')]
    public function action19() { }

    // authorized for a referer whose path corresponds to that stored
    // in the 'okPath' template variable
    #[TµReferer(pathVar: 'okPath')]
    public function action20() { }

    // authorized for a referer whose path corresponds to that stored
    // in the 'refererPath' key of the 'x-security' extended configuration
    // (in the 'temma.json' file)
    #[TµReferer(pathConfig: true)]
    public function action21() { }

    // authorized for a referer whose URL is 'https://www.fubar.com/some/page.html'
    #[TµReferer(url: 'https://www.fubar.com/some/page.html')]
    public function action22() { }

    // allowed for a referer whose URL is 'https://fu.com/bar'
    // or 'https://bar.com/fu'
    #[TµReferer(url: ['https://fu.com/bar', 'https://bar.com/fu'])]
    public function action23() { }

    // authorized for a referer whose URL validates the provided regular expression
    #[TµReferer(urlRegex: '/^.*$/')]
    public function action24() { }

    // authorized for a referer whose URL matches that stored in
    // the 'okURL' template variable
    #[TµReferer(urlVar: 'okURL')]
    public function action25() { }

    // authorized for a referer whose URL matches that stored in the
    // 'refererUrl' key of the 'x-security' extended configuration
    // (in the 'temma.json' file)
    #[TµReferer(urlConfig: true)]
    public function action26() { }

    // redirect to the defined URL if there is no referer
    #[TµReferer(redirect: '/login')]
    public function action27() { }

    // redirect to URL defined in 'redirRef' template variable
    #[TµReferer(redirectVar: 'redirRef')]
    public function action28() { }

    // redirect to the URL stored in the 'refererRedirect' key of
    // the 'x-security' extended configuration (in the 'temma.json' file)
    #[TµReferer(redirectConfig: true)]
    public function action29() { }
}
Previous: Method attribute helper
Next: Redirect attribute helper

Table of Contents