Contrôle d'accès avancé : access checkers, AccessResult et cacheabilité

· 6 min de lecture

Dans Drupal, une vérification d’accès ne répond pas seulement « oui » ou « non ». Elle répond aussi pour qui et pour combien de temps cette réponse est valable. Oublier cette deuxième partie, c’est prendre le risque qu’une décision calculée pour un administrateur soit servie depuis le cache à un simple visiteur.

Cet article couvre les access checkers personnalisés, la logique de AccessResult, ses métadonnées de cache, et la différence souvent mal comprise entre hook_entity_access et les node grants.

AccessResult : trois états, pas deux

Toute vérification d’accès moderne retourne un AccessResultInterface, avec trois états possibles :

  • allowed : j’autorise ;
  • neutral : je n’ai pas d’avis ;
  • forbidden : j’interdis, et personne ne peut passer outre.

Ils se combinent avec deux opérateurs :

orIf() andIf()
Un des deux est forbidden forbidden forbidden
Au moins un allowed allowed neutral si l’autre est neutral
Les deux allowed allowed allowed
Les deux neutral neutral neutral

C’est ce qui permet à plusieurs modules de voter sur le même accès : hook_entity_access est combiné avec orIf(), et un seul forbidden suffit à fermer la porte. Selon le contexte, un neutral final vaut un refus : c’est le cas pour l’accès aux routes, qui exige un allowed.

Surtout, orIf() et andIf() fusionnent les métadonnées de cache des résultats qui ont participé à la décision. Un résultat d’accès est un objet cacheable, au même titre qu’un render array.

Un access checker personnalisé

Cas d’usage : un site de gestion de projets. La page /project/{node}/reports doit être accessible aux membres du projet (un champ field_members qui référence des utilisateurs) et aux administrateurs.

La route

# my_module.routing.yml
my_module.project_reports:
  path: '/project/{node}/reports'
  defaults:
    _controller: '\Drupal\my_module\Controller\ProjectReportsController::view'
    _title: 'Rapports'
  requirements:
    _project_member: 'TRUE'
  options:
    parameters:
      node:
        type: entity:node

Le service

# my_module.services.yml
services:
  my_module.project_member_access:
    class: Drupal\my_module\Access\ProjectMemberAccessCheck
    tags:
      - { name: access_check, applies_to: _project_member }

Le tag access_check avec applies_to associe le service à la clé _project_member des requirements. Toutes les routes qui déclarent cette clé passent par lui.

La classe

<?php

namespace Drupal\my_module\Access;

use Drupal\Core\Access\AccessResult;
use Drupal\Core\Access\AccessResultInterface;
use Drupal\Core\Routing\Access\AccessInterface;
use Drupal\Core\Session\AccountInterface;
use Drupal\node\NodeInterface;

final class ProjectMemberAccessCheck implements AccessInterface {

  public function access(AccountInterface $account, NodeInterface $node): AccessResultInterface {
    if ($node->bundle() !== 'project') {
      return AccessResult::forbidden('Not a project.')->addCacheableDependency($node);
    }

    $is_member = in_array(
      $account->id(),
      array_column($node->get('field_members')->getValue(), 'target_id')
    );

    return AccessResult::allowedIfHasPermission($account, 'administer projects')
      ->orIf(
        AccessResult::allowedIf($is_member)
          ->addCacheContexts(['user'])
          ->addCacheableDependency($node)
      );
  }

}

Les arguments de access() sont résolus par leur nom et leur type : $account reçoit l’utilisateur courant, $node le paramètre de route déjà converti en entité. Vous pouvez aussi demander RouteMatchInterface $route_match, Route $route ou Request $request.

Le vrai sujet : les métadonnées de cache

Relisons le code sous l’angle du cache :

  • allowedIfHasPermission() ajoute automatiquement le contexte user.permissions.
  • allowedIf($is_member) ne sait rien de la façon dont $is_member a été calculé. C’est à vous de dire que le résultat dépend de l’utilisateur (user) et du nœud (addCacheableDependency($node), qui ajoute le tag node:42).
  • Sans addCacheableDependency($node), retirer un membre du projet n’invaliderait pas les résultats déjà en cache.

Où ça fuit en pratique

L’accès à la route elle-même n’est pas mis en cache tel quel. La fuite arrive quand ce résultat sert à construire un rendu : un lien « Voir les rapports » dans un bloc, un menu, un teaser.

// ❌ Le booléen perd toutes les métadonnées de cache.
$url = Url::fromRoute('my_module.project_reports', ['node' => $node->id()]);
if ($url->access()) {
  $build['reports'] = Link::fromTextAndUrl($this->t('Rapports'), $url)->toRenderable();
}

Ce bloc est mis en cache sans contexte user. Le premier utilisateur qui l’affiche décide pour tout le monde : si c’est un membre, tous les visiteurs voient le lien ; sinon, aucun membre ne le voit.

// ✅ L'objet AccessResult est passé à #access, le renderer fusionne sa cacheabilité.
$url = Url::fromRoute('my_module.project_reports', ['node' => $node->id()]);
$build['reports'] = Link::fromTextAndUrl($this->t('Rapports'), $url)->toRenderable();
$build['reports']['#access'] = $url->access(NULL, TRUE);

Le deuxième argument TRUE de access() demande un objet AccessResultInterface au lieu d’un booléen. Le renderer accepte cet objet dans #access et ajoute ses contextes et tags au rendu. La règle s’applique aussi à $entity->access('update', NULL, TRUE).

Et si le résultat n’est pas utilisé dans un render array ? Appliquez-le explicitement :

CacheableMetadata::createFromObject($access)->applyTo($build);

Choisir le bon contexte

Contexte Varie selon Cardinalité
user.permissions L’ensemble des permissions Faible
user.roles Les rôles Faible
user.roles:editor Le fait d’avoir le rôle editor 2 variantes
user L’utilisateur Une variante par utilisateur

Le contexte user est correct mais coûteux : il déclenche l’auto-placeholdering (voir l’article sur les lazy builders). Si l’accès dépend d’une donnée partagée par beaucoup d’utilisateurs (une équipe, une organisation), un contexte de cache personnalisé (un service tagué cache.context) réduit fortement le nombre de variantes.

hook_entity_access vs node grants

C’est la confusion la plus fréquente, et elle produit de vraies fuites de données.

hook_entity_access : décision au cas par cas

function my_module_node_access(NodeInterface $node, $operation, AccountInterface $account) {
  if ($operation === 'view' && $node->bundle() === 'project') {
    $members = array_column($node->get('field_members')->getValue(), 'target_id');
    return AccessResult::forbiddenIf(!in_array($account->id(), $members))
      ->addCacheContexts(['user'])
      ->addCacheableDependency($node);
  }
  return AccessResult::neutral();
}

Ce hook est appelé quand une entité précise est vérifiée : affichage d’une page, $node->access(), rendu d’une entité. Il n’est pas appelé quand une requête liste des entités. Une vue « Derniers projets » affichera donc les titres de projets dont l’utilisateur n’est pas membre, même s’il obtient une 403 en cliquant.

Notez aussi que hook_node_access() n’est pas invoqué pour les utilisateurs qui ont la permission bypass node access.

Node grants : décision appliquée aux requêtes

Le système de grants (hook_node_access_records() + hook_node_grants()) stocke les droits dans la table node_access. Drupal les injecte automatiquement dans toutes les requêtes marquées node_access, ce qui comprend les entity queries avec accessCheck(TRUE) et les Views (sauf si « Disable SQL rewriting » est coché).

function my_module_node_access_records(NodeInterface $node) {
  if ($node->bundle() !== 'project') {
    return [];
  }
  $grants = [];
  foreach ($node->get('field_members') as $item) {
    $grants[] = [
      'realm' => 'project_member',
      'gid' => $item->target_id,
      'grant_view' => 1,
      'grant_update' => 0,
      'grant_delete' => 0,
    ];
  }
  return $grants;
}

function my_module_node_grants(AccountInterface $account, $operation) {
  return ['project_member' => [$account->id()]];
}

Le prix à payer : les grants sont précalculés. Modifier la logique impose de reconstruire les permissions (node_access_rebuild()), une opération longue sur un gros site. Ils ne concernent que les nœuds.

Et les autres entités ?

Pour les entités qui ne sont pas des nœuds, les entity queries avec accessCheck(TRUE) ajoutent le tag {entity_type}_access (par exemple media_access). Vous pouvez filtrer les listes avec hook_query_TAG_alter(), ou utiliser le module contrib Entity API, qui fournit un « query access » générique (événement entity.query_access) pour les entités qui le déclarent.

Drupal 10 : une entity query sur une entité de contenu doit appeler ->accessCheck(TRUE) ou ->accessCheck(FALSE) explicitement, sinon une exception est levée. C’est le bon moment pour relire chaque accessCheck(FALSE) de votre code : chacun est une liste qui ignore les droits.

Résumé

Besoin Outil
Protéger une route Access checker (_custom_access ou tag access_check)
Décider de l’accès à une entité affichée hook_entity_access / hook_ENTITY_TYPE_access
Filtrer des listes de nœuds Node grants
Filtrer des listes d’autres entités hook_query_TAG_alter() sur {entity_type}_access

Tester l’accès et sa cacheabilité

Un test Kernel peut vérifier les deux en même temps :

public function testMemberAccess(): void {
  $member = $this->createUser();
  $stranger = $this->createUser();
  $project = $this->createNode(['type' => 'project', 'field_members' => [$member->id()]]);

  $check = new ProjectMemberAccessCheck();

  $result = $check->access($member, $project);
  $this->assertTrue($result->isAllowed());
  $this->assertContains('user', $result->getCacheContexts());
  $this->assertContains('node:' . $project->id(), $result->getCacheTags());

  $this->assertFalse($check->access($stranger, $project)->isAllowed());
}

Les assertions sur les contextes et les tags sont celles qui manquent le plus souvent, alors que ce sont elles qui protègent contre les fuites en production.

Conclusion

Un contrôle d’accès correct dans Drupal a deux dimensions : la décision, et sa cacheabilité. Retournez des objets AccessResult plutôt que des booléens, déclarez systématiquement de quoi dépend la décision, et choisissez entre hook_entity_access et node grants selon qu’il faut protéger une entité ou une liste. Ce sont trois réflexes simples qui évitent les failles les plus courantes sur les sites Drupal.

Suite de la série →Post-mortem : CPU spike à 100% en production Drupal — analyse et résolution