Atributo Referer

---

1Apresentação

Este atributo é usado para proteger o acesso a um controlador ou uma ação com base no valor do cabeçalho HTTP REFERER.

---

2Parâmetros

O atributo oferece vários parâmetros:

• $domain: (bool|string|array) Indica o domínio do referer (se true, o domínio deve ser idêntico ao domínio atual), ou uma lista de domínios (o referer deve ser igual a um deles).
• $domainSuffix: (string|array) Sufixo do domínio do referer, ou lista de sufixos.
• $domainRegex: (string) Expressão regular a ser validada pelo domínio do referer.
• $domainVar: (string) Nome da variável de template contendo o domínio ao qual o domínio do referer deve corresponder.
• $domainConfig: (bool) Defina como true para usar a chave refererDomain da configuração estendida x-security (no arquivo etc/temma.php).
• $https: (bool|string) O efeito desse parâmetro depende do seu valor:
  • null: (valor padrão) O referer pode ser em HTTP ou HTTPS.
  • true: O referer deve ser HTTPS.
  • false: O referer deve ser HTTP.
  • 'same': O referer deve usar o mesmo protocolo (HTTP/HTTPS) do site atual.
• $path: (string|array) Caminho ou lista de caminhos do referer.
• $pathPrefix: (string|array) Prefixo do caminho do referer, ou lista de prefixos.
• $pathSuffix: (string|array) Sufixo do caminho do referer, ou lista de sufixos.
• $pathRegex: (string) Expressão regular que o caminho do referer deve validar.
• $pathVar: (string) Nome da variável de template contendo o caminho do referer.
• $pathConfig: (bool) Defina como true para usar a chave refererPath da configuração estendida x-security (no arquivo etc/temma.php).
• $url: (string|array) URL ou lista de URLs do referer.
• $urlRegex: (string) Expressão regular a ser validada pela URL do referer.
• $urlVar: (string) Nome da variável de template contendo a URL do referer.
• $urlConfig: (bool) Defina como true para usar a chave refererUrl da configuração estendida x-security (no arquivo etc/temma.php).
• $redirect: (string) URL para a qual redirecionar os usuários que não têm direito de acessar o controlador ou a ação (em vez de exibir uma página de erro).
• $redirectVar: (string) Nome da variável de template contendo a URL para a qual redirecionar o usuário.

---

3Prioridade de redirecionamento

Se o acesso for negado, o usuário pode ser redirecionado. Para determinar a URL de redirecionamento, o atributo aplica a seguinte ordem de prioridade:

1. Se o parâmetro $redirect estiver definido, ele é usado.
2. Se o parâmetro $redirectVar estiver definido, e contiver o nome de uma variável de template existente e não vazia, seu conteúdo é usado.
3. Se o arquivo etc/temma.php contiver uma configuração estendida x-security, e esta contiver uma chave refererRedirect, seu conteúdo é usado.
4. Se o arquivo etc/temma.php contiver uma configuração estendida x-security, e esta contiver uma chave redirect, seu conteúdo é usado.

---

4Configuração

Para garantir que todos os atributos Referer redirecionem para a mesma URL, basta definir a chave refererRedirect na configuração estendida x-security do arquivo etc/temma.php:

<?php

return [
    'x-security' => [
        'refererRedirect' => '/failure'
    ]
];

Para garantir que a URL de redirecionamento seja a mesma para os atributos Auth, Method, Referer e Redirect, basta definir a chave redirect na configuração estendida x-security do arquivo etc/temma.php:

<?php

return [
    'x-security' => [
        'redirect' => '/login'
    ]
];

---

5Exemplos

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

class Admin extends \Temma\Web\Controller {
    // acesso proibido para requisições sem referer
    #[TµReferer]
    public function action1() { }

    // autorizado apenas para requisições do mesmo domínio
    #[TµReferer(true)]
    public function action2() { }

    // permitido para o domínio 'fubar.com'
    #[TµReferer('fubar.com')]
    public function action3() { }

    // igual ao anterior
    #[TµReferer(domain: 'fubar.com')]
    public function action3bis() { }

    // permitido para os domínios 'fubar.com' e 'www.fubar.com'
    #[TµReferer(['fubar.com', 'www.fubar.com'])]
    public function action4() { }

    // igual ao anterior
    #[TµReferer(domain: ['fubar.com', 'www.fubar.com'])]
    public function action4bis() { }

    // permitido para domínios terminados em '.fubar.com'.
    #[TµReferer(domainSuffix: '.fubar.com')]
    public function action5() { }

    // permitido para domínios terminados em '.fubar.com' ou '.foobar.com'.
    #[TµReferer(domainSuffix: ['.fubar.com', '.foobar.com'])]
    public function action6() { }

    // permitido para domínios que validam a expressão regular fornecida
    #[TµReferer(domainRegex: '^test\d?.fubar.(com|net)$')]
    public function action7() { }

    // autorizado para o domínio cujo nome está armazenado
    // na variável de template 'okDomain'
    #[TµReferer(domainVar: 'okDomain')]
    public function action8() { }

    // autorizado para o domínio definido na chave 'refererDomain' da
    // configuração estendida 'x-security' (no arquivo 'etc/temma.php')
    #[TµReferer(domainConfig: true)]
    public function action9() { }

    // autorizado para um referer HTTP
    #[TµReferer(https: false)]
    public function action10() { }

    // autorizado para um referer HTTPS
    #[TµReferer(https: true)]
    public function action11() { }

    // autorizado para um referer cujo protocolo (HTTP/HTTPS)
    // é o mesmo do site atual
    #[TµReferer(https: 'same')]
    public function action12() { }

    // autorizado para um referer com o caminho '/fu/bar.html'.
    #[TµReferer(path: '/fu/var.html')]
    public function action13() { }

    // permitido para um referer com o caminho '/fu.html' ou '/bar.html'
    #[TµReferer(path: ['/fu.html', '/bar.html'])]
    public function action14() { }

    // permitido para um referer cujo caminho começa com '/fu/'
    #[TµReferer(pathPrefix: '/fu/')]
    public function action15() { }

    // autorizado para um referer cujo caminho começa com '/fu/' ou '/bar/'
    #[TµReferer(pathPrefix: ['/fu/', '/bar/'])]
    public function action16() { }

    // permitido para um referer cujo caminho termina com '/api.xml'
    #[TµReferer(pathSuffix: '/api.xml')]
    public function action17() { }

    // autorizado para um referer cujo caminho termina com '/api.xml' ou '/api.json'
    #[TµReferer(pathSuffix: ['/api.xml', '/api.json'])]
    public function action18() { }

    // autorizado para um referer cujo caminho valida a expressão regular fornecida
    #[TµReferer(pathRegex: '/^\/.*testApi.*\.xml$/')]
    public function action19() { }

    // autorizado para um referer cujo caminho corresponde ao armazenado
    // na variável de template 'okPath'
    #[TµReferer(pathVar: 'okPath')]
    public function action20() { }

    // autorizado para um referer cujo caminho corresponde ao armazenado
    // na chave 'refererPath' da configuração estendida 'x-security'
    // (no arquivo 'etc/temma.php')
    #[TµReferer(pathConfig: true)]
    public function action21() { }

    // autorizado para um referer cuja URL é 'https://www.fubar.com/some/page.html'
    #[TµReferer(url: 'https://www.fubar.com/some/page.html')]
    public function action22() { }

    // permitido para um referer cuja URL é 'https://fu.com/bar'
    // ou 'https://bar.com/fu'
    #[TµReferer(url: ['https://fu.com/bar', 'https://bar.com/fu'])]
    public function action23() { }

    // autorizado para um referer cuja URL valida a expressão regular fornecida
    #[TµReferer(urlRegex: '/^.*$/')]
    public function action24() { }

    // autorizado para um referer cuja URL corresponde à armazenada
    // na variável de template 'okURL'
    #[TµReferer(urlVar: 'okURL')]
    public function action25() { }

    // autorizado para um referer cuja URL corresponde à armazenada na
    // chave 'refererUrl' da configuração estendida 'x-security'
    // (no arquivo 'etc/temma.php')
    #[TµReferer(urlConfig: true)]
    public function action26() { }

    // redireciona para a URL definida se não houver referer
    #[TµReferer(redirect: '/login')]
    public function action27() { }

    // redireciona para a URL definida na variável de template 'redirRef'
    #[TµReferer(redirectVar: 'redirRef')]
    public function action28() { }

    // redireciona para a URL armazenada na chave 'refererRedirect' da
    // configuração estendida 'x-security' (no arquivo 'etc/temma.php')
    #[TµReferer]
    public function action29() { }
}