Contrôler les fonctionnalités du navigateur avec des règles d'autorisation

Gérez l'accès de votre page et des iFrames tiers à votre page aux fonctionnalités du navigateur.

Kevin K. Lee

La règle d'autorisation, anciennement appelée règle de fonctionnalité, permet au développeur de contrôler les fonctionnalités du navigateur disponibles pour une page, ses iframes et ses sous-ressources, en déclarant un ensemble de règles que le navigateur doit appliquer. Ces règles s'appliquent aux origines fournies dans une liste d'origines d'en-tête de réponse. La liste des origines peut contenir des origines identiques et/ou différentes, et permet au développeur de contrôler l'accès des propriétaires et des tiers aux fonctionnalités du navigateur.

C'est l'utilisateur qui prend la décision finale d'autoriser l'accès à des fonctionnalités plus puissantes. Il doit fournir une autorisation explicite en acceptant une invite.

La stratégie d'autorisations permet au site de niveau supérieur de définir ce que lui et ses tiers ont l'intention d'utiliser, et décharge l'utilisateur de la tâche de déterminer si la demande d'accès à la fonctionnalité est légitime ou non. Par exemple, en utilisant la stratégie d'autorisation pour bloquer la fonctionnalité de géolocalisation pour tous les tiers, le développeur peut être certain qu'aucun tiers n'aura accès à la géolocalisation de l'utilisateur.

Remarque:La Privacy Sandbox est une série de propositions et d'API permettant de répondre aux cas d'utilisation tiers sans cookies tiers ni autres mécanismes de suivi. Les API Privacy Sandbox, telles que les indices client User-Agent et l'API Topics, sont gérées par le règlement sur les autorisations de la même manière que les fonctionnalités telles que geolocation et camera. Pour obtenir la liste des API de plate-forme Web qui s'appuient sur le règlement sur les autorisations, consultez la liste des fonctionnalités. Notez que cette liste peut ne pas être à jour.

Modifications apportées au règlement sur les autorisations

Le règlement sur les autorisations était auparavant appelé règlement sur les fonctionnalités. Les concepts clés restent les mêmes, mais le nom a changé et certains changements importants ont été apportés.

Utilisation des champs structurés

Les champs structurés fournissent un ensemble de structures de données courantes pour normaliser l'analyse et la sérialisation des valeurs des champs d'en-tête HTTP. Pour en savoir plus sur les champs structurés, consultez l'article de blog de Fastly intitulé Améliorer HTTP avec des champs d'en-tête structurés.

Ancienne version

  geolocation 'self' https://example.com; camera 'none'

Avant avec la règle de caractéristiques.

Nouveau

  geolocation=(self "https://example.com"), camera=()

Désormais, avec le règlement sur les autorisations.

Combiner des en-têtes avec l'attribut allow de l'iFrame

Avec la stratégie de fonctionnalité, vous pouvez ajouter la fonctionnalité à un frame inter-origine en ajoutant l'origine à la liste des origines de l'en-tête ou en ajoutant un attribut allow à la balise iFrame. Avec la règle d'autorisation, si vous ajoutez un cadre inter-origine à la liste des origines, la balise iFrame de cette origine doit inclure l'attribut allow. Si la réponse ne contient pas d'en-tête de règles d'autorisation, la valeur par défaut de la liste des origines est considérée comme étant *. L'ajout de l'attribut allow à l'iframe permet d'accéder à la fonctionnalité.

Par conséquent, nous recommandons aux développeurs de définir explicitement l'en-tête de la règle d'autorisation dans la réponse afin que les iFrames inter-origines qui ne figurent pas dans la liste des origines ne puissent pas accéder à cette fonctionnalité, même si allow est présent.

Vous pouvez toujours utiliser la règle de fonctionnalité après Chrome 88, mais elle sert d'alias pour la règle d'autorisations. À l'exception de la syntaxe, il n'y a aucune différence de logique. Si les en-têtes de règles d'autorisation et de règles de fonctionnalités sont utilisés ensemble, l'en-tête Permissions-Policy aura une priorité plus élevée et écrasera la valeur fournie par l'en-tête Feature-Policy.

Comment utiliser la stratégie d'autorisation ?

Présentation rapide

Avant d'entrer dans le vif du sujet, examinons un scénario courant : vous êtes le propriétaire d'un site Web et vous souhaitez contrôler la façon dont votre site et le code tiers utilisent les fonctionnalités du navigateur.

• Votre site est https://your-site.example.
• Votre site intègre une iFrame de même origine (https://your-site.example).
• Votre site intègre un iFrame provenant d'https://trusted-site.example, que vous considérez comme fiable.
• Votre site affiche également des annonces diffusées par https://ad.example.
• Vous souhaitez autoriser la géolocalisation uniquement pour votre site et le site de confiance, et non pour l'annonce.

Dans ce cas, utilisez l'en-tête suivant:

Permissions-Policy: geolocation=(self "https://trusted-site.example")

Définissez explicitement l'attribut allow sur la balise iFrame pour le site approuvé:

<iframe src="https://trusted-site.example" allow="geolocation">

Dans cet exemple, la liste des origines d'en-tête n'autorise que votre site (self) et trusted-site.example à utiliser la fonctionnalité de géolocalisation. ad.example n'est pas autorisé à utiliser la géolocalisation.

1. Votre site your-site.example est autorisé à utiliser la fonctionnalité de géolocalisation avec le consentement de l'utilisateur.
2. Un iFrame de même origine (your-site.example) est autorisé à utiliser la fonctionnalité sans utiliser l'attribut allow.
3. Une iFrame diffusée à partir d'un sous-domaine (subdomain.your-site-example) différent qui n'a pas été ajouté à la liste des origines et dont l'attribut allow est défini sur la balise iFrame ne peut pas utiliser la fonctionnalité. Les différents sous-domaines sont considérés comme des sites du même domaine, mais d'origine différente.
4. Un iframe inter-origine (trusted-site.example) ajouté à la liste des origines et dont l'attribut allow est défini sur la balise iframe est autorisé à utiliser la fonctionnalité.
5. Un iframe inter-origine (trusted-site.example) ajouté à la liste des origines, sans l'attribut allow, est bloqué pour utiliser la fonctionnalité.
6. Un élément iframe inter-origine (ad.example) qui n'a pas été ajouté à la liste des origines ne peut pas utiliser la fonctionnalité, même si l'attribut allow est inclus dans la balise iframe.

En-tête de réponse HTTP Permissions-Policy

Permissions-Policy: <feature>=(<token>|<origin(s)>)

Utilisez un en-tête Permissions-Policy dans la réponse du serveur pour définir les origines autorisées pour une fonctionnalité. La valeur de l'en-tête peut prendre une combinaison de jetons et de chaînes d'origines. Les jetons disponibles sont * pour toutes les origines et self pour la même origine.

Si votre en-tête concerne plusieurs fonctionnalités, séparez-les par une virgule. Si vous indiquez plusieurs origines, séparez-les par un espace. Pour les en-têtes qui listent une origine qui est une requête inter-origines, la balise iframe doit inclure l'attribut allow.

Voici quelques exemples de paires clé-valeur:

• Syntaxe: [FEATURE]=*
  • Règle appliquée à toutes les origines
  • Exemple : geolocation=*
• Syntaxe: [FEATURE]=(self)
  • Règle appliquée à la même origine
  • Exemple : geolocation=(self)
• Syntaxe: [FEATURE]=(self [ORIGIN(s)])
  • Règle appliquée à la même origine et aux origines spécifiées
  • Exemple : geolocation=(self "https://a.example" "https://b.example")
  • self est un raccourci de https://your-site.example
• Syntaxe: [FEATURE]=([ORIGIN(s)])
  • Règle appliquée à la même origine et aux origines spécifiées
  • Exemple : geolocation=("https://your-site.example" "https://a.example" "https://b.example")
  • Lorsque vous utilisez cette syntaxe, l'une des origines doit être celle de l'intégrateur. Si les autorisations ne sont pas accordées à la page d'intégration elle-même, les iFrames intégrées à cette page seront également bloquées, même si elles sont ajoutées à la liste des origines, car le règlement sur les autorisations délègue les autorisations. Vous pouvez également utiliser le jeton self.
• Syntaxe: [FEATURE]=()
  • Fonctionnalité bloquée pour toutes les origines
  • Exemple : geolocation=()

Avertissement:Si l'en-tête de la stratégie d'autorisation n'est pas présent dans la réponse, le jeton * par défaut est utilisé. Cela permet à tous les éléments iframe de la page avec un attribut allow d'utiliser la fonctionnalité. Par conséquent, nous vous recommandons vivement de définir explicitement la liste des origines dans l'en-tête Permissions-Policy pour contrôler l'accès.

Point clé:Avec le changement de la règle d'autorisations par rapport à la règle de fonctionnalité, il n'est plus suffisant d'ajouter l'origine à la liste des origines de l'en-tête pour activer la fonctionnalité pour un iframe inter-origine. L'iframe doit inclure l'attribut allow s'il est multidomaine, quel que soit ce qui est défini dans la liste des origines de l'en-tête.

Différents sous-domaines et chemins

Les différents sous-domaines, tels que https://your-site.example et https://subdomain.your-site.example, sont considérés comme de même site, mais d'origine différente. Par conséquent, l'ajout d'un sous-domaine à la liste des origines n'autorise pas l'accès à un autre sous-domaine du même site. Chaque sous-domaine intégré qui souhaite utiliser la fonctionnalité doit être ajouté séparément à la liste des origines. Par exemple, si l'accès aux sujets de navigation de l'utilisateur n'est autorisé que pour la même origine avec l'en-tête Permissions-Policy: browsing-topics=(self), une iframe provenant d'un autre sous-domaine du même site, https://subdomain.your-site.example, n'aura pas accès aux sujets.

Les chemins d'accès différents, tels que https://your-site.example et https://your-site.example/embed, sont considérés comme de même origine, et ils ne doivent pas nécessairement figurer dans la liste des origines.

Attribut allow d'iFrame

Pour une utilisation inter-origine, un iframe a besoin de l'attribut allow dans la balise pour accéder à la fonctionnalité.

Syntaxe : <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>

Exemple :

<iframe src="https://trusted-site.example" allow="geolocation">

Remarque:La syntaxe allow="geolocation" est un raccourci pour allow="geolocation 'src'". src est un jeton spécial qui se développe dans l'origine de l'attribut src de l'iFrame.

Gérer la navigation iFrame

Par défaut, si un iframe accède à une autre origine, la règle n'est pas appliquée à l'origine à laquelle l'iframe accède. En listant l'origine vers laquelle l'iframe navigue dans l'attribut allow, la stratégie d'autorisation appliquée à l'iframe d'origine sera appliquée à l'origine vers laquelle l'iframe navigue.

<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">

Pour voir comment cela fonctionne, consultez la démonstration de navigation dans une iFrame.

Exemples de configurations de règles d'autorisation

Vous trouverez des exemples des configurations suivantes dans la démonstration.

Fonctionnalité autorisée pour toutes les origines

Permissions-Policy: geolocation=*

<iframe src="https://trusted-site.example" allow="geolocation">
<iframe src="https://ad.example" allow="geolocation">

Lorsque la liste d'origines est définie sur le jeton *, la fonctionnalité est autorisée pour toutes les origines présentes sur la page, y compris elle-même et toutes les iFrames. Dans cet exemple, tout le code diffusé à partir de https://your-site.example et les codes diffusés à partir de l'iframe https://trusted-site.example et de https://ad.example ont accès à la fonctionnalité de géolocalisation dans le navigateur de l'utilisateur. N'oubliez pas que l'attribut "allow" doit également être défini sur l'iframe lui-même, et que l'origine doit être ajoutée à la liste des origines de l'en-tête.

Cette configuration est illustrée dans la démonstration.

Fonctionnalité autorisée uniquement pour la même origine

Permissions-Policy: geolocation=(self)

L'utilisation du jeton self permet d'utiliser la géolocalisation uniquement pour la même origine. Les origines croisées n'auront pas accès à cette fonctionnalité. Dans cet exemple, seul https://trusted-site.example (self) aura accès à la géolocalisation. Utilisez cette syntaxe si vous souhaitez que cette fonctionnalité ne s'applique qu'à votre page.

Cette configuration est illustrée dans la démonstration.

Fonctionnalité autorisée pour les pages de même origine et les pages multi-origines spécifiques

Permissions-Policy: geolocation=(self "https://trusted-site.example")

Cette syntaxe permet d'utiliser la géolocalisation pour soi-même (https://your-site.example) et https://trusted-site.example. N'oubliez pas d'ajouter explicitement l'attribut "allow" à la balise iFrame. Si un autre iFrame contient <iframe src="https://ad.example" allow="geolocation">, https://ad.example n'aura pas accès à la fonctionnalité de géolocalisation. Seule la page d'origine et le https://trusted-site.example figurant dans la liste des origines et dont l'attribut "allow" est défini dans la balise iframe auront accès à la fonctionnalité de l'utilisateur.

Cette configuration est illustrée dans la démonstration.

Fonctionnalité bloquée sur toutes les origines

Permissions-Policy: geolocation=()

Si la liste d'origine est vide, la fonctionnalité est bloquée pour toutes les origines. Cette configuration est illustrée dans la démonstration.

Important:Il n'est pas possible d'autoriser la fonctionnalité pour les éléments intégrés multi-domaines si elle est bloquée pour les éléments intégrés de même origine. Étant donné que les autorisations appliquées à la page parente sont déléguées aux iFrames intégrées, la fonctionnalité doit être activée pour la même origine si elle doit être autorisée pour les origines différentes.

Utiliser l'API JavaScript

L'API JavaScript existante de la règle de fonctionnalité se trouve sous la forme d'un objet dans le document ou l'élément (document.featurePolicy or element.featurePolicy). L'API JavaScript pour la règle d'autorisation n'a pas encore été implémentée.

L'API Feature Policy peut être utilisée pour les règles définies par le règlement sur les autorisations, à quelques exceptions près. Des questions restent en suspens concernant l'implémentation d'une API JavaScript. Une proposition a été faite pour déplacer la logique dans l'API Permissions. Rejoignez la discussion si vous avez des commentaires.

featurePolicy.allowsFeature(feature)

• Renvoie true si la fonctionnalité est autorisée pour l'utilisation de l'origine par défaut.
• Le comportement est le même pour les règles définies par la règle d'autorisation et la règle de fonctionnalité précédente.
• Lorsque allowsFeature() est appelé sur un élément iframe (iframeEl.featurePolicy.allowsFeature('geolocation')), la valeur renvoyée indique si l'attribut allow est défini sur l'iframe.

featurePolicy.allowsFeature(feature, origin)

• Renvoie true si la fonctionnalité est autorisée pour l'origine spécifiée.
• Si la méthode est appelée sur document, elle ne vous indique plus si la fonctionnalité est autorisée pour l'origine spécifiée, comme le faisait la règle de fonctionnalité. Cette méthode vous indique maintenant qu'il est possible que la fonctionnalité soit autorisée pour cette origine. Vous devez vérifier si l'attribut allow est défini ou non dans l'iframe. Le développeur doit effectuer une vérification supplémentaire de l'attribut allow sur l'élément iframe pour déterminer si la fonctionnalité est autorisée pour l'origine tierce.

Rechercher des fonctionnalités dans un iframe avec l'objet element

Vous pouvez utiliser element.allowsFeature(feature), qui tient compte de l'attribut "allow", contrairement à document.allowsFeature(feature, origin).

const someIframeEl = document.getElementById('some-iframe')
const isCameraFeatureAllowed = someIframeEl.featurePolicy.allowsFeature('camera')

featurePolicy.allowedFeatures()

• Renvoie la liste des fonctionnalités autorisées pour l'utilisation de l'origine par défaut.
• Le comportement est le même pour les deux règles définies par la règle d'autorisations et la règle de fonctionnalités.
• Lorsque le nœud associé est un iframe, l'attribut allow est pris en compte.

featurePolicy.features()

• Affiche la liste des fonctionnalités disponibles dans le navigateur.
• Le comportement est le même pour les deux règles définies par la règle d'autorisations et la règle de fonctionnalités.

Intégration des outils pour les développeurs Chrome

Découvrez le fonctionnement de la stratégie d'autorisations dans DevTools.

1. Accédez aux outils pour les développeurs Chrome.
2. Ouvrez le panneau Application pour vérifier les fonctionnalités autorisées et non autorisées de chaque frame.
3. Dans la barre latérale, sélectionnez le frame que vous souhaitez inspecter. Une liste des fonctionnalités que le frame sélectionné est autorisé à utiliser et une liste des fonctionnalités bloquées dans ce frame s'affichent.

Migration depuis Feature-Policy

Si vous utilisez l'en-tête Feature-Policy, vous pouvez suivre la procédure ci-dessous pour migrer vers la stratégie d'autorisations.

Remplacer les en-têtes de règles de fonctionnalités par des en-têtes de règles d'autorisations

Étant donné que les en-têtes de règles de fonctionnalités ne sont compatibles qu'avec les navigateurs basés sur Chromium et que les en-têtes de règles d'autorisation sont compatibles depuis Chrome 88, vous pouvez mettre à jour les en-têtes existants avec les règles d'autorisation.

Ancienne version

Feature-Policy:
  autoplay *;
  geolocation 'self';
  camera 'self' 'https://trusted-site.example';
  fullscreen 'none';

Avant avec la règle de caractéristiques.

Nouveau

Permissions-Policy:
  autoplay=*,
  geolocation=(self),
  camera=(self "https://trusted-site.example"),
  fullscreen=()

Désormais, avec le règlement sur les autorisations.

Modifier l'utilisation de document.allowsFeature(feature, origin)

Si vous utilisez la méthode document.allowsFeature(feature, origin) pour vérifier les fonctionnalités autorisées pour les iFrames, utilisez la méthode allowsFeature(feature) associée à l'élément iFrame, et non à l'document contenant. La méthode element.allowsFeature(feature) tient compte de l'attribut "allow", contrairement à document.allowsFeature(feature, origin).

Vérifier l'accès aux fonctionnalités avec document

Pour continuer à utiliser document comme nœud de base, vous devez effectuer une vérification supplémentaire de l'attribut allow sur la balise iFrame.

<iframe id="some-iframe" src="https://example.com" allow="camera"></iframe>

Permissions-Policy: camera=(self "https://example.com")

const isCameraPolicySet = document.featurePolicy.allowsFeature('camera', 'https://example.com')

const someIframeEl = document.getElementById('some-iframe')
const hasCameraAttributeValue = someIframeEl.hasAttribute('allow')
&& someIframeEl.getAttribute('allow').includes('camera')

const isCameraFeatureAllowed = isCameraPolicySet && hasCameraAttributeValue

Au lieu de mettre à jour le code existant à l'aide de document, il est recommandé d'appeler allowsFeature() sur l'objet element, comme dans l'exemple précédent.

API Reporting

L'API Reporting fournit un mécanisme de création de rapports pour les applications Web de manière cohérente. L'API Reporting pour les cas de non-respect des règles sur les autorisations est disponible en tant que fonctionnalité expérimentale.

Si vous souhaitez tester la fonctionnalité expérimentale, suivez la procédure guidée et activez l'indicateur dans chrome://flags/#enable-experimental-web-platform-features. Lorsque l'indicateur est activé, vous pouvez observer les cas de non-respect des règles sur les autorisations dans DevTools, sous l'onglet "Application" :

L'exemple suivant montre comment l'en-tête de l'API Reporting peut être construit:

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;

Dans l'implémentation actuelle, vous pouvez recevoir des rapports sur les cas de non-respect des règles pour tout cas de non-respect qui se produit dans ce cadre en configurant un point de terminaison nommé "default", comme dans l'exemple précédent. Les sous-cadres nécessitent leur propre configuration de création de rapports.

Remarque:Si vous souhaitez que la politique d'autorisations soit prise en charge par défaut dans l'API Reporting, ajoutez votre soutien ou vos commentaires à la discussion.

En savoir plus

Pour en savoir plus sur le règlement sur les autorisations, consultez les ressources suivantes:

• Spécifications de la politique d'autorisations
• Explication de la politique relative aux autorisations
• Liste des fonctionnalités contrôlées par les règles.