Atributo Auth

1Apresentação

Este atributo é usado para gerenciar como um controlador ou uma ação pode ser acessado, dependendo da autenticação do usuário, dos papéis atribuídos a ele e dos serviços aos quais ele tem direito de acesso.

2Variável de template $currentUser

Este atributo se baseia na existência de uma variável de template $currentUser, que contém informações sobre o usuário a partir do momento em que ele se autentica. Essa variável é normalmente definida por um pré-plugin.

A variável $currentUser deve ser um array associativo contendo as seguintes chaves:

  • id: (int) Identificador do usuário. Deve ser definido quando o usuário está autenticado.
  • roles: (array) Array associativo cujas chaves são os papéis do usuário (associadas ao valor true).
  • services: (array) Array associativo cujas chaves são os serviços aos quais o usuário tem acesso (associadas ao valor true).

3Parâmetros

O atributo oferece vários parâmetros:

  • $role: (string|array) Papel que o usuário deve ter, ou lista de papéis (o usuário deve ter pelo menos um). Se um papel começar com um traço (-), o usuário não deve ter esse papel.
  • $service: (string|array) Serviço ao qual o usuário deve ter acesso, ou lista de serviços (o usuário deve ter acesso a pelo menos um deles). Se um serviço começar com um traço (-), o usuário não deve ter acesso a esse serviço.
  • $authenticated: (null|bool) O efeito desse parâmetro depende do seu valor:
    • true: (valor padrão) O usuário deve estar autenticado para acessar o controlador ou a ação.
    • false: O usuário não deve estar autenticado.
    • null: O usuário pode estar autenticado ou não.
  • $redirect: (string) URL para a qual redirecionar o usuário se ele não estiver autorizado a acessar o controlador ou a ação.
  • $redirectVar: (string) Nome da variável de template contendo a URL para a qual redirecionar o usuário.
  • $storeUrl: (bool) Defina como true para que a URL requisitada seja armazenada na variável de sessão authRequestedUrl, quando o usuário é redirecionado por não estar autorizado. Essa variável pode ser usada, após a autenticação, para levar o usuário de volta à página que ele desejava acessar.

4Prioridade 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 authRedirect, 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.

Se nenhuma URL de redirecionamento for encontrada, um erro 401 é retornado.

5Configuração

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

<?php

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

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'
    ]
];

Se você tiver seu próprio mecanismo de autenticação (e, portanto, não usar o controlador/plugin Auth fornecido pelo Temma), pode ser que você queira usar uma variável de template que não se chame $currentUser. Nesse caso, você pode redefinir o nome da variável a ser usada pelo atributo, definindo a chave authVariable na configuração estendida x-security; a variável só precisa ser um array associativo contendo pelo menos a chave id. 

<?php

return [
    'x-security' => [
        'authVariable' => 'currentOrganization'
    ]
];

6Exemplos

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

/*
 * As ações deste controlador só são acessíveis
 * a usuários autenticados.
 */
#[TµAuth]
class Account extends \Temma\Web\Controller {
    // ...
}

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

/*
 * As ações só são acessíveis a usuários não
 * autenticados, com redirecionamento para a
 * página inicial.
 */
#[TµAuth(authenticated: false, redirect: '/')]
class Login extends \Temma\Web\Controller {
    // ...
}

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

class Login extends \Temma\Web\Controller {
    // autorizado para usuários com o papel "manager"
    #[TµAuth('manager')]
    public function action1() { }

    // igual ao anterior
    #[TµAuth(role: 'manager')]
    public function action1bis() { }

    // autorizado para usuários com o papel "manager" ou "writer"
    #[TµAuth(['manager', 'writer'])]
    public function action2() { }

    // igual ao anterior
    #[TµAuth(role: ['manager', 'writer'])]
    public function action2bis() { }

    // proibido para usuários com o papel "rookie"
    #[TµAuth('-rookie')]
    public function action3() { }

    // autorizado para usuários com o papel manager, mas sem o papel "rookie"
    #[TµAuth(['manager', '-rookie'])]
    public function action4() { }

    // autorizado para usuários com acesso ao serviço "images"
    #[TµAuth(service: 'images')]
    public function action5() { }

    // autorizado para usuários com acesso ao serviço "images" ou "text"
    #[TµAuth(service: ['images', 'text'])]
    public function action6() { }

    // proibido para usuários com acesso ao serviço "video"
    #[TµAuth(service: '-video')]
    public function action7() { }

    // autorizado para usuários que tenham os papéis "manager"
    //  e "writer" ao mesmo tempo
    #[TµAuth('manager')]
    #[TµAuth('writer')]
    public function action8() { }

    // redireciona usuários que não são administradores
    #[TµAuth('admin', redirect: '/login')]
    public function action9() { }
}

7Variáveis flash

Quando o atributo Auth impede o acesso a um controlador ou ação, e realiza um redirecionamento, ele registra o motivo do bloqueio em uma variável flash chamada __authError.

Essa variável pode conter os seguintes valores:

  • not_authenticated: o usuário não está autenticado, mas precisa estar para acessar o recurso.
  • authenticated: o usuário está autenticado, mas não precisa estar para acessar o recurso.
  • no_role: o usuário não possui nenhum dos papéis exigidos.
  • forbidden_role: o usuário possui um papel proibido.
    A variável flash __authErrorData contém o nome do primeiro papel proibido encontrado.
  • no_service: o usuário não tem acesso a nenhum dos serviços exigidos.
  • forbidden_service: o usuário tem acesso a um serviço proibido.
    A variável flash __authErrorData contém o nome do primeiro serviço proibido encontrado.