Auth attribute

1Presentation

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.

2$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).

3Parameters

The attribute offers several parameters:

$role: (string) Role the user must have, or list of roles (the user must have at least one). If a role starts with a dash (-), the user must have not this role.
$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). If a service starts with a dash (-), the user must not have access to this service.
$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.

4Redirection priority

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

If the $redirect parameter is set, it is used.
If the $redirectVar parameter is defined, and it contains the name of an existing, non-empty template variable, its content is used.
If the etc/temma.php file contains an x-security extended configuration, and this contains an authRedirect key, its content is used.
If the etc/temma.php 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.

5Configuration

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

<?php

return [
    '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 etc/temma.php file:

<?php

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

If you have your own authentication mechanism (and therefore don't use the Auth controller/plugin supplied by Temma), you may want to use a template variable not named $currentUser. In this case, you can redefine the name of the variable to be used by the attribute, by defining the authVariable key in the x-security extended configuration; the variable just needs to be an associative array containing at least the id key.

<?php

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

6Examples

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() { }

    // forbidden for users with the "rookie" role
    #[TµAuth('-rookie')]
    public function action3() { }

    // authorized for users with the manager role, but without the "rookie" role
    #[TµAuth(['manager', '-rookie'])]
    public function action4() { }

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

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

    // forbidden for users with access to the "video" service
    #[TµAuth(service: '-video')]
    public function action7() { }

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

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

7Flash variables

When the Auth attribute prevents access to a controller or action, and performs a redirection, it records the reason for the block in a flash variable named __authError.

This variable can contain the following values:

not_authenticated: the user is not authenticated, but must be to access the resource.
authenticated: the user is authenticated, but does not need to be to access the resource.
no_role: the user has none of the required roles.
forbidden_role: the user has a forbidden role.
The flash variable __authErrorData contains the name of the first forbidden role found.
no_service: the user has no access to any of the required services.
forbidden_service: the user has access to a forbidden service.
The flash variable __authErrorData contains the name of the first forbidden service found.