Presentation

This attribute is used to manage how a controller or action can be accessed, depending on user authentication, the roles assigned to them and the services for which they have access rights.

$currentUser template variable

This attribute is based on the existence of a $currentUser template variable, which contains information about the user from the moment he/she logs in. This variable is usually set by a pre-plugin.

The $currentUser variable must be an associative array containing the following keys:

• id: (int) User identifier. Must be set when the user is authenticated.
• roles: (array) Associative array whose keys are the user's roles (associated with the value true).
• services: (array) Associative array whose keys are the services to which the user has access (associated with the value true).

Parameters

The attribute offers several parameters:

• $role: (string) Role the user must have, or list of roles (the user must have at least one).
• $service: (string) Service to which the user must have access, or list of services (the user must have access to at least one of them).
• $authenticated: (null|bool) The effect of this parameter depends on its value:
  • true: (default value) The user must be authenticated to access the controller or action.
  • false: The user must not be authenticated.
  • null: The user may or may not be authenticated.
• $redirect: (string) URL to redirect to if the user is not authorized to access the controller or action.
• $redirectVar: (string) Name of the template variable containing the URL to redirect the user to.
• $storeUrl: (bool) Set to true so that the requested URL is stored in the authRequestedUrl session variable, when the user is redirected because he is not authorized. This variable can be used after authentication to take users back to the page they wished to access.

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 an authRedirect 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.

If no redirection URL is found, a 401 error is returned.

Configuration

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

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

To ensure that the redirection 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\Auth as TµAuth;

/*
 * The actions of this controller are accessible
 * only to authenticated users.
 */
#[TµAuth]
class Account extends \Temma\Web\Controller {
    // ...
}

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

/*
 * Actions are accessible only to unauthenticated
 * users, with a redirection to the logout page.
 */
#[TµAuth(authenticated: false, redirect: '/logout')]
class Login extends \Temma\Web\Controller {
    // ...
}

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

class Login extends \Temma\Web\Controller {
    // authorized for users with the "manager" role
    #[TµAuth('manager')]
    public function action1() { }

    // same as previous
    #[TµAuth(role: 'manager')]
    public function action1bis() { }

    // authorized for users with the "manager" or "writer" role
    #[TµAuth(['manager', 'writer'])]
    public function action2() { }

    // same as previous
    #[TµAuth(role: ['manager', 'writer'])]
    public function action2bis() { }

    // authorized for users with access to the "images" service
    #[TµAuth(service: 'images')]
    public function action3() { }

    // authorized for users with access to the "images" or "text" service
    #[TµAuth(service: ['images', 'text'])]
    public function action4() { }

    // authorized for users who have the "manager"
    //  and "writer" roles at the same time
    #[TµAuth('manager')]
    #[TµAuth('writer')]
    public function action5() { }

    // redirects non-administrator users
    #[TµAuth('admin', redirect: '/login')]
    public function action6() { }
}