Gérez la façon dont votre page et les iFrames tiers présents sur votre page ont accès aux fonctionnalités du navigateur.
Les règles d'autorisation, anciennement appelées règles de fonctionnalités, permettent 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 à appliquer par le navigateur. Ces règles sont appliquées aux origines fournies dans une liste d'origines d'en-tête de réponse. La liste d'origines peut contenir des origines identiques et/ou multi-origines, et permet au développeur de contrôler les accès propriétaires et tiers aux fonctionnalités du navigateur.
L'utilisateur a la décision finale d'autoriser l'accès à des fonctionnalités plus puissantes. Il doit fournir une autorisation explicite via une invite.
Les règles d'autorisation permettent au site de premier niveau de définir ce qu'il et ses tiers ont l'intention d'utiliser, et évite à l'utilisateur de devoir déterminer si la demande d'accès aux fonctionnalités est légitime ou non. Par exemple, en bloquant la fonctionnalité de géolocalisation pour tous les tiers via les règles relatives aux autorisations, le développeur peut être certain qu'aucun tiers n'aura accès à la géolocalisation de l'utilisateur.
Modifications apportées aux règles d'autorisation
Les règles relatives aux autorisations étaient auparavant appelées "règles relatives aux fonctionnalités". Les concepts clés restent les mêmes, mais des changements importants ont été apportés au nom.
Utilisation des champs structurés
Les champs structurés fournissent un ensemble de structures de données courantes permettant de standardiser 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 le protocole HTTP avec des champs d'en-tête structurés.
geolocation 'self' https://example.com; camera 'none'
avec la règle sur les fonctionnalités.
geolocation=(self "https://example.com"), camera=()
et désormais doté d'une règle d'autorisation.
Combiner les en-têtes avec l'attribut iFrame allow
Avec les règles relatives aux fonctionnalités, vous pouvez ajouter la fonctionnalité à un frame multi-origine soit en ajoutant l'origine à la liste d'origine de l'en-tête, soit en ajoutant un attribut allow à la balise iFrame. Avec les règles d'autorisation, si vous ajoutez un cadre multi-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 "Règles d'autorisation", la liste d'origines est considérée comme ayant la valeur par défaut *. 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 des règles d'autorisation dans la réponse, afin que les iFrame multi-origines non répertoriés dans la liste d'origine ne puissent pas accéder à cette fonctionnalité, même si allow est présent.
Les règles de fonctionnalité peuvent toujours être utilisées après Chrome 88, mais elles servent d'alias pour les règles relatives aux autorisations. Hormis la syntaxe, il n'existe aucune différence de logique. Si les en-têtes "Règles d'autorisation" et "Règles de fonctionnalités" sont utilisés ensemble, l'en-tête Permissions-Policy aura une priorité plus élevée et remplacera la valeur fournie par l'en-tête Feature-Policy.
Comment utiliser les règles d'autorisation ?
Présentation rapide
Avant d'entrer dans les détails, examinons un scénario courant où vous êtes le propriétaire d'un site Web et que 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 un iFrame de même origine (
https://your-site.example). - Votre site intègre un iFrame de
https://trusted-site.examplede confiance. - 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 du site de confiance:
<iframe src="https://trusted-site.example" allow="geolocation">
Dans cet exemple, la liste des origines de l'en-tête ne permet qu'à votre site (self) et trusted-site.example d'utiliser la fonctionnalité de géolocalisation. ad.example n'est pas autorisé à utiliser la géolocalisation.
- Votre site
your-site.exampleest autorisé à utiliser la fonctionnalité de géolocalisation avec le consentement de l'utilisateur. - Un iFrame de même origine (
your-site.example) est autorisé à utiliser cette fonctionnalité sans utiliser l'attributallow. - La fonctionnalité est bloquée pour un iFrame diffusé à partir d'un autre sous-domaine (
subdomain.your-site-example) qui n'a pas été ajouté à la liste d'origine et pour lequel l'attribut "allow" est défini sur la balise iFrame. Différents sous-domaines sont considérés comme des sites multi-origines. - Un iFrame multi-origine (
trusted-site.example) qui a été ajouté à la liste d'origine et pour lequel l'attributallowest défini sur la balise iFrame est autorisé à utiliser cette fonctionnalité. - Un iFrame multi-origine (
trusted-site.example) ajouté à la liste d'origine, sans l'attributallow, ne peut pas utiliser cette fonctionnalité. - Un iFrame multi-origine (
ad.example) qui n'a pas été ajouté à la liste d'origines ne peut pas utiliser cette fonctionnalité, même si l'attributallowest 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 un élément géographique. La valeur d'en-tête peut utiliser 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 éléments géographiques, séparez-les par une virgule. Si vous répertoriez plusieurs origines, séparez-les par un espace. Pour les en-têtes qui indiquent une origine correspondant à une requête multi-origine, 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") selfest un raccourci pourhttps://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 la représentation vectorielle continue. Si les autorisations ne sont pas accordées à la page de l'outil d'intégration elle-même, les iFrames intégrés à cette page seront également bloqués, même s'ils sont ajoutés à la liste d'origine, car la règle d'autorisations délègue les autorisations. Vous pouvez également utiliser le jeton
self.
- Syntaxe:
[FEATURE]=()- Fonctionnalité bloquée pour toutes les origines
- Exemple :
geolocation=()
Différents sous-domaines et chemins d'accès
Différents sous-domaines, tels que https://your-site.example et https://subdomain.your-site.example, sont considérés comme sur le même site, mais multi-origines. Par conséquent, l'ajout d'un sous-domaine à la liste d'origine ne permet pas d'accéder à 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 d'origine. Par exemple, si l'accès aux thèmes de navigation de l'utilisateur est autorisé à la même origine uniquement avec l'en-tête Permissions-Policy: browsing-topics=(self), un iFrame d'un autre sous-domaine du même site (https://subdomain.your-site.example) n'aura pas accès aux thèmes.
Les chemins d'accès différents, tels que https://your-site.example et https://your-site.example/embed, sont considérés comme ayant la même origine. Il n'est donc pas nécessaire de les répertorier dans la liste d'origine.
Attribut iFrame allow
Pour une utilisation multi-origine, l'iFrame nécessite l'attribut allow dans la balise pour avoir accès à la fonctionnalité.
Syntaxe : <iframe src="[ORIGIN]" allow="[FEATURE] <'src' | [ORIGIN(s)]"></iframe>
Exemple :
<iframe src="https://trusted-site.example" allow="geolocation">
Gérer la navigation dans iFrame
Par défaut, si un iFrame accède à une autre origine, la règle n'est pas appliquée à l'origine vers laquelle l'iFrame accède. Si vous indiquez l'origine vers laquelle l'iFrame accède dans l'attribut allow, les règles d'autorisation appliquées à l'iFrame d'origine s'appliqueront à l'origine vers laquelle l'iFrame accède.
<iframe src="https://trusted-site.example" allow="geolocation https://trusted-site.example https://trusted-navigated-site.example">
Pour la voir en action, consultez la démonstration de la navigation iFrame.
Exemples de configurations des règles d'autorisation
Les exemples de configurations suivantes sont disponibles 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 tous les iFrames. Dans cet exemple, tout le code diffusé à partir de https://your-site.example, ainsi que 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, lors de l'ajout de l'origine à la liste des origines de l'en-tête.
Cette configuration est illustrée dans la démonstration.
Fonctionnalité autorisée uniquement sur la même origine
Permissions-Policy: geolocation=(self)
L'utilisation du jeton self permet d'utiliser la géolocalisation uniquement vers la même origine. Les utilisateurs issus de plusieurs origines n'auront pas accès à l'élément géographique. 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 sur la même origine et sur des origines multiples spécifiques
Permissions-Policy: geolocation=(self "https://trusted-site.example")
Cette syntaxe permet d'utiliser la géolocalisation à la fois (https://your-site.example) et https://trusted-site.example. N'oubliez pas d'ajouter explicitement l'attribut allow au tag iFrame. S'il existe un autre iFrame avec <iframe src="https://ad.example" allow="geolocation">, https://ad.example n'aura pas accès à la fonctionnalité de géolocalisation. Seules la page d'origine et l'élément https://trusted-site.example listés dans la liste d'origine, avec l'attribut "allow" dans la balise iFrame, ont accès à la fonctionnalité de l'utilisateur.
Cette configuration est illustrée dans la démonstration.
Fonctionnalité bloquée pour toutes les origines
Permissions-Policy: geolocation=()
Si la liste d'origines est vide, la fonctionnalité est bloquée pour toutes les origines. Cette configuration est illustrée dans la démonstration.
Utiliser l'API JavaScript
L'API JavaScript existante de Feature Policy se trouve en tant qu'objet dans le document ou l'élément (document.featurePolicy or element.featurePolicy). L'API JavaScript pour les règles 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 les règles d'autorisation, sous certaines conditions. Il reste des questions concernant l'implémentation de l'API JavaScript, et une proposition a été faite pour déplacer la logique vers l'API Permissions. Participez à la discussion si vous avez des remarques.
featurePolicy.allowsFeature(feature)
- Renvoie
truesi la fonctionnalité est autorisée 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'autorisation et l'ancienne règle relative aux fonctionnalités.
- 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 dans l'iFrame.
featurePolicy.allowsFeature(feature, origin)
- Renvoie
truesi l'élément géographique est autorisé 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 l'a fait la règle de fonctionnalité. Cette méthode vous indique qu'il est possible que la caractéristique soit autorisée à accéder à cette origine. Vous devez vérifier de nouveau si l'attributallowest défini ou non sur l'iFrame. Le développeur doit vérifier l'attributallowde l'élément iFrame afin de 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 une liste de 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 une règle relative aux autorisations et par une règle relative à une fonctionnalité.
- 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 une règle relative aux autorisations et par une règle relative à une fonctionnalité.
Intégration des outils pour les développeurs Chrome
Découvrez le fonctionnement des règles d'autorisation dans les outils de développement.
- Accédez aux outils pour les développeurs Chrome.
- Ouvrez le panneau Application pour vérifier les fonctionnalités autorisées et non autorisées de chaque image.
- Dans la barre latérale, sélectionnez le cadre que vous souhaitez inspecter. Une liste des fonctionnalités que le frame sélectionné est autorisé à utiliser s'affiche, ainsi qu'une liste des fonctionnalités bloquées dans ce frame.
Migration depuis une règle de fonctionnalité
Si vous utilisez actuellement l'en-tête Feature-Policy, vous pouvez implémenter les étapes suivantes pour migrer vers les règles d'autorisation.
Remplacer les en-têtes Feature Policy par des en-têtes de règles d'autorisations
Étant donné que les en-têtes de règles relatives aux fonctionnalités ne sont compatibles qu'avec les navigateurs basés sur Chromium, et que les en-têtes des règles d'autorisation le sont depuis Chrome 88, vous pouvez mettre à jour les en-têtes existants en toute sécurité avec les règles d'autorisation.
Feature-Policy: autoplay *; geolocation 'self'; camera 'self' 'https://trusted-site.example'; fullscreen 'none';
avec la règle sur les fonctionnalités.
Permissions-Policy: autoplay=*, geolocation=(self), camera=(self "https://trusted-site.example"), fullscreen=()
et désormais doté d'une règle d'autorisation.
Mettre à jour 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 la méthode document qui le contient. La méthode element.allowsFeature(feature) prend en compte l'attribut allow, contrairement à document.allowsFeature(feature, origin).
Vérification de l'accès aux fonctionnalités avec document...
Pour continuer à utiliser document comme nœud de base, vous devez vérifier l'attribut allow dans 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 cohérent de création de rapports pour les applications Web. L'API Reporting pour les cas de non-respect des règles d'autorisation est disponible en tant que fonctionnalité expérimentale.
Si vous souhaitez tester la fonctionnalité expérimentale, suivez le tutoriel et activez l'indicateur dans chrome://flags/#enable-experimental-web-platform-features. Lorsque cette option est activée, vous pouvez observer les cas de non-respect des règles relatives aux autorisations dans l'onglet "Application" des outils de développement:
L'exemple suivant montre comment se présente l'en-tête de l'API Reporting:
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 de non-respect des règles pour tout non-respect des règles dans ce frame en configurant un point de terminaison nommé "default", comme dans l'exemple ci-dessus. Les sous-cadres nécessitent leur propre configuration de création de rapports.
En savoir plus
Pour en savoir plus sur les règles d'autorisation, consultez les ressources suivantes: