Attribut Auth

1Présentation

L'attribut Auth sert à gérer comment un contrôleur ou une action peut être accédé, en fonction de l'authentification des utilisateurs, des rôles qui leur sont assignés et des services pour lesquels ils ont des droits d'accès.

2Variable de template

Cet attribut se base sur l'existence d'une variable de template $currentUser qui contient des informations sur l'utilisateur à partir du moment où il s'est authentifié. Cette variable est habituellement positionnée par un pré-plugin.

La variable $currentUser doit être un tableau associatif contenant les clés suivantes :

id : (int) Identifiant de l'utilisateur. Doit être défini lorsque l'utilisateur est authentifié.
roles : (array) Tableau associatif dont les clés sont les rôles de l'utilisateur (associées à la valeur true).
services : (array) Tableau associatif dont les clés sont les services auxquels l'utilisateur a accès (associées à la valeur true).

3Paramètres

L'attribut propose plusieurs paramètres :

$role : (string|array) Rôle que l'utilisateur doit posséder, ou liste de rôles dont l'utilisateur doit posséder au moins un. Si un rôle est précédé d'un tiret (-), il ne faut pas que l'utilisateur le possède.
$service : (string|array) Service auquel l'utilisateur doit avoir accès, ou liste de services dont l'utilisateur doit avoir accès à au moins un. Si un service est précédé d'un tiret (-), il ne faut pas que l'utilisateur y ait accès.
$authenticated : (null|bool) L'effet de ce paramètre dépend de sa valeur :
- true : (valeur par défaut) L'utilisateur doit être authentifié pour accéder au contrôleur ou à l'action.
- false : L'utilisateur ne doit pas être authentifié.
- null : L'utilisateur peut être authentifié ou non.
$redirect : (string) URL vers laquelle rediriger l'utilisateur s'il n'a pas le droit d'accéder au contrôleur ou à l'action.
$redirectVar : (string) Nom de la variable de template contenant l'URL vers laquelle rediriger l'utilisateur.
$storeUrl : (bool) Mettre à true pour que l'URL demandée soit enregistrée dans la variable de session authRequestedUrl, lorsque l'utilisateur est redirigé car il n'est pas autorisé. Cela permet, après authentification, de ramener l'utilisateur vers la page à laquelle il souhaitait accéder.

4Priorité de redirection

Si l'accès est refusé, l'utilisateur peut être redirigé. Pour déterminer l'URL de redirection, l'attribut applique l'ordre de priorité suivant :

Si le paramètre $redirect est défini, il est utilisé.
Si le paramètre $redirectVar est défini, et qu'il contient le nom d'une variable de template qui existe et est non vide, le contenu de celle-ci est utilisé.
Si le fichier etc/temma.php contient une configuration étendue x-security, et que celle-ci contient une clé authRedirect, le contenu de celle-ci est utilisé.
Si le fichier etc/temma.php contient une configuration étendue x-security, et que celle-ci contient une clé redirect, le contenu de celle-ci est utilisé.

Si aucune URL de redirection n'a été trouvée, une erreur 401 est retournée.

5Configuration

Pour que tous les attributs Auth redirigent vers la même URL, il suffit de définir la clé authRedirect dans la configuration étendue x-security du fichier etc/temma.php :

<?php

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

Pour que l'URL de redirection soit la même pour les attributs Auth, Method, Referer et Redirect, il suffit de définir la clé redirect dans la configuration étendue x-security du fichier etc/temma.php :

<?php

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

Si vous avez votre propre mécanisme d'authentification (et que vous n'utilisez donc pas le contrôleur/plugin Auth fourni par Temma), vous pouvez vouloir utiliser une variable de template qui ne s'appelle pas $currentUser. Dans ce cas, vous pouvez redéfinir le nom de la variable que l'attribut doit utiliser, en définissant la clé authVariable dans la configuration étendue x-security ; il faut juste que la variable soit une tableau associatif contenant au moins la clé id.

<?php

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

6Exemples d'utilisation

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

/*
 * Les actions de ce contrôleur ne sont accessibles
 * qu'aux utilisateurs authentifiés.
 */
#[TµAuth]
class Account extends \Temma\Web\Controller {
    // ...
}

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

/*
 * Les actions ne sont accessible qu'aux utilisateurs
 * non authentifiés, avec une redirection vers la page
 * d'accueil.
 */
#[TµAuth(authenticated: false, redirect: '/')]
class Login extends \Temma\Web\Controller {
    // ...
}

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

class Login extends \Temma\Web\Controller {
    // autorisé pour les utilisateurs avec le rôle "manager"
    #[TµAuth('manager')]
    public function action1() { }

    // identique au précédent
    #[TµAuth(role: 'manager')]
    public function action1bis() { }

    // autorisé pour les utilisateurs avec le rôle "manager" ou "writer"
    #[TµAuth(['manager', 'writer'])]
    public function action2() { }

    // identique au précédent
    #[TµAuth(role: ['manager', 'writer'])]
    public function action2bis() { }

    // interdit aux utilisateurs ayant le rôle "rookie"
    #[TµAuth('-rookie')]
    public function action3() { }

    // autorisé pour les utilisateurs avec le rôle "manager", mais sans le rôle "rookie"
    #[TµAuth(['manager', '-rookie'])]
    public function action4() { }

    // autorisé pour les utilisateurs ayant accès au service "images"
    #[TµAuth(service: 'images')]
    public function action5() { }

    // autorisé pour les utilisateurs ayant accès au service "images" ou "text"
    #[TµAuth(service: ['images', 'text'])]
    public function action6() { }

    // interdit aux utilisateur ayant accès au service "video"
    #[TµAuth(service: '-video')]
    public function action7() { }

    // autorisé pour les utilisateurs qui ont en même temps les rôles
    // "manager" et "writer"
    #[TµAuth('manager')]
    #[TµAuth('writer')]
    public function action8() { }

    // redirige les utilisateurs qui ne sont pas des administrateurs
    #[TµAuth('admin', redirect: '/login')]
    public function action9() { }
}

7Variables flash

Lorsque l'attribut Auth empêche l'accès à un contrôleur ou une action, et qu'il effectue une redirection, il enregistre la raison du blocage dans une variable flash nommée __authError.

Voici les valeurs que peut contenir cette variable :

not_authenticated : l'utilisateur n'est pas authentifié, alors qu'il faut l'être pour accéder à la ressource.
authenticated : l'utilisateur est authentifié, alors qu'il ne faut pas l'être pour accéder à la ressource.
no_role : l'utilisateur ne possède aucun des rôles nécessaires.
forbidden_role : l'utilisateur possède un rôle interdit.
La variable flash __authErrorData contient alors le nom du premier rôle interdit trouvé.
no_service : l'utilisateur n'a accès à aucun des services nécessaires.
forbidden_service : l'utilisateur a accès à un service interdit.
La variable flash __authErrorData contient alors le nom du premier service interdit trouvé.